[Python-checkins] cpython: Issue #15283: Updated pyvenv documentation to expand on activation.
vinay.sajip
python-checkins at python.org
Mon Jul 9 10:25:58 CEST 2012
http://hg.python.org/cpython/rev/baf5ed391a7f
changeset: 78022:baf5ed391a7f
parent: 78020:464c6a50b0ce
user: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: Mon Jul 09 09:24:59 2012 +0100
summary:
Issue #15283: Updated pyvenv documentation to expand on activation.
files:
Doc/library/venv.rst | 60 +++++++++++++++++++++++++++++-
Doc/using/scripts.rst | 33 ++++++++++++++++-
2 files changed, 88 insertions(+), 5 deletions(-)
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -50,7 +50,7 @@
The command, if run with ``-h``, will show the available options::
- usage: pyvenv [-h] [--system-site-packages] [--symlink] [--clear]
+ usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
[--upgrade] ENV_DIR [ENV_DIR ...]
Creates virtual Python environments in one or more target directories.
@@ -62,7 +62,8 @@
-h, --help show this help message and exit
--system-site-packages Give access to the global site-packages dir to the
virtual environment.
- --symlink Attempt to symlink rather than copy.
+ --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.
@@ -79,6 +80,56 @@
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.
+
+.. note:: A virtual environment (also called a ``venv``) is a Python
+ environment such that the Python interpreter, libraries and scripts
+ installed into it are isolated from those installed in other virtual
+ environments, and (by default) any libraries installed in a "system" Python,
+ i.e. one which is installed as part of your operating system.
+
+ 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
+ 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.
+
+ 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
+ directory of the venv, whereas :attr:`sys.base_prefix` and
+ :attr:`sys.base_exec_prefix` point to the non-venv Python installation
+ which was used to create the venv. If a venv is not active, then
+ :attr:`sys.prefix` is the same as :attr:`sys.base_prefix` and
+ :attr:`sys.exec_prefix` is the same as :attr:`sys.base_exec_prefix` (they
+ all point to a non-venv Python installation).
+
API
---
@@ -105,7 +156,10 @@
e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and
Unix systems, but ``False`` on Windows and Mac OS X.
- .. XXX it also takes "upgrade"!
+ * ``upgrade`` -- a Boolean value which, if True, will upgrade an existing
+ environment with the running Python - for use when that Python has been
+ upgraded in-place (defaults to ``False``).
+
Creators of third-party virtual environment tools will be free to use the
diff --git a/Doc/using/scripts.rst b/Doc/using/scripts.rst
--- a/Doc/using/scripts.rst
+++ b/Doc/using/scripts.rst
@@ -33,7 +33,7 @@
The command, if run with ``-h``, will show the available options::
- usage: pyvenv [-h] [--system-site-packages] [--symlink] [--clear]
+ usage: pyvenv [-h] [--system-site-packages] [--symlinks] [--clear]
[--upgrade] ENV_DIR [ENV_DIR ...]
Creates virtual Python environments in one or more target directories.
@@ -45,7 +45,8 @@
-h, --help show this help message and exit
--system-site-packages Give access to the global site-packages dir to the
virtual environment.
- --symlink Attempt to symlink rather than copy.
+ --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.
@@ -63,6 +64,34 @@
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.
+
.. note:: A virtual environment (also called a ``venv``) is a Python
environment such that the Python interpreter, libraries and scripts
installed into it are isolated from those installed in other virtual
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list