Merge pull request #2479 from stevepiercy/docs/easy-install-to-pip.2104

Steve Piercy

2016-04-12 278afff7a9bbb42d96ac2199689c3141b9463b9c

Merge pull request #2479 from stevepiercy/docs/easy-install-to-pip.2104

Docs/easy install to pip.2104

 docs/glossary.rst

@@ -1100,10 +1100,16 @@
      checker, and applying a renderer to a dictionary returned from the view.

   pip
      The `Python Packaging Authority <https://www.pypa.io/>`_ recommended tool
      for installing Python packages.
      The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
      tool for installing Python packages.

   pyvenv
      The Python Packaging Authority's recommended command for `creating
      virtual environments on Python 3.4 and greater
      <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`_.
      The Python Packaging Authority formerly recommended using this command
      for `creating virtual environments on Python 3.4 and 3.5
      <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`_,
      but it is deprecated in 3.6 in favor of ``python3 -m venv`` which is
      backward compatible.

   venv
      The `Python Packaging Authority's <https://www.pypa.io/>`_ recommended
      tool for creating virtual environments.

 docs/narr/commandline.rst

@@ -578,10 +578,10 @@
.. versionadded:: 1.5

Each of Pyramid's console scripts (``pserve``, ``pviews``, etc.) can be run
directly using ``python -m``, allowing custom arguments to be sent to the
directly using ``python3 -m``, allowing custom arguments to be sent to the
Python interpreter at runtime. For example::

      python -3 -m pyramid.scripts.pserve development.ini
      python3 -m pyramid.scripts.pserve development.ini


.. index::

 docs/narr/install.rst

@@ -5,8 +5,8 @@

.. note::

    This installation guide now emphasizes the use of Python 3.4 and greater
    for simplicity.
    This installation guide emphasizes the use of Python 3.4 and greater for
    simplicity.


.. index::
@@ -126,8 +126,8 @@
Requirements for Installing Packages
------------------------------------

Use :term:`pip` for installing packages and :term:`pyvenv` for creating a
virtual environment. A virtual environment is a semi-isolated Python
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.

@@ -155,7 +155,7 @@
   .. code-block:: bash

      $ export VENV=~/env
      $ pyvenv $VENV
      $ python3 -m venv $VENV

   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
@@ -190,7 +190,7 @@

      c:\> set VENV=c:\env
      # replace "x" with your minor version of Python 3
      c:\> c:\Python3x\Scripts\pyvenv %VENV%
      c:\> c:\Python3x\Scripts\python3 -m venv %VENV%

   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

 docs/quick_tour.rst

@@ -25,7 +25,7 @@

.. parsed-literal::

    $ pyvenv env
    $ python3 -m venv env
    $ env/bin/pip install pyramid
    # or for a specific released version
    $ env/bin/pip install "pyramid==\ |release|\ "
@@ -34,7 +34,7 @@

.. parsed-literal::

    c:\\> c:\\Python35\\python -m venv env
    c:\\> c:\\Python35\\python3 -m venv env
    c:\\> env\\Scripts\\pip install pyramid
    # or for a specific released version
    c:\\> env\\Scripts\\pip install "pyramid==\ |release|\ "

 docs/quick_tutorial/requirements.rst

@@ -22,9 +22,9 @@
* **Python 3.5**. Pyramid fully supports Python 3.3+ and Python 2.6+. 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.5'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 ``venv``. For Python 2.7, you can install
  ``virtualenv``.

* **pip**. We use ``pip`` for package management.

@@ -158,26 +158,20 @@
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 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

.. code-block:: ps1con

    # Windows
    c:\> c:\Python35\python -m venv %VENV%
    c:\> c:\Python35\python3 -m venv %VENV%

.. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
   2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ package.