[Python-checkins] cpython: Factored out common venv documentation and added more information about
vinay.sajip
python-checkins at python.org
Tue Jul 10 09:21:24 CEST 2012
http://hg.python.org/cpython/rev/42d1da32d74f
changeset: 78050:42d1da32d74f
user: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: Tue Jul 10 08:21:07 2012 +0100
summary:
Factored out common venv documentation and added more information about Distribute/pip.
files:
Doc/library/venv.rst | 89 ++------------------------
Doc/using/scripts.rst | 86 +-------------------------
Doc/using/venv-create.inc | 85 +++++++++++++++++++++++++
3 files changed, 93 insertions(+), 167 deletions(-)
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -25,88 +25,8 @@
Creating virtual environments
-----------------------------
-Creation of virtual environments is simplest executing the ``pyvenv`` script::
+.. include:: /using/venv-create.inc
- pyvenv /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
-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``).
-
-.. 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::
-
- c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
-
-or equivalently::
-
- c:\Temp>c:\Python33\python -m venv myenv
-
-The command, if run with ``-h``, will show the available options::
-
- usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
- [--upgrade] ENV_DIR [ENV_DIR ...]
-
- Creates virtual Python environments in one or more target directories.
-
- positional arguments:
- ENV_DIR A directory to create the environment in.
-
- optional arguments:
- -h, --help show this help message and exit
- --system-site-packages Give access to the global site-packages dir to the
- virtual environment.
- --symlinks Try to use symlinks rather than copies, when symlinks
- are not the default for the platform.
- --clear Delete the environment directory if it already exists.
- If not specified and the directory exists, an error is
- raised.
- --upgrade Upgrade the environment directory to use this version
- of Python, assuming Python has been upgraded in-place.
-
-If the target directory already exists an error will be raised, unless the
-``--clear`` or ``--upgrade`` option was provided.
-
-The created ``pyvenv.cfg`` file also includes the
-``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with
-the ``--system-site-packages`` option, ``false`` otherwise.
-
-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.
-
-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: on
-a Posix platform, you would typically do::
-
- $ source <venv>/bin/activate
-
-whereas on Windows, you might do::
-
- C:\> <venv>/Scripts/activate
-
-if you are using the ``cmd.exe`` shell, or perhaps::
-
- PS C:\> <venv>/Scripts/Activate.ps1
-
-if you use PowerShell.
-
-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.
.. _venv-def:
@@ -119,9 +39,14 @@
A venv is a directory tree which contains Python executable files and
other files which indicate that it is a venv.
- Common installation tools such as ``distribute`` and ``pip`` work as
+ Common installation tools such as ``Distribute`` and ``pip`` work as
expected with venvs - i.e. when a venv is active, they install Python
packages into the venv without needing to be told to do so explicitly.
+ Of course, you need to install them into the venv first: this could be
+ done by running ``distribute_setup.py`` with the venv activated,
+ followed by running ``easy_install pip``. Alternatively, you could download
+ the source tarballs and run ``python setup.py install`` after unpacking,
+ with the venv activated.
When a venv is active (i.e. the venv's Python interpreter is running), the
attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the base
diff --git a/Doc/using/scripts.rst b/Doc/using/scripts.rst
--- a/Doc/using/scripts.rst
+++ b/Doc/using/scripts.rst
@@ -6,89 +6,5 @@
pyvenv - Creating virtual environments
--------------------------------------
-Creation of :ref:`virtual environments <venv-def>` is done by executing the
-``pyvenv`` script::
+.. include:: venv-create.inc
- pyvenv /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 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``).
-
-.. 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::
-
- c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
-
-or equivalently::
-
- c:\Temp>c:\Python33\python -m venv myenv
-
-The command, if run with ``-h``, will show the available options::
-
- usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
- [--upgrade] ENV_DIR [ENV_DIR ...]
-
- Creates virtual Python environments in one or more target directories.
-
- positional arguments:
- ENV_DIR A directory to create the environment in.
-
- optional arguments:
- -h, --help show this help message and exit
- --system-site-packages Give access to the global site-packages dir to the
- virtual environment.
- --symlinks Try to use symlinks rather than copies, when symlinks
- are not the default for the platform.
- --clear Delete the environment directory if it already exists.
- If not specified and the directory exists, an error is
- raised.
- --upgrade Upgrade the environment directory to use this version
- of Python, assuming Python has been upgraded in-place.
-
-If the target directory already exists an error will be raised, unless
-the ``--clear`` or ``--upgrade`` option was provided.
-
-The created ``pyvenv.cfg`` file also includes the
-``include-system-site-packages`` key, set to ``true`` if ``venv`` is
-run with the ``--system-site-packages`` option, ``false`` otherwise.
-
-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.
-
-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: on
-a Posix platform, you would typically do::
-
- $ source <venv>/bin/activate
-
-whereas on Windows, you might do::
-
- C:\> <venv>/Scripts/activate
-
-if you are using the ``cmd.exe`` shell, or perhaps::
-
- PS C:\> <venv>/Scripts/Activate.ps1
-
-if you use PowerShell.
-
-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.
-
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
new file mode 100644
--- /dev/null
+++ b/Doc/using/venv-create.inc
@@ -0,0 +1,85 @@
+Creation of :ref:`virtual environments <venv-def>` is done by executing the
+``pyvenv`` script::
+
+ pyvenv /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
+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``).
+
+.. 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::
+
+ c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
+
+or equivalently::
+
+ c:\Temp>c:\Python33\python -m venv myenv
+
+The command, if run with ``-h``, will show the available options::
+
+ usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
+ [--upgrade] ENV_DIR [ENV_DIR ...]
+
+ Creates virtual Python environments in one or more target directories.
+
+ positional arguments:
+ ENV_DIR A directory to create the environment in.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --system-site-packages Give access to the global site-packages dir to the
+ virtual environment.
+ --symlinks Try to use symlinks rather than copies, when symlinks
+ are not the default for the platform.
+ --clear Delete the environment directory if it already exists.
+ If not specified and the directory exists, an error is
+ raised.
+ --upgrade Upgrade the environment directory to use this version
+ of Python, assuming Python has been upgraded in-place.
+
+If the target directory already exists an error will be raised, unless
+the ``--clear`` or ``--upgrade`` option was provided.
+
+The created ``pyvenv.cfg`` file also includes the
+``include-system-site-packages`` key, set to ``true`` if ``venv`` is
+run with the ``--system-site-packages`` option, ``false`` otherwise.
+
+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.
+
+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: on
+a Posix platform, you would typically do::
+
+ $ source <venv>/bin/activate
+
+whereas on Windows, you might do::
+
+ C:\> <venv>/Scripts/activate
+
+if you are using the ``cmd.exe`` shell, or perhaps::
+
+ PS C:\> <venv>/Scripts/Activate.ps1
+
+if you use PowerShell.
+
+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.
+
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list