diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index e5c91e46201..ac0115b863e 100644 --- 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 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 /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 :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 diff --git a/Doc/using/scripts.rst b/Doc/using/scripts.rst index 89688477b95..08fcfd6aeb5 100644 --- 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 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 /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