Issue #15283: Updated pyvenv documentation to expand on activation.
This commit is contained in:
Vinay Sajip
parent
cc4cffb8fa
commit
a945ad1a12
|
|
@ -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 show the available options::
|
|||
-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 @@ 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.
|
||||
|
||||
.. 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 :class:`EnvBuilder` class.
|
|||
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
|
||||
|
|
|
|||
|
|
@ -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 show the available options::
|
|||
-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 @@ 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue