diff options
Diffstat (limited to 'docs/quick_tutorial/requirements.rst')
| -rw-r--r-- | docs/quick_tutorial/requirements.rst | 259 |
1 files changed, 102 insertions, 157 deletions
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index b5778ea42..a74c07673 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -4,79 +4,67 @@ Requirements ============ -Let's get our tutorial environment setup. Most of the setup work is in -standard Python development practices (install Python, -make an isolated environment, and setup packaging tools.) +Let's get our tutorial environment set up. Most of the set up work is in +standard Python development practices (install Python and make an isolated +virtual environment.) .. note:: - Pyramid encourages standard Python development practices with - packaging tools, virtual environments, logging, and so on. There - are many variations, implementations, and opinions across the Python - community. For consistency, ease of documentation maintenance, - and to minimize confusion, the Pyramid *documentation* has adopted - specific conventions. + Pyramid encourages standard Python development practices with packaging + tools, virtual environments, logging, and so on. There are many variations, + implementations, and opinions across the Python community. For consistency, + ease of documentation maintenance, and to minimize confusion, the Pyramid + *documentation* has adopted specific conventions that are consistent with the + :term:`Python Packaging Authority`. This *Quick Tutorial* is based on: -* **Python 3.3**. Pyramid fully supports Python 3.2+ and Python 2.6+. - This tutorial uses **Python 3.3** but runs fine under Python 2.7. +* **Python 3.7**. Pyramid fully supports Python 3.4+ and Python 2.7+. This + tutorial uses **Python 3.7** but runs fine under Python 2.7. -* **pyvenv**. We believe in virtual environments. For this tutorial, - we use Python 3.3's built-in solution, the ``pyvenv`` command. - For Python 2.7, you can install ``virtualenv``. +* **venv**. We believe in virtual environments. For this tutorial, we use + Python 3's built-in solution :term:`venv`. For Python 2.7, you can install + :term:`virtualenv`. -* **setuptools and easy_install**. We use - `setuptools <https://pypi.python.org/pypi/setuptools/>`_ - and its ``easy_install`` for package management. +* **pip**. We use :term:`pip` for package management. -* **Workspaces, projects, and packages.** Our home directory - will contain a *tutorial workspace* with our Python virtual - environment(s) and *Python projects* (a directory with packaging - information and *Python packages* of working code.) +* **Workspaces, projects, and packages.** Our home directory will contain a + *tutorial workspace* with our Python virtual environment and *Python + projects* (a directory with packaging information and *Python packages* of + working code.) -* **Unix commands**. Commands in this tutorial use UNIX syntax and - paths. Windows users should adjust commands accordingly. +* **Unix commands**. Commands in this tutorial use Unix syntax and paths. + Windows users should adjust commands accordingly. .. note:: - Pyramid was one of the first web frameworks to fully support Python 3 in October 2011. +.. note:: + Windows commands use the plain old MSDOS shell. For PowerShell command + syntax, see its documentation. + Steps ===== -#. :ref:`install-python-3.3-or-greater` +#. :ref:`install-python-3` #. :ref:`create-a-project-directory-structure` #. :ref:`set-an-environment-variable` #. :ref:`create-a-virtual-environment` -#. :ref:`install-setuptools-(python-packaging-tools)` #. :ref:`install-pyramid` -.. _install-python-3.3-or-greater: -Install Python 3.3 or greater ------------------------------ +.. _install-python-3: -Download the latest standard Python 3.3+ release (not development -release) from -`python.org <http://www.python.org/download/releases/>`_. On that page, you -must click the latest version, then scroll down to the "Downloads" section -for your operating system. +Install Python 3 +---------------- -Windows and Mac OS X users can download and run an installer. +See the detailed recommendation for your operating system described under +:ref:`installing_chapter`. -Windows users should also 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. - -Linux users can either use their package manager to install Python 3.3 -or may -`build Python 3.3 from source -<http://pyramid.readthedocs.org/en/master/narr/install.html#package-manager- -method>`_. +- :ref:`for-macos-users` +- :ref:`if-you-don-t-yet-have-a-python-interpreter-unix` +- :ref:`if-you-don-t-yet-have-a-python-interpreter-windows` .. _create-a-project-directory-structure: @@ -84,126 +72,115 @@ method>`_. Create a project directory structure ------------------------------------ -We will arrive at a directory structure of -``workspace->project->package``, with our workspace named -``quick_tutorial``. The following diagram shows how this is structured -and where our virtual environment will reside: +We will arrive at a directory structure of ``workspace -> project -> package``, +where our workspace is named ``quick_tutorial``. The following tree diagram +shows how this will be structured, and where our :term:`virtual environment` +will reside as we proceed through the tutorial: -.. figure:: ../_static/directory_structure_pyramid.png - :alt: Final directory structure +.. code-block:: text - Final directory structure. + ~ + └── projects + └── quick_tutorial + ├── env + └── step_one + ├── intro + │ ├── __init__.py + │ └── app.py + └── setup.py -For Linux, the commands to do so are as follows: +For macOS and Linux, the commands to do so are as follows: .. code-block:: bash - # Mac and Linux - $ cd ~ - $ mkdir -p projects/quick_tutorial - $ cd projects/quick_tutorial + # macOS and Linux + cd ~ + mkdir -p projects/quick_tutorial + cd projects/quick_tutorial For Windows: -.. code-block:: posh +.. code-block:: doscon # Windows - c:\> cd \ - c:\> mkdir projects\quick_tutorial - c:\> cd projects\quick_tutorial + cd \ + mkdir projects\quick_tutorial + cd projects\quick_tutorial -In the above figure, your user home directory is represented by ``~``. In -your home directory, all of your projects are in the ``projects`` directory. -This is a general convention not specific to Pyramid that many developers use. -Windows users will do well to use ``c:\`` as the location for ``projects`` in -order to avoid spaces in any of the path names. +In the above figure, your user home directory is represented by ``~``. In your +home directory, all of your projects are in the ``projects`` directory. This is +a general convention not specific to Pyramid that many developers use. Windows +users will do well to use ``c:\`` as the location for ``projects`` in order to +avoid spaces in any of the path names. Next within ``projects`` is your workspace directory, here named ``quick_tutorial``. A workspace is a common term used by integrated -development environments (IDE) like PyCharm and PyDev that stores -isolated Python environments (virtualenvs) and specific project files -and repositories. +development environments (IDE), like PyCharm and PyDev, where virtual +environments, specific project files, and repositories are stored. .. _set-an-environment-variable: -Set an Environment Variable +Set an environment variable --------------------------- -This tutorial will refer frequently to the location of the virtual -environment. We set an environment variable to save typing later. +This tutorial will refer frequently to the location of the :term:`virtual +environment`. We set an environment variable to save typing later. .. code-block:: bash - # Mac and Linux - $ export VENV=~/projects/quick_tutorial/env33/ + # macOS and Linux + export VENV=~/projects/quick_tutorial/env + +.. code-block:: doscon # Windows - # TODO: This command does not work - c:\> set VENV=c:\projects\quick_tutorial\env33 + set VENV=c:\projects\quick_tutorial\env .. _create-a-virtual-environment: -Create a Virtual Environment +Create a virtual environment ---------------------------- -.. warning:: The current state of isolated Python environments using - ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See - http://stackoverflow.com/q/15981111/95735 for a discussion of the issue - and `PEP 453 <http://www.python.org/dev/peps/pep-0453/>`_ for a proposed - resolution. - -``pyvenv`` is a tool to create isolated Python 3.3 environments, each -with its own Python binary and independent set of installed Python -packages in its site directories. Let's create one, using the location -we just specified in the environment variable. +``venv`` is a tool to create isolated Python 3 environments, each with its own +Python binary and independent set of installed Python packages in its site +directories. Let's create one, using the location we just specified in the +environment variable. .. code-block:: bash - # Mac and Linux - $ pyvenv $VENV + # macOS and Linux + python3 -m venv $VENV - # Windows - c:\> c:\Python33\python -m venv %VENV% +.. code-block:: doscon -.. seealso:: See also Python 3's :mod:`venv module <python3:venv>`, - Python 2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ - package, - :ref:`Installing Pyramid on a Windows System <installing_windows>` + # Windows + python -m venv %VENV% +.. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python + 2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package. -.. _install-setuptools-(python-packaging-tools): -Install ``setuptools`` (Python packaging tools) ------------------------------------------------ +Update packaging tools in the virtual environment +------------------------------------------------- -The following command will download a script to install ``setuptools``, then -pipe it to your environment's version of Python. +It's always a good idea to update to the very latest version of packaging tools +because the installed Python bundles only the version that was available at the +time of its release. .. code-block:: bash - # Mac and Linux - $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python - - # Windows - # - # Use your web browser to download this file: - # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py - # - # ...and save it to: - # c:\projects\quick_tutorial\ez_setup.py - # - # Then run the following command: - - c:\> %VENV%\Scripts\python ez_setup.py + # macOS and Linux + $VENV/bin/pip install --upgrade pip setuptools -If ``wget`` complains with a certificate error, then run this command instead: +.. code-block:: doscon -.. code-block:: bash + # Windows + %VENV%\Scripts\pip install --upgrade pip setuptools - # Mac and Linux - $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python +.. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source + bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`. .. _install-pyramid: @@ -212,48 +189,16 @@ Install Pyramid --------------- We have our Python standard prerequisites out of the way. The Pyramid -part is pretty easy: +part is pretty easy. We'll also install a WSGI server, Waitress. .. parsed-literal:: - # Mac and Linux - $ $VENV/bin/easy_install "pyramid==\ |release|\ " + # macOS and Linux + $VENV/bin/pip install "pyramid==\ |release|\ " waitress # Windows - c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " - -Our Python virtual environment now has the Pyramid software available. - -You can optionally install some of the extra Python packages used -during this tutorial: - -.. code-block:: bash - - # Mac and Linux - $ $VENV/bin/easy_install nose webtest deform sqlalchemy \ - pyramid_chameleon pyramid_debugtoolbar waitress \ - pyramid_tm zope.sqlalchemy - - # Windows - c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar waitress pyramid_tm zope.sqlalchemy - - -.. note:: + %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " waitress - Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace - packages, for which ``pip``'s support is less-than-optimal. Also, Pyramid's - dependencies use some optional C extensions for performance: with - ``easy_install``, Windows users can get these extensions without needing - a C compiler (``pip`` does not support installing binary Windows - distributions, except for ``wheels``, which are not yet available for - all dependencies). - -.. seealso:: See also :ref:`installing_unix`. For instructions to set up your - Python environment for development using Windows or Python 2, see Pyramid's - :ref:`Before You Install <installing_chapter>`. - - See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools - installation instructions - <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_, - and `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_. +Our Python virtual environment now has the Pyramid software available +as well as the ``waitress`` package. |