Issue #27285: Document the deprecation of the pyvenv script.

As part of the update, the documentation was updated to normalize
around the term "virtual environment" instead of relying too heavily
on "venv" for the same meaning and leading to inconsistent usage of
either.

Thanks to Steve Piercy for the patch.

Doc/glossary.rst

@@ -970,7 +970,7 @@ Glossary
       without interfering with the behaviour of other Python applications
       running on the same system.
 
-      See also :ref:`scripts-pyvenv`.
+      See also :mod:`venv`.
 
    virtual machine
       A computer defined entirely in software.  Python's virtual machine

Doc/installing/index.rst

@@ -2,9 +2,9 @@
 
 .. _installing-index:
 
-*****************************
-  Installing Python Modules
-*****************************
+*************************
+Installing Python Modules
+*************************
 
 :Email: distutils-sig@python.org
 
@@ -34,24 +34,24 @@ Key terms
 
 * ``pip`` is the preferred installer program. Starting with Python 3.4, it
   is included by default with the Python binary installers.
-* a virtual environment is a semi-isolated Python environment that allows
+* 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
-* ``pyvenv`` is the standard tool for creating virtual environments, and has
+  being installed system wide.
+* ``venv`` is the standard tool for creating virtual environments, and has
   been part of Python since Python 3.3. Starting with Python 3.4, it
-  defaults to installing ``pip`` into all created virtual environments
+  defaults to installing ``pip`` into all created virtual environments.
 * ``virtualenv`` is a third party alternative (and predecessor) to
-  ``pyvenv``. It allows virtual environments to be used on versions of
-  Python prior to 3.4, which either don't provide ``pyvenv`` at all, or
+  ``venv``. It allows virtual environments to be used on versions of
+  Python prior to 3.4, which either don't provide ``venv`` at all, or
   aren't able to automatically install ``pip`` into created environments.
-* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
+* The `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public
   repository of open source licensed packages made available for use by
-  other Python users
+  other Python users.
 * the `Python Packaging Authority
   <https://www.pypa.io/en/latest/>`__ are the group of
   developers and documentation authors responsible for the maintenance and
   evolution of the standard packaging tools and the associated metadata and
-  file format standards. They maintain a variety of tools, documentation
+  file format standards. They maintain a variety of tools, documentation,
   and issue trackers on both `GitHub <https://github.com/pypa>`__ and
   `BitBucket <https://bitbucket.org/pypa/>`__.
 * ``distutils`` is the original build and distribution system first added to
@@ -62,6 +62,19 @@ Key terms
   of the mailing list used to coordinate Python packaging standards
   development).
 
+.. deprecated:: 3.6
+   ``pyvenv`` was the recommended tool for creating virtual environments for
+   Python 3.3 and 3.4, and is `deprecated in Python 3.6
+   <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
+
+.. versionchanged:: 3.5
+   The use of ``venv`` is now recommended for creating virtual environments.
+
+.. seealso::
+
+   `Python Packaging User Guide: Creating and using virtual environments
+   <https://packaging.python.org/installing/#creating-virtual-environments>`__
+
 
 Basic usage
 ===========
@@ -100,13 +113,14 @@ explicitly::
 More information and resources regarding ``pip`` and its capabilities can be
 found in the `Python Packaging User Guide <https://packaging.python.org>`__.
 
-``pyvenv`` has its own documentation at :ref:`scripts-pyvenv`. Installing
-into an active virtual environment uses the commands shown above.
+Creation of virtual environments is done through the :mod:`venv` module.
+Installing packages into an active virtual environment uses the commands shown
+above.
 
 .. seealso::
 
     `Python Packaging User Guide: Installing Python Distribution Packages
-    <https://packaging.python.org/en/latest/installing/>`__
+    <https://packaging.python.org/installing/>`__
 
 
 How do I ...?
@@ -124,7 +138,7 @@ User Guide.
 .. seealso::
 
    `Python Packaging User Guide: Requirements for Installing Packages
-   <https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`__
+   <https://packaging.python.org/installing/#requirements-for-installing-packages>`__
 
 
 .. installing-per-user-installation:
@@ -142,20 +156,19 @@ package just for the current user, rather than for all users of the system.
 A number of scientific Python packages have complex binary dependencies, and
 aren't currently easy to install using ``pip`` directly. At this point in
 time, it will often be easier for users to install these packages by
-`other means
-<https://packaging.python.org/en/latest/science/>`__
+`other means <https://packaging.python.org/science/>`__
 rather than attempting to install them with ``pip``.
 
 .. seealso::
 
    `Python Packaging User Guide: Installing Scientific Packages
-   <https://packaging.python.org/en/latest/science/>`__
+   <https://packaging.python.org/science/>`__
 
 
 ... work with multiple versions of Python installed in parallel?
 ----------------------------------------------------------------
 
-On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
+On Linux, Mac OS X, and other POSIX systems, use the versioned Python commands
 in combination with the ``-m`` switch to run the appropriate copy of
 ``pip``::
 
@@ -164,7 +177,7 @@ in combination with the ``-m`` switch to run the appropriate copy of
    python3   -m pip install SomePackage  # default Python 3
    python3.4 -m pip install SomePackage  # specifically Python 3.4
 
-(appropriately versioned ``pip`` commands may also be available)
+Appropriately versioned ``pip`` commands may also be available.
 
 On Windows, use the ``py`` Python launcher in combination with the ``-m``
 switch::
@@ -212,11 +225,11 @@ as users are more regularly able to install pre-built extensions rather
 than needing to build them themselves.
 
 Some of the solutions for installing `scientific software
-<https://packaging.python.org/en/latest/science/>`__
-that is not yet available as pre-built ``wheel`` files may also help with
+<https://packaging.python.org/science/>`__
+that are not yet available as pre-built ``wheel`` files may also help with
 obtaining other binary extensions without needing to build them locally.
 
 .. seealso::
 
    `Python Packaging User Guide: Binary Extensions
-   <https://packaging.python.org/en/latest/extensions/>`__
+   <https://packaging.python.org/extensions/>`__

Doc/tutorial/venv.rst

@@ -20,15 +20,14 @@ the requirements of every application.  If application A needs version
 the requirements are in conflict and installing either version 1.0 or 2.0
 will leave one application unable to run.
 
-The solution for this problem is to create a :term:`virtual
-environment` (often shortened to "virtualenv"), a self-contained
-directory tree that contains a Python installation for a particular
-version of Python, plus a number of additional packages.
+The solution for this problem is to create a :term:`virtual environment`, a
+self-contained directory tree that contains a Python installation for a
+particular version of Python, plus a number of additional packages.
 
 Different applications can then use different virtual environments.
 To resolve the earlier example of conflicting requirements,
 application A can have its own virtual environment with version 1.0
-installed while application B has another virtualenv with version 2.0.
+installed while application B has another virtual environment with version 2.0.
 If application B requires a library be upgraded to version 3.0, this will
 not affect application A's environment.
 
@@ -36,29 +35,26 @@ not affect application A's environment.
 Creating Virtual Environments
 =============================
 
-The script used to create and manage virtual environments is called
-:program:`pyvenv`.  :program:`pyvenv` will usually install the most
-recent version of Python that you have available; the script is also
-installed with a version number, so if you have multiple versions of
-Python on your system you can select a specific Python version by
-running ``pyvenv-3.4`` or whichever version you want.
+The module used to create and manage virtual environments is called
+:mod:`venv`.  :mod:`venv` will usually install the most recent version of
+Python that you have available. If you have multiple versions of Python on your
+system, you can select a specific Python version by running ``python3`` or
+whichever version you want.
 
-To create a virtualenv, decide upon a directory
-where you want to place it and run :program:`pyvenv` with the
-directory path::
+To create a virtual environment, decide upon a directory where you want to
+place it, and run the :mod:`venv` module as a script with the directory path::
 
-   pyvenv tutorial-env
+   python3 -m venv tutorial-env
 
 This will create the ``tutorial-env`` directory if it doesn't exist,
 and also create directories inside it containing a copy of the Python
 interpreter, the standard library, and various supporting files.
 
-Once you've created a virtual environment, you need to
-activate it.
+Once you've created a virtual environment, you may activate it.
 
 On Windows, run::
 
-  tutorial-env/Scripts/activate
+  tutorial-env\Scripts\activate.bat
 
 On Unix or MacOS, run::
 
@@ -69,33 +65,36 @@ On Unix or MacOS, run::
 ``activate.csh`` and ``activate.fish`` scripts you should use
 instead.)
 
-Activating the virtualenv will change your shell's prompt to show what
-virtualenv you're using, and modify the environment so that running
-``python`` will get you that particular version and installation of
-Python.  For example::
+Activating the virtual environment will change your shell's prompt to show what
+virtual environment you're using, and modify the environment so that running
+``python`` will get you that particular version and installation of Python.
+For example:
 
-  -> source ~/envs/tutorial-env/bin/activate
-  (tutorial-env) -> python
-  Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25)
+.. code-block:: bash
+
+  $ source ~/envs/tutorial-env/bin/activate
+  (tutorial-env) $ python
+  Python 3.5.1 (default, May  6 2016, 10:59:36)
     ...
   >>> import sys
   >>> sys.path
-  ['', '/usr/local/lib/python34.zip', ...,
-  '~/envs/tutorial-env/lib/python3.4/site-packages']
+  ['', '/usr/local/lib/python35.zip', ...,
+  '~/envs/tutorial-env/lib/python3.5/site-packages']
   >>>
 
 
 Managing Packages with pip
 ==========================
 
-Once you've activated a virtual environment, you can install, upgrade,
-and remove packages using a program called :program:`pip`.  By default
-``pip`` will install packages from the Python Package Index,
-<https://pypi.python.org/pypi>.  You can browse the Python Package Index
-by going to it in your web browser, or you can use ``pip``'s
-limited search feature::
+You can install, upgrade, and remove packages using a program called
+:program:`pip`.  By default ``pip`` will install packages from the Python
+Package Index, <https://pypi.python.org/pypi>.  You can browse the Python
+Package Index by going to it in your web browser, or you can use ``pip``'s
+limited search feature:
+
+.. code-block:: bash
 
-  (tutorial-env) -> pip search astronomy
+  (tutorial-env) $ pip search astronomy
   skyfield               - Elegant astronomy for Python
   gary                   - Galactic astronomy and gravitational dynamics.
   novas                  - The United States Naval Observatory NOVAS astronomy library
@@ -107,9 +106,11 @@ limited search feature::
 "freeze", etc.  (Consult the :ref:`installing-index` guide for
 complete documentation for ``pip``.)
 
-You can install the latest version of a package by specifying a package's name::
+You can install the latest version of a package by specifying a package's name:
+
+.. code-block:: bash
 
-  -> pip install novas
+  (tutorial-env) $ pip install novas
   Collecting novas
     Downloading novas-3.1.1.3.tar.gz (136kB)
   Installing collected packages: novas
@@ -117,9 +118,11 @@ You can install the latest version of a package by specifying a package's name::
   Successfully installed novas-3.1.1.3
 
 You can also install a specific version of a package by giving the
-package name  followed by ``==`` and the version number::
+package name  followed by ``==`` and the version number:
 
-  -> pip install requests==2.6.0
+.. code-block:: bash
+
+  (tutorial-env) $ pip install requests==2.6.0
   Collecting requests==2.6.0
     Using cached requests-2.6.0-py2.py3-none-any.whl
   Installing collected packages: requests
@@ -128,9 +131,11 @@ package name  followed by ``==`` and the version number::
 If you re-run this command, ``pip`` will notice that the requested
 version is already installed and do nothing.  You can supply a
 different version number to get that version, or you can run ``pip
-install --upgrade`` to upgrade the package to the latest version::
+install --upgrade`` to upgrade the package to the latest version:
+
+.. code-block:: bash
 
-  -> pip install --upgrade requests
+  (tutorial-env) $ pip install --upgrade requests
   Collecting requests
   Installing collected packages: requests
     Found existing installation: requests 2.6.0
@@ -141,9 +146,11 @@ install --upgrade`` to upgrade the package to the latest version::
 ``pip uninstall`` followed by one or more package names will remove the
 packages from the virtual environment.
 
-``pip show`` will display information about a particular package::
+``pip show`` will display information about a particular package:
 
-  (tutorial-env) -> pip show requests
+.. code-block:: bash
+
+  (tutorial-env) $ pip show requests
   ---
   Metadata-Version: 2.0
   Name: requests
@@ -157,9 +164,11 @@ packages from the virtual environment.
   Requires:
 
 ``pip list`` will display all of the packages installed in the virtual
-environment::
+environment:
+
+.. code-block:: bash
 
-  (tutorial-env) -> pip list
+  (tutorial-env) $ pip list
   novas (3.1.1.3)
   numpy (1.9.2)
   pip (7.0.3)
@@ -168,19 +177,23 @@ environment::
 
 ``pip freeze`` will produce a similar list of the installed packages,
 but the output uses the format that ``pip install`` expects.
-A common convention is to put this list in a ``requirements.txt`` file::
+A common convention is to put this list in a ``requirements.txt`` file:
 
-  (tutorial-env) -> pip freeze > requirements.txt
-  (tutorial-env) -> cat requirements.txt
+.. code-block:: bash
+
+  (tutorial-env) $ pip freeze > requirements.txt
+  (tutorial-env) $ cat requirements.txt
   novas==3.1.1.3
   numpy==1.9.2
   requests==2.7.0
 
 The ``requirements.txt`` can then be committed to version control and
 shipped as part of an application.  Users can then install all the
-necessary packages with ``install -r``::
+necessary packages with ``install -r``:
+
+.. code-block:: bash
 
-  -> pip install -r requirements.txt
+  (tutorial-env) $ pip install -r requirements.txt
   Collecting novas==3.1.1.3 (from -r requirements.txt (line 1))
     ...
   Collecting numpy==1.9.2 (from -r requirements.txt (line 2))

Doc/using/index.rst

@@ -17,4 +17,3 @@ interpreter and things that make working with Python easier.
    unix.rst
    windows.rst
    mac.rst
-   scripts.rst

Doc/using/scripts.rst

-.. _tools-and-scripts:
-
-Additional Tools and Scripts
-============================
-
-.. _scripts-pyvenv:
-
-pyvenv - Creating virtual environments
---------------------------------------
-
-.. include:: venv-create.inc
-

Doc/using/venv-create.inc

 Creation of :ref:`virtual environments <venv-def>` is done by executing the
-``pyvenv`` script::
+command ``venv``::
 
-    pyvenv /path/to/new/virtual/environment
+    python3 -m venv /path/to/new/virtual/environment
 
 Running this command creates the target directory (creating any parent
 directories that don't exist already) and places a ``pyvenv.cfg`` file in it
-with a ``home`` key pointing to the Python installation the command was run
-from.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
+with a ``home`` key pointing to the Python installation from which the command
+was run.  It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
 containing a copy of the ``python`` binary (or binaries, in the case of
 Windows).  It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
 subdirectory (on Windows, this is ``Lib\site-packages``).
 
+.. deprecated:: 3.6
+   ``pyvenv`` was the recommended tool for creating virtual environments for
+   Python 3.3 and 3.4, and is `deprecated in Python 3.6
+   <https://docs.python.org/dev/whatsnew/3.6.html#deprecated-features>`_.
+
+.. versionchanged:: 3.5
+   The use of ``venv`` is now recommended for creating virtual environments.
+
 .. seealso::
 
    `Python Packaging User Guide: Creating and using virtual environments
-   <https://packaging.python.org/en/latest/installing/#creating-virtual-environments>`__
+   <https://packaging.python.org/installing/#creating-virtual-environments>`__
 
 .. highlight:: none
 
-On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
-don't have the relevant PATH and PATHEXT settings::
+On Windows, invoke the ``venv`` command as follows::
 
-    c:\Temp>c:\Python35\python c:\Python35\Tools\Scripts\pyvenv.py myenv
+    c:\>c:\Python35\python -m venv c:\path\to\myenv
 
-or equivalently::
+Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for
+your :ref:`Python installation <using-on-windows>`::
 
-    c:\Temp>c:\Python35\python -m venv myenv
+    c:\>python -m venv myenv c:\path\to\myenv
 
 The command, if run with ``-h``, will show the available options::
 
@@ -36,25 +44,26 @@ The command, if run with ``-h``, will show the available options::
     Creates virtual Python environments in one or more target directories.
 
     positional arguments:
-      ENV_DIR             A directory to create the environment in.
+      ENV_DIR               A directory to create the environment in.
 
     optional arguments:
-      -h, --help             show this help message and exit
-      --system-site-packages Give the virtual environment access to the system
-                             site-packages dir.
-      --symlinks             Try to use symlinks rather than copies, when symlinks
-                             are not the default for the platform.
-      --copies               Try to use copies rather than symlinks, even when
-                             symlinks are the default for the platform.
-      --clear                Delete the contents of the environment directory if it
-                             already exists, before environment creation.
-      --upgrade              Upgrade the environment directory to use this version
-                             of Python, assuming Python has been upgraded in-place.
-      --without-pip          Skips installing or upgrading pip in the virtual
-                             environment (pip is bootstrapped by default)
-
-Depending on how the ``venv`` functionality has been invoked, the usage message
-may vary slightly, e.g. referencing ``pyvenv`` rather than ``venv``.
+      -h, --help            show this help message and exit
+      --system-site-packages
+                            Give the virtual environment access to the system
+                            site-packages dir.
+      --symlinks            Try to use symlinks rather than copies, when symlinks
+                            are not the default for the platform.
+      --copies              Try to use copies rather than symlinks, even when
+                            symlinks are the default for the platform.
+      --clear               Delete the contents of the environment directory if it
+                            already exists, before environment creation.
+      --upgrade             Upgrade the environment directory to use this version
+                            of Python, assuming Python has been upgraded in-place.
+      --without-pip         Skips installing or upgrading pip in the virtual
+                            environment (pip is bootstrapped by default)
+
+    Once an environment has been created, you may wish to activate it, e.g. by
+    sourcing an activate script in its bin directory.
 
 .. versionchanged:: 3.4
    Installs pip by default, added the ``--without-pip``  and ``--copies``
@@ -73,12 +82,13 @@ run with the ``--system-site-packages`` option, ``false`` otherwise.
 Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be
 invoked to bootstrap ``pip`` into the virtual environment.
 
-Multiple paths can be given to ``pyvenv``, in which case an identical
-virtualenv will be created, according to the given options, at each
-provided path.
+Multiple paths can be given to ``venv``, in which case an identical virtual
+environment will be created, according to the given options, at each provided
+path.
 
-Once a venv has been created, it can be "activated" using a script in the
-venv's binary directory. The invocation of the script is platform-specific:
+Once a virtual environment has been created, it can be "activated" using a
+script in the virtual environment's binary directory. The invocation of the
+script is platform-specific:
 
 +-------------+-----------------+-----------------------------------------+
 | Platform    | Shell           | Command to activate virtual environment |
@@ -95,16 +105,17 @@ venv's binary directory. The invocation of the script is platform-specific:
 +-------------+-----------------+-----------------------------------------+
 
 You don't specifically *need* to activate an environment; activation just
-prepends the venv's binary directory to your path, so that "python" invokes the
-venv's Python interpreter and you can run installed scripts without having to
-use their full path. However, all scripts installed in a venv should be
-runnable without activating it, and run with the venv's Python automatically.
-
-You can deactivate a venv by typing "deactivate" in your shell. The exact
-mechanism is platform-specific: for example, the Bash activation script defines
-a "deactivate" function, whereas on Windows there are separate scripts called
-``deactivate.bat`` and ``Deactivate.ps1`` which are installed when the venv is
-created.
+prepends the virtual environment's binary directory to your path, so that
+"python" invokes the virtual environment's Python interpreter and you can run
+installed scripts without having to use their full path. However, all scripts
+installed in a virtual environment should be runnable without activating it,
+and run with the virtual environment's Python automatically.
+
+You can deactivate a virtual environment by typing "deactivate" in your shell.
+The exact mechanism is platform-specific: for example, the Bash activation
+script defines a "deactivate" function, whereas on Windows there are separate
+scripts called ``deactivate.bat`` and ``Deactivate.ps1`` which are installed
+when the virtual environment is created.
 
 .. versionadded:: 3.4
    ``fish`` and ``csh`` activation scripts.

Misc/ACKS

@@ -1150,6 +1150,7 @@ Dusty Phillips
 Christopher J. Phoenix
 James Pickering
 Neale Pickett
+Steve Piercy
 Jim St. Pierre
 Dan Pierson
 Martijn Pieters

Misc/NEWS

@@ -154,6 +154,12 @@ Tools/Demos
 
 - Issue #27418: Fixed Tools/importbench/importbench.py.
 
+Documentation
+-------------
+
+- Issue #27285: Update documentation to reflect the deprecation of ``pyvenv``
+  and normalize on the term "virtual environment". Patch by Steve Piercy.
+
 
 What's New in Python 3.6.0 alpha 2
 ==================================