diff options
Diffstat (limited to 'docs/quick_tutorial/requirements.rst')
| -rw-r--r-- | docs/quick_tutorial/requirements.rst | 213 |
1 files changed, 82 insertions, 131 deletions
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst index f855dcb55..1f2b4da97 100644 --- a/docs/quick_tutorial/requirements.rst +++ b/docs/quick_tutorial/requirements.rst @@ -4,75 +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.3+ and Python 2.6+. - This tutorial uses **Python 3.3** but runs fine under Python 2.7. +* **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.7+. This + tutorial uses **Python 3.5** 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.5'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 <https://www.python.org/downloads/>`_. +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-mac-os-x-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: @@ -80,11 +72,10 @@ 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 tree diagram shows how this will be -structured and where our virtual environment will reside as we proceed through -the tutorial: +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: .. code-block:: text @@ -109,105 +100,84 @@ For Linux, the commands to do so are as follows: For Windows: -.. code-block:: ps1con +.. code-block:: doscon # Windows c:\> cd \ c:\> mkdir projects\quick_tutorial c:\> 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/env +.. code-block:: doscon + # Windows - # TODO: This command does not work c:\> 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 + $ 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 + c:\> c:\Python35\python3 -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 + $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 - - # Mac and Linux - $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python + # Windows + c:\> %VENV%\Scripts\pip install --upgrade pip setuptools .. _install-pyramid: @@ -216,48 +186,29 @@ Install Pyramid --------------- We have our Python standard prerequisites out of the way. The Pyramid -part is pretty easy: +part is pretty easy. .. parsed-literal:: # Mac and Linux - $ $VENV/bin/easy_install "pyramid==\ |release|\ " + $ $VENV/bin/pip install "pyramid==\ |release|\ " # Windows - c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " + c:\\> %VENV%\\Scripts\\pip 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: +You can optionally install some of the extra Python packages used in 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 + $ $VENV/bin/pip install webtest pytest pytest-cov deform sqlalchemy \ + pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress \ + pyramid_tm zope.sqlalchemy +.. code-block:: doscon -.. note:: - - 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>`_. - + # Windows + c:\> %VENV%\Scripts\pip install webtest deform sqlalchemy pyramid_chameleon pyramid_debugtoolbar pyramid_jinja2 waitress pyramid_tm zope.sqlalchemy |