#23891: add a section to the Tutorial describing virtual environments and pip

2 files changed, 198 insertions, 0 deletions

diff --git a/Doc/tutorial/index.rst b/Doc/tutorial/index.rst
index c14b1d6774..8ee011e282 100644
--- a/Doc/tutorial/index.rst
+++ b/Doc/tutorial/index.rst
@@ -53,6 +53,7 @@ The :ref:`glossary` is also worth going through.
    classes.rst
    stdlib.rst
    stdlib2.rst
+   venv.rst
    whatnow.rst
    interactive.rst
    floatingpoint.rst
diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst
new file mode 100644
index 0000000000..dd63a2cdc3
--- /dev/null
+++ b/Doc/tutorial/venv.rst
@@ -0,0 +1,197 @@
+
+.. _tut-venv:
+
+*********************************
+Virtual Environments and Packages
+*********************************
+
+Introduction
+============
+
+Python applications will often use packages and modules that don't
+come as part of the standard library.  Applications will sometimes
+need a specific version of a library, because the application may
+require that a particular bug has been fixed or the application may be
+written using an obsolete version of the library's interface.
+
+This means it may not be possible for one Python installation to meet
+the requirements of every application.  If application A needs version
+1.0 of a particular module but application B needs version 2.0, then
+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.
+
+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.
+If application B requires a library be upgraded to version 3.0, this will
+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.
+
+To create a virtualenv, decide upon a directory
+where you want to place it and run :program:`pyvenv` with the
+directory path::
+
+   pyvenv 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.  If you
+
+Once you've created a virtual environment, you need to
+activate it.
+
+On Windows, run::
+
+  tutorial-env/Scripts/activate
+
+On Unix or MacOS, run::
+
+  source tutorial-env/bin/activate
+
+(This script is written for the bash shell.  If you use the
+:program:`csh` or :program:`fish` shells, there are alternate
+``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::
+
+  -> source ~/envs/tutorial-env/bin/activate
+  (tutorial-env) -> python
+  Python 3.4.3+ (3.4:c7b9645a6f35+, May 22 2015, 09:31:25)
+    ...
+  >>> import sys
+  >>> sys.path
+  ['', '/usr/local/lib/python34.zip', ...,
+  '~/envs/tutorial-env/lib/python3.4/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 Packaging Index,
+<https://pypi.python.org/pypi>.  You can browse the Python Packaging Index
+by going to it in your web browser, or you can use ``pip``'s
+limited search feature::
+
+  (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
+  astroobs               - Provides astronomy ephemeris to plan telescope observations
+  PyAstronomy            - A collection of astronomy related tools for Python.
+  ...
+
+``pip`` has a number of subcommands: "search", "install", "uninstall",
+"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::
+
+  -> pip install novas
+  Collecting novas
+    Downloading novas-3.1.1.3.tar.gz (136kB)
+  Installing collected packages: novas
+    Running setup.py install for novas
+  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::
+
+  -> 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
+  Successfully installed requests-2.6.0
+
+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::
+
+  -> pip install --upgrade requests
+  Collecting requests
+  Installing collected packages: requests
+    Found existing installation: requests 2.6.0
+      Uninstalling requests-2.6.0:
+        Successfully uninstalled requests-2.6.0
+  Successfully installed requests-2.7.0
+
+``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::
+
+  (tutorial-env) -> pip show requests
+  ---
+  Metadata-Version: 2.0
+  Name: requests
+  Version: 2.7.0
+  Summary: Python HTTP for Humans.
+  Home-page: http://python-requests.org
+  Author: Kenneth Reitz
+  Author-email: me@kennethreitz.com
+  License: Apache 2.0
+  Location: /Users/akuchling/envs/tutorial-env/lib/python3.4/site-packages
+  Requires:
+
+``pip list`` will display all of the packages installed in the virtual
+environment::
+
+  (tutorial-env) -> pip list
+  novas (3.1.1.3)
+  numpy (1.9.2)
+  pip (7.0.3)
+  requests (2.7.0)
+  setuptools (16.0)
+
+``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::
+
+  (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``::
+
+  -> 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))
+    ...
+  Collecting requests==2.7.0 (from -r requirements.txt (line 3))
+    ...
+  Installing collected packages: novas, numpy, requests
+    Running setup.py install for novas
+  Successfully installed novas-3.1.1.3 numpy-1.9.2 requests-2.7.0
+
+``pip`` has many more options.  Consult the :ref:`installing-index`
+guide for complete documentation for ``pip``.  When you've written
+a package and want to make it available on the Python Packaging Index,
+consult the :ref:`distributing-index` guide.