cpython: baf5ed391a7f (original) (raw)

Mercurial > cpython

changeset 78022:baf5ed391a7f

Issue #15283: Updated pyvenv documentation to expand on activation. [#15283]

Vinay Sajip <vinay_sajip@yahoo.co.uk>
date	Mon, 09 Jul 2012 09:24:59 +0100
parents	464c6a50b0ce
children	867adc562169
files	Doc/library/venv.rst Doc/using/scripts.rst
diffstat	2 files changed, 88 insertions(+), 5 deletions(-)[+] [-] Doc/library/venv.rst 60 Doc/using/scripts.rst 33

line wrap: on

line diff

--- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -50,7 +50,7 @@ or equivalently:: 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 @@ The command, if run with -h, will sh -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.[](#l1.16)

 --symlinks             Try to use symlinks rather than copies, when symlinks[](#l1.17)

                        are not the default for the platform.[](#l1.18)
 --clear                Delete the environment directory if it already exists.[](#l1.19)
                        If not specified and the directory exists, an error is[](#l1.20)
                        raised.[](#l1.21)

@@ -79,6 +80,56 @@ the --system-site-packages option, ` 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 /bin/activate

+ +whereas on Windows, you might do:: +

c:> /Scripts/activate

+ +if you are using the cmd.exe shell, or perhaps:: +

PS C:> /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 @@ creation according to their needs, the : 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[](#l1.85)

 upgraded in-place (defaults to ``False``).[](#l1.86)

+ Creators of third-party virtual environment tools will be free to use the

--- a/Doc/using/scripts.rst +++ b/Doc/using/scripts.rst @@ -33,7 +33,7 @@ or equivalently:: 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 @@ The command, if run with -h, will sh -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.[](#l2.16)

 --symlinks             Try to use symlinks rather than copies, when symlinks[](#l2.17)

                        are not the default for the platform.[](#l2.18)
 --clear                Delete the environment directory if it already exists.[](#l2.19)
                        If not specified and the directory exists, an error is[](#l2.20)
                        raised.[](#l2.21)

@@ -63,6 +64,34 @@ Multiple paths can be given to ``pyvenv` 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 /bin/activate

+ +whereas on Windows, you might do:: +

c:> /Scripts/activate

+ +if you are using the cmd.exe shell, or perhaps:: +

PS C:> /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