diff options
Diffstat (limited to 'docs/narr/install.rst')
| -rw-r--r-- | docs/narr/install.rst | 458 |
1 files changed, 169 insertions, 289 deletions
diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a825b61b9..248b432d3 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -1,309 +1,221 @@ .. _installing_chapter: Installing :app:`Pyramid` -============================ +========================= + +.. note:: + + This installation guide emphasizes the use of Python 3.4 and greater for + simplicity. + .. index:: single: install preparation -Before You Install ------------------- +Before You Install Pyramid +-------------------------- -You will need `Python <http://python.org>`_ version 2.6 or better to run -:app:`Pyramid`. +Install Python version 3.4 or greater for your operating system, and satisfy +the :ref:`requirements-for-installing-packages`, as described in +the following sections. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` has been tested under Python 2.6, Python - 2.7, Python 3.2, Python 3.3, Python 3.4 and PyPy 2.2. :app:`Pyramid` does - not run under any version of Python before 2.6. + As of this writing, :app:`Pyramid` is tested against Python 2.7, + Python 3.4, Python 3.5, Python 3.6, Python 3.7, and PyPy. -:app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, -Mac OS X, and FreeBSD as well as on Windows platforms. It is also known to run -on :term:`PyPy` (1.9+). +:app:`Pyramid` is known to run on all popular Unix-like systems such as Linux, +macOS, and FreeBSD, as well as on Windows platforms. It is also known to +run on :term:`PyPy` (1.9+). -:app:`Pyramid` installation does not require the compilation of any C code, so -you need only a Python interpreter that meets the requirements mentioned. +:app:`Pyramid` installation does not require the compilation of any C code. +However, some :app:`Pyramid` dependencies may attempt to build binary +extensions from C code for performance speed ups. If a compiler or Python +headers are unavailable, the dependency will fall back to using pure Python +instead. -Some :app:`Pyramid` dependencies may attempt to build C extensions for -performance speedups. If a compiler or Python headers are unavailable the -dependency will fall back to using pure Python instead. +.. note:: -For Mac OS X Users -~~~~~~~~~~~~~~~~~~ + If you see any warnings or errors related to failing to compile the binary + extensions, in most cases you may safely ignore those errors. If you wish to + use the binary extensions, please verify that you have a functioning + compiler and the Python header files installed for your operating system. -Python comes pre-installed on Mac OS X, but due to Apple's release cycle, -it is often out of date. Unless you have a need for a specific earlier version, -it is recommended to install the latest 2.x or 3.x version of Python. -You can install the latest verion of Python for Mac OS X from the binaries on -`python.org <https://www.python.org/download/mac/>`_. +.. _for-macos-users: -Alternatively, you can use the `homebrew <http://brew.sh/>`_ package manager. +For macOS Users +~~~~~~~~~~~~~~~ -.. code-block:: text +Python comes pre-installed on macOS, but due to Apple's release cycle, it is +often out of date. Unless you have a need for a specific earlier version, it is +recommended to install the latest 3.x version of Python. - # for python 2.7 - $ brew install python +You can install the latest version of Python for macOS from the binaries on +`python.org <https://www.python.org/downloads/mac-osx/>`_. - # for python 3.4 - $ brew install python3 +Alternatively, you can use the `homebrew <https://brew.sh/>`_ package manager. + +.. code-block:: bash + + # for python 3.x + brew install python3 If you use an installer for your Python, then you can skip to the section :ref:`installing_unix`. -If You Don't Yet Have A Python Interpreter (UNIX) + +.. _if-you-don-t-yet-have-a-python-interpreter-unix: + +If You Don't Yet Have a Python Interpreter (Unix) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your system doesn't have a Python interpreter, and you're on UNIX, you can +If your system doesn't have a Python interpreter, and you're on Unix, you can either install Python using your operating system's package manager *or* you -can install Python from source fairly easily on any UNIX system that has +can install Python from source fairly easily on any Unix system that has development tools. -.. index:: - pair: install; Python (from package, UNIX) - -Package Manager Method -++++++++++++++++++++++ - -You can use your system's "package manager" to install Python. Each package -manager is slightly different, but the "flavor" of them is usually the same. - -For example, on a Debian or Ubuntu system, use the following command: - -.. code-block:: text - - $ sudo apt-get install python2.7-dev - -This command will install both the Python interpreter and its development -header files. Note that the headers are required by some (optional) C -extensions in software depended upon by Pyramid, not by Pyramid itself. - -Once these steps are performed, the Python interpreter will usually be -invokable via ``python2.7`` from a shell prompt. - -.. index:: - pair: install; Python (from source, UNIX) - -Source Compile Method -+++++++++++++++++++++ - -It's useful to use a Python interpreter that *isn't* the "system" Python -interpreter to develop your software. The authors of :app:`Pyramid` tend not -to use the system Python for development purposes; always a self-compiled one. -Compiling Python is usually easy, and often the "system" Python is compiled -with options that aren't optimal for web development. For an explanation, see -https://github.com/Pylons/pyramid/issues/747. - -To compile software on your UNIX system, typically you need development tools. -Often these can be installed via the package manager. For example, this works -to do so on an Ubuntu Linux system: - -.. code-block:: text - - $ sudo apt-get install build-essential - -On Mac OS X, installing `XCode <http://developer.apple.com/tools/xcode/>`_ has -much the same effect. - -Once you've got development tools installed on your system, you can install a -Python 2.7 interpreter from *source*, on the same system, using the following -commands: - -.. code-block:: text +.. seealso:: See the official Python documentation :ref:`Using Python on Unix + platforms <python:using-on-unix>` for full details. - $ cd ~ - $ mkdir tmp - $ mkdir opt - $ cd tmp - $ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz - $ tar xvzf Python-2.7.3.tgz - $ cd Python-2.7.3 - $ ./configure --prefix=$HOME/opt/Python-2.7.3 - $ make && make install - -Once these steps are performed, the Python interpreter will be invokable via -``$HOME/opt/Python-2.7.3/bin/python`` from a shell prompt. .. index:: pair: install; Python (from package, Windows) -If You Don't Yet Have A Python Interpreter (Windows) +.. _if-you-don-t-yet-have-a-python-interpreter-windows: + +If You Don't Yet Have a Python Interpreter (Windows) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your Windows system doesn't have a Python interpreter, you'll need to -install it by downloading a Python 2.7-series interpreter executable from -`python.org's download section <http://python.org/download/>`_ (the files +install it by downloading a Python 3.x-series interpreter executable from +`python.org's download section <https://www.python.org/downloads/>`_ (the files labeled "Windows Installer"). Once you've downloaded it, double click on the -executable and accept the defaults during the installation process. You may -also need to download and install the Python for Windows extensions. - -.. warning:: - - After you install Python on Windows, you may need to add the ``C:\Python27`` - directory to your environment's ``Path`` in order to make it possible to - invoke Python from a command prompt by typing ``python``. To do so, right - click ``My Computer``, select ``Properties`` --> ``Advanced Tab`` --> - ``Environment Variables`` and add that directory to the end of the ``Path`` - environment variable. - -.. index:: - single: installing on UNIX - -.. _installing_unix: - -Installing :app:`Pyramid` on a UNIX System ---------------------------------------------- - -It is best practice to install :app:`Pyramid` into a "virtual" Python -environment in order to obtain isolation from any "system" packages you've got -installed in your Python version. This can be done by using the -:term:`virtualenv` package. Using a virtualenv will also prevent -:app:`Pyramid` from globally installing versions of packages that are not -compatible with your system Python. - -To set up a virtualenv in which to install :app:`Pyramid`, first ensure that -:term:`setuptools` is installed. To do so, invoke ``import setuptools`` within -the Python interpreter you'd like to run :app:`Pyramid` under. - -The following command will not display anything if setuptools is already -installed: - -.. code-block:: text - - $ python2.7 -c 'import setuptools' - -Running the same command will yield the following output if setuptools is not -yet installed: - -.. code-block:: text - - Traceback (most recent call last): - File "<stdin>", line 1, in <module> - ImportError: No module named setuptools - -If ``import setuptools`` raises an :exc:`ImportError` as it does above, you -will need to install setuptools manually. - -If you are using a "system" Python (one installed by your OS distributor or a -third-party packager such as Fink or MacPorts), you can usually install the -setuptools package by using your system's package manager. If you cannot do -this, or if you're using a self-installed version of Python, you will need to -install setuptools "by hand". Installing setuptools "by hand" is always a -reasonable thing to do, even if your package manager already has a pre-chewed -version of setuptools for installation. +executable and select appropriate options during the installation process. To +standardize this documentation, we used the GUI installer and selected the +following options: + +- Screen 1: Install Python 3.x.x (32- or 64-bit) + - Check "Install launcher for all users (recommended)". + - Check "Add Python 3.x to PATH". + - Click "Install Now". +- Screen 2: User Account Control + - Click "Yes". + +.. seealso:: See the official Python documentation :ref:`Using Python on + Windows <python:using-on-windows>` for full details. + +.. seealso:: You might also need to download and install the `Python for + Windows extensions + <https://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read + the README.txt file at the end of the list of builds, and follow its + directions. Make sure you get the proper 32- or 64-bit build and Python + version. -Installing Setuptools -~~~~~~~~~~~~~~~~~~~~~ +.. seealso:: `Python launcher for Windows + <https://docs.python.org/3/using/windows.html#launcher>`_ provides a command + ``py`` that allows users to run any installed version of Python. -To install setuptools by hand under Python 2, first download `ez_setup.py -<https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ then invoke -it using the Python interpreter into which you want to install setuptools. +.. warning:: After you install Python on Windows, you might need to add the + directory where Python and other programs—such as pip, :term:`Setuptools`, and + cookiecutter—are installed to your environment's ``Path``. This will make it + possible to invoke them from a command prompt. -.. code-block:: text + To do so, search for "Environment Variables" on your computer (on Windows + 10, it is under ``System Properties`` --> ``Advanced``) and add that + directory to the ``Path`` environment variable, using the GUI to edit path + segments. - $ python ez_setup.py + Example segments should look like + ``C:\Users\<username>\AppData\Local\Programs\Python3x-32``, where you have + your username instead of ``<username>``, and your version of Python and + whether it is 32- or 64-bit. Additionally ensure you have the path segment + ending with ``\Scripts``, i.e., + ``C:\Users\<username>\AppData\Local\Programs\Python3x-32\Scripts``, and for + user-installed Python programs, ``%APPDATA%\Python\Python3x\Scripts``. -Once this command is invoked, setuptools should be installed on your system. -If the command fails due to permission errors, you may need to be the -administrative user on your system to successfully invoke the script. To -remediate this, you may need to do: + You may need to restart your command prompt session to load the environment + variables. -.. code-block:: text + .. seealso:: See `Configuring Python (on Windows) + <https://docs.python.org/3/using/windows.html#configuring-python>`_ for + full details. - $ sudo python ez_setup.py .. index:: - pair: install; virtualenv + single: requirements for installing packages -Installing the ``virtualenv`` Package -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _requirements-for-installing-packages: -Once you've got setuptools installed, you should install the :term:`virtualenv` -package. To install the :term:`virtualenv` package into your -setuptools-enabled Python interpreter, use the ``easy_install`` command. +Requirements for Installing Packages +------------------------------------ -.. warning:: +Use :term:`pip` for installing packages and ``python3 -m venv env`` for +creating a virtual environment. A virtual environment is a semi-isolated Python +environment that allows packages to be installed for use by a particular +application, rather than being installed system wide. - Python 3.3 includes ``pyvenv`` out of the box, which provides similar - functionality to ``virtualenv``. We however suggest using ``virtualenv`` - instead, which works well with Python 3.3. This isn't a recommendation made - for technical reasons; it's made because it's not feasible for the authors - of this guide to explain setup using multiple virtual environment systems. - We are aiming to not need to make the installation documentation - Turing-complete. +.. seealso:: See the Python Packaging Authority's (PyPA) documention + `Requirements for Installing Packages + <https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages>`_ + for full details. - If you insist on using ``pyvenv``, you'll need to understand how to install - software such as ``setuptools`` into the virtual environment manually, which - this guide does not cover. -.. code-block:: text - - $ easy_install virtualenv - -This command should succeed, and tell you that the virtualenv package is now -installed. If it fails due to permission errors, you may need to install it as -your system's administrative user. For example: +.. index:: + single: installing on Unix + single: installing on macOS -.. code-block:: text +.. _installing_unix: - $ sudo easy_install virtualenv +Installing :app:`Pyramid` on a Unix System +------------------------------------------ -.. index:: - single: virtualenv - pair: Python; virtual environment +After installing Python as described previously in :ref:`for-macos-users` or +:ref:`if-you-don-t-yet-have-a-python-interpreter-unix`, and satisfying the +:ref:`requirements-for-installing-packages`, you can now install Pyramid. -Creating the Virtual Python Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#. Make a :term:`virtual environment` workspace: -Once the :term:`virtualenv` package is installed in your Python environment, -you can then create a virtual environment. To do so, invoke the following: + .. code-block:: bash -.. code-block:: text + export VENV=~/env + python3 -m venv $VENV - $ export VENV=~/env - $ virtualenv $VENV - New python executable in /home/foo/env/bin/python - Installing setuptools.............done. + You can either follow the use of the environment variable ``$VENV``, or + replace it with the root directory of the virtual environment. If you choose + the former approach, ensure that ``$VENV`` is an absolute path. In the + latter case, the ``export`` command can be skipped. -You can either follow the use of the environment variable, ``$VENV``, or -replace it with the root directory of the :term:`virtualenv`. In that case, the -`export` command can be skipped. If you choose the former approach, ensure that -it's an absolute path. +#. (Optional) Consider using ``$VENV/bin/activate`` to make your shell + environment wired to use the virtual environment. -.. warning:: +#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: - Avoid using the ``--system-site-packages`` option when creating the - virtualenv unless you know what you are doing. For versions of virtualenv - prior to 1.7, make sure to use the ``--no-site-packages`` option, because - this option was formerly not the default and may produce undesirable - results. + .. parsed-literal:: -.. warning:: + $VENV/bin/pip install "pyramid==\ |release|\ " - *do not* use ``sudo`` to run the ``virtualenv`` script. It's perfectly - acceptable (and desirable) to create a virtualenv as a normal user. +.. index:: + single: $VENV/bin/pip vs. source bin/activate +.. _venv-bin-pip-vs-source-bin-activate: -Installing :app:`Pyramid` Into the Virtual Python Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then + ``pip``? -After you've got your virtualenv installed, you may install :app:`Pyramid` -itself using the following commands: + ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the + virtual environment and not at the system level. -.. parsed-literal:: - - $ $VENV/bin/easy_install "pyramid==\ |release|\ " + ``activate`` makes changes to the user's shell environment which can often be convenient. However, in the context of long-form documentation, environment configuration can easily be forgotten. By keeping each snippet explicit we can reduce copy / paste errors by users in which commands are executed against the wrong Python environment. Also, ``deactivate`` might not correctly restore previous shell environment variables. Avoiding ``activate`` keeps the environment more reproducible. -The ``easy_install`` command will take longer than the previous ones to -complete, as it downloads and installs a number of dependencies. + Although using ``source bin/activate``, then ``pip``, requires fewer key + strokes to issue commands once invoked, there are other things to consider. + Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate + is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_. -.. note:: + Ultimately we prefer to keep things clear and simple, so we use + ``$VENV/bin/pip``. - If you see any warnings and/or errors related to failing to compile the C - extensions, in most cases you may safely ignore those errors. If you wish - to use the C extensions, please verify that you have a functioning compiler - and the Python header files installed. .. index:: single: installing on Windows @@ -311,75 +223,43 @@ complete, as it downloads and installs a number of dependencies. .. _installing_windows: Installing :app:`Pyramid` on a Windows System -------------------------------------------------- - -You can use Pyramid on Windows under Python 2 or 3. - -#. Download and install the most recent `Python 2.7.x or 3.3.x version - <http://www.python.org/download/>`_ for your system. - -#. Download and install the `Python for Windows extensions - <http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read - the README.txt file at the end of the list of builds, and follow its - directions. Make sure you get the proper 32- or 64-bit build and Python - version. - -#. Install latest :term:`setuptools` distribution into the Python from step 1 - above: download `ez_setup.py - <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ and run - it using the ``python`` interpreter of your Python 2.7 or 3.3 installation - using a command prompt: - - .. code-block:: text +--------------------------------------------- - # modify the command according to the python version, e.g.: - # for Python 2.7: - c:\> c:\Python27\python ez_setup.py - # for Python 3.3: - c:\> c:\Python33\python ez_setup.py +After installing Python as described previously in +:ref:`if-you-don-t-yet-have-a-python-interpreter-windows`, and satisfying the +:ref:`requirements-for-installing-packages`, you can now install Pyramid. -#. Install `virtualenv`: +#. Make a :term:`virtual environment` workspace: - .. code-block:: text + .. code-block:: doscon - # modify the command according to the python version, e.g.: - # for Python 2.7: - c:\> c:\Python27\Scripts\easy_install virtualenv - # for Python 3.3: - c:\> c:\Python33\Scripts\easy_install virtualenv + cd \ + set VENV=c:\env + python -m venv %VENV% + cd %VENV% -#. Make a :term:`virtualenv` workspace: + You can either follow the use of the environment variable ``%VENV%``, or + replace it with the root directory of the virtual environment. If you choose + the former approach, ensure that ``%VENV%`` is an absolute path. In the + latter case, the ``set`` command can be skipped. - .. code-block:: text +#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell + environment wired to use the virtual environment. - c:\> set VENV=c:\env - # modify the command according to the python version, e.g.: - # for Python 2.7: - c:\> c:\Python27\Scripts\virtualenv %VENV% - # for Python 3.3: - c:\> c:\Python33\Scripts\virtualenv %VENV% +#. Use ``pip`` to get :app:`Pyramid` and its direct dependencies installed: - You can either follow the use of the environment variable, ``%VENV%``, or - replace it with the root directory of the :term:`virtualenv`. In that case, - the `set` command can be skipped. If you choose the former approach, ensure - that it's an absolute path. + .. parsed-literal:: -#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell - environment wired to use the virtualenv. + %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " -#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies - installed: +.. note:: See the note above for :ref:`Why use $VENV/bin/pip instead of source + bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`. - .. parsed-literal:: - - c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " What Gets Installed ------------------- -When you ``easy_install`` :app:`Pyramid`, various other libraries such as -WebOb, PasteDeploy, and others are installed. - -Additionally, as chronicled in :ref:`project_narr`, scaffolds will be -registered, which make it easy to start a new :app:`Pyramid` project. +When you install :app:`Pyramid`, various libraries such as WebOb, PasteDeploy, +and others are installed. +Additionally, as chronicled in :ref:`project_narr`, our :term:`cookiecutter` will be used, which makes it easy to start a new :app:`Pyramid` project. |