From ea6ccbeb9a419d8f40cacb11193f1ee0a98e2f69 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Mon, 17 Oct 2022 10:28:04 +0200 Subject: [PATCH 1/4] Doc: Refresh the venv introduction documentation, and correct the incorrect statement about the VIRTUAL_ENV environment variable --- Doc/library/venv.rst | 139 +++++++++++++++++++++++--------------- Doc/using/venv-create.inc | 42 ------------ 2 files changed, 86 insertions(+), 95 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 40eccdec16b39a..7821b3d84b10a9 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -15,12 +15,22 @@ -------------- +.. _venv-def: + The :mod:`venv` module provides support for creating lightweight "virtual -environments" with their own site directories, optionally isolated from system -site directories. Each virtual environment has its own Python binary (which -matches the version of the binary that was used to create this environment) and -can have its own independent set of installed Python packages in its site -directories. +environments" with their own independent set of Python packages installed in +their site directories. A virtual environment is created on top of an existing +Python installation, known as the virtual environment's "base" Python, and may +be optionally isolated from the base's site packages, meaning +that packages installed in the base environment will not be accessible from +the virtual environment. +A virtual environment is therefore a powerful and convenient concept which +allows quick, and relatively light-weight, Python environment creation. + +When used from within a virtual environment, common installation tools such as +setuptools_ and pip_ will install Python packages +into the virtual environment's site directory without needing to be told to do +so explicitly. See :pep:`405` for more information about Python virtual environments. @@ -36,54 +46,66 @@ Creating virtual environments .. include:: /using/venv-create.inc - -.. _venv-def: - -.. note:: A virtual environment 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 virtual environment is a directory tree which contains Python executable - files and other files which indicate that it is a virtual environment. - - Common installation tools such as setuptools_ and pip_ work as - expected with virtual environments. In other words, when a virtual - environment is active, they install Python packages into the virtual - environment without needing to be told to do so explicitly. - - When a virtual environment is active (i.e., the virtual environment's Python - interpreter is running), the attributes :attr:`sys.prefix` and - :attr:`sys.exec_prefix` point to the base directory of the virtual - environment, whereas :attr:`sys.base_prefix` and - :attr:`sys.base_exec_prefix` point to the non-virtual environment Python - installation which was used to create the virtual environment. If a virtual - environment 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-virtual environment - Python installation). - - When a virtual environment is active, any options that change the - installation path will be ignored from all ``setuptools`` configuration - files to prevent projects being inadvertently installed outside of the - virtual environment. - - When working in a command shell, users can make a virtual environment active - by running an ``activate`` script in the virtual environment's executables - directory (the precise filename and command to use the file is - shell-dependent), which prepends the virtual environment's directory for - executables to the ``PATH`` environment variable for the running shell. There - should be no need in other circumstances to activate a virtual - environment; scripts installed into virtual environments have a "shebang" - line which points to the virtual environment's Python interpreter. This means - that the script will run with that interpreter regardless of the value of - ``PATH``. On Windows, "shebang" line processing is supported if you have the - Python Launcher for Windows installed (this was added to Python in 3.3 - see - :pep:`397` for more details). Thus, double-clicking an installed script in a - Windows Explorer window should run the script with the correct interpreter - without there needing to be any reference to its virtual environment in - ``PATH``. +Further venv detail +------------------- + +When a virtual environment is running, the attributes :attr:`sys.prefix` and +:attr:`sys.exec_prefix` point to the prefix directory of the virtual +environment, whereas :attr:`sys.base_prefix` and +:attr:`sys.base_exec_prefix` point to the non-virtual environment Python +installation which was used to create the virtual environment (known as the +virtual environment's base environment). It is sufficient to check +``sys.prefix == sys.base_prefix`` to determine if the current interpreter is +a virtual environment. + +A virtual environment may be "activated" using a script in the virtual +environment's binary directory. This will prepend the virtual environment's +binary directory to your path, so that running "python" will invoke the virtual +environment's Python interpreter and you can run +installed scripts without having to use their full path. The invocation of the +activation script is platform-specific (```` must be replaced by the path +of the directory containing the virtual environment): + ++-------------+-----------------+-----------------------------------------+ +| Platform | Shell | Command to activate virtual environment | ++=============+=================+=========================================+ +| POSIX | bash/zsh | $ source /bin/activate | ++-------------+-----------------+-----------------------------------------+ +| | fish | $ source /bin/activate.fish | ++-------------+-----------------+-----------------------------------------+ +| | csh/tcsh | $ source /bin/activate.csh | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell Core | $ /bin/Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ +| Windows | cmd.exe | C:\\> \\Scripts\\activate.bat | ++-------------+-----------------+-----------------------------------------+ +| | PowerShell | PS C:\\> \\Scripts\\Activate.ps1 | ++-------------+-----------------+-----------------------------------------+ + +.. versionadded:: 3.4 + ``fish`` and ``csh`` activation scripts. + +.. versionadded:: 3.8 + PowerShell activation scripts installed under POSIX for PowerShell Core + support. + +You don't specifically *need* to activate an environment, and all scripts +installed in a virtual environment should be runnable without activating it. +In order to achieve this, scripts installed into virtual environments have +a "shebang" line which points to the virtual environment's Python interpreter. +This means that the script will run with that interpreter regardless of the +value of ``PATH``. On Windows, "shebang" line processing is supported if +you have the Python Launcher for Windows installed (this was added to Python +in 3.3 - see :pep:`397` for more details). Thus, double-clicking an installed +script in a Windows Explorer window should run the script with the correct +interpreter without there needing to be any reference to its virtual +environment in :envvar:`PATH`. + +When a virtual environment has been activated, the :envvar:`VIRTUAL_ENV` +environment variable is set to the path of the virtual environment. Since it +is not a requirement to explicitly activate a virtual environment in order +to use it, the :envvar:`VIRTUAL_ENV` environment variable cannot be relied +upon to determine whether a Python environment is virtual or not. .. warning:: Because scripts installed in environments should not expect the environment to be activated, their shebang lines contain the absolute paths @@ -99,6 +121,17 @@ Creating virtual environments environment in its new location. Otherwise, software installed into the environment may not work as expected. +You can deactivate a virtual environment by typing "deactivate" in your shell. +The exact mechanism is platform-specific and is an internal implementation +detail (typically a script or shell function will be used). + + +.. note:: When a virtual environment is active, any options that change the + installation path will be ignored from all :mod:`distutils` configuration + files to prevent projects being inadvertently installed outside of the + virtual environment. + + .. _venv-api: API diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index c2a9f521a148b6..fd8cc019b4d1a8 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual environment will be created, according to the given options, at each provided path. -Once a virtual environment has been created, it can be "activated" using a -script in the virtual environment's binary directory. The invocation of the -script is platform-specific (`` must be replaced by the path of the -directory containing the virtual environment): - -+-------------+-----------------+-----------------------------------------+ -| Platform | Shell | Command to activate virtual environment | -+=============+=================+=========================================+ -| POSIX | bash/zsh | $ source /bin/activate | -+-------------+-----------------+-----------------------------------------+ -| | fish | $ source /bin/activate.fish | -+-------------+-----------------+-----------------------------------------+ -| | csh/tcsh | $ source /bin/activate.csh | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell Core | $ /bin/Activate.ps1 | -+-------------+-----------------+-----------------------------------------+ -| Windows | cmd.exe | C:\\> \\Scripts\\activate.bat | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell | PS C:\\> \\Scripts\\Activate.ps1 | -+-------------+-----------------+-----------------------------------------+ - -When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment -variable is set to the path of the virtual environment. This can be used to -check if one is running inside a virtual environment. - -You don't specifically *need* to activate an environment; activation just -prepends the virtual environment's binary directory to your path, so that -"python" invokes the virtual environment's Python interpreter and you can run -installed scripts without having to use their full path. However, all scripts -installed in a virtual environment should be runnable without activating it, -and run with the virtual environment's Python automatically. - -You can deactivate a virtual environment by typing "deactivate" in your shell. -The exact mechanism is platform-specific and is an internal implementation -detail (typically a script or shell function will be used). - -.. versionadded:: 3.4 - ``fish`` and ``csh`` activation scripts. - -.. versionadded:: 3.8 - PowerShell activation scripts installed under POSIX for PowerShell Core - support. From 1ba4797ad0149e3e1c27eb6bf0bf5b9d57256ff7 Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Mon, 17 Oct 2022 13:15:33 +0200 Subject: [PATCH 2/4] Review action to add newline into the documentation of virtual environments --- Doc/library/venv.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 7821b3d84b10a9..00a4a9ac67b733 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -24,6 +24,7 @@ Python installation, known as the virtual environment's "base" Python, and may be optionally isolated from the base's site packages, meaning that packages installed in the base environment will not be accessible from the virtual environment. + A virtual environment is therefore a powerful and convenient concept which allows quick, and relatively light-weight, Python environment creation. From f3d13f3816f54f9164d04e8e673d799ace943dfa Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Tue, 18 Oct 2022 09:09:57 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/venv.rst | 125 +++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 64 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 00a4a9ac67b733..45ea7b9c847c47 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -16,24 +16,21 @@ -------------- .. _venv-def: +.. _venv-intro: -The :mod:`venv` module provides support for creating lightweight "virtual -environments" with their own independent set of Python packages installed in -their site directories. A virtual environment is created on top of an existing +The :mod:`!venv` module supports creating lightweight "virtual environments", +each with their own independent set of Python packages installed in +their :mod:`site` directories. +A virtual environment is created on top of an existing Python installation, known as the virtual environment's "base" Python, and may -be optionally isolated from the base's site packages, meaning -that packages installed in the base environment will not be accessible from -the virtual environment. - -A virtual environment is therefore a powerful and convenient concept which -allows quick, and relatively light-weight, Python environment creation. +optionally be isolated from the packages in the base environment, +so only those explicitly installed in the virtual environment are available. When used from within a virtual environment, common installation tools such as -setuptools_ and pip_ will install Python packages -into the virtual environment's site directory without needing to be told to do -so explicitly. +`pip`_ will install Python packages into a virtual environment +without needing to be told to do so explicitly. -See :pep:`405` for more information about Python virtual environments. +See :pep:`405` for more background on Python virtual environments. .. seealso:: @@ -47,8 +44,10 @@ Creating virtual environments .. include:: /using/venv-create.inc -Further venv detail -------------------- +.. _venv-explanation: + +How venvs work +-------------- When a virtual environment is running, the attributes :attr:`sys.prefix` and :attr:`sys.exec_prefix` point to the prefix directory of the virtual @@ -57,56 +56,60 @@ environment, whereas :attr:`sys.base_prefix` and installation which was used to create the virtual environment (known as the virtual environment's base environment). It is sufficient to check ``sys.prefix == sys.base_prefix`` to determine if the current interpreter is -a virtual environment. - -A virtual environment may be "activated" using a script in the virtual -environment's binary directory. This will prepend the virtual environment's -binary directory to your path, so that running "python" will invoke the virtual -environment's Python interpreter and you can run -installed scripts without having to use their full path. The invocation of the -activation script is platform-specific (```` must be replaced by the path -of the directory containing the virtual environment): - -+-------------+-----------------+-----------------------------------------+ -| Platform | Shell | Command to activate virtual environment | -+=============+=================+=========================================+ -| POSIX | bash/zsh | $ source /bin/activate | -+-------------+-----------------+-----------------------------------------+ -| | fish | $ source /bin/activate.fish | -+-------------+-----------------+-----------------------------------------+ -| | csh/tcsh | $ source /bin/activate.csh | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell Core | $ /bin/Activate.ps1 | -+-------------+-----------------+-----------------------------------------+ -| Windows | cmd.exe | C:\\> \\Scripts\\activate.bat | -+-------------+-----------------+-----------------------------------------+ -| | PowerShell | PS C:\\> \\Scripts\\Activate.ps1 | -+-------------+-----------------+-----------------------------------------+ +running from a virtual environment. + +A virtual environment may be "activated" using a script in its binary directory +(``bin`` on POSIX; ``Scripts`` on Windows). +This will prepend that directory to your :envvar:`!PATH`, so that running +:program:`!python` will invoke the environment's Python interpreter +and you can run installed scripts without having to use their full path. +The invocation of the activation script is platform-specific +(:samp:`{}` must be replaced by the path to the directory +containing the virtual environment): + ++-------------+------------+--------------------------------------------------+ +| Platform | Shell | Command to activate virtual environment | ++=============+============+==================================================+ +| POSIX | bash/zsh | :samp:`$ source {}/bin/activate` | +| +------------+--------------------------------------------------+ +| | fish | :samp:`$ source {}/bin/activate.fish` | +| +------------+--------------------------------------------------+ +| | csh/tcsh | :samp:`$ source {}/bin/activate.csh` | +| +------------+--------------------------------------------------+ +| | PowerShell | :samp:`$ {}/bin/Activate.ps1` | ++-------------+------------+--------------------------------------------------+ +| Windows | cmd.exe | :samp:`C:\\> {}\\Scripts\\activate.bat` | +| +------------+--------------------------------------------------+ +| | PowerShell | :samp:`PS C:\\> {}\\Scripts\\Activate.ps1` | ++-------------+------------+--------------------------------------------------+ .. versionadded:: 3.4 - ``fish`` and ``csh`` activation scripts. + :program:`!fish` and :program:`!csh` activation scripts. .. versionadded:: 3.8 PowerShell activation scripts installed under POSIX for PowerShell Core support. -You don't specifically *need* to activate an environment, and all scripts -installed in a virtual environment should be runnable without activating it. +You don't specifically *need* to activate a virtual environment, +as you can just specify the full path to that environment's +Python interpreter when invoking Python. +Furthermore, all scripts installed in the environment +should be runnable without activating it. + In order to achieve this, scripts installed into virtual environments have -a "shebang" line which points to the virtual environment's Python interpreter. +a "shebang" line which points to the environment's Python interpreter, +i.e. :samp:`#!/{}/bin/python`. This means that the script will run with that interpreter regardless of the -value of ``PATH``. On Windows, "shebang" line processing is supported if -you have the Python Launcher for Windows installed (this was added to Python -in 3.3 - see :pep:`397` for more details). Thus, double-clicking an installed -script in a Windows Explorer window should run the script with the correct -interpreter without there needing to be any reference to its virtual -environment in :envvar:`PATH`. - -When a virtual environment has been activated, the :envvar:`VIRTUAL_ENV` -environment variable is set to the path of the virtual environment. Since it -is not a requirement to explicitly activate a virtual environment in order -to use it, the :envvar:`VIRTUAL_ENV` environment variable cannot be relied -upon to determine whether a Python environment is virtual or not. +value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if +you have the :ref:`launcher` installed. Thus, double-clicking an installed +script in a Windows Explorer window should run it with the correct interpreter +without the environment needing to be activated or on the :envvar:`!PATH`. + +When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV` +environment variable is set to the path of the environment. +Since explicitly activating a virtual environment is not required to use it, +:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine +whether a virtual environment is being used. .. warning:: Because scripts installed in environments should not expect the environment to be activated, their shebang lines contain the absolute paths @@ -122,15 +125,9 @@ upon to determine whether a Python environment is virtual or not. environment in its new location. Otherwise, software installed into the environment may not work as expected. -You can deactivate a virtual environment by typing "deactivate" in your shell. +You can deactivate a virtual environment by typing ``deactivate`` in your shell. The exact mechanism is platform-specific and is an internal implementation -detail (typically a script or shell function will be used). - - -.. note:: When a virtual environment is active, any options that change the - installation path will be ignored from all :mod:`distutils` configuration - files to prevent projects being inadvertently installed outside of the - virtual environment. +detail (typically, a script or shell function will be used). .. _venv-api: From 3d8517a53cf5044629b462e2f8f2a73b42f67eec Mon Sep 17 00:00:00 2001 From: Phil Elson Date: Wed, 19 Oct 2022 12:10:02 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/venv.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 45ea7b9c847c47..adc6cd339ac157 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -49,12 +49,12 @@ Creating virtual environments How venvs work -------------- -When a virtual environment is running, the attributes :attr:`sys.prefix` and -:attr:`sys.exec_prefix` point to the prefix directory of the virtual -environment, whereas :attr:`sys.base_prefix` and -:attr:`sys.base_exec_prefix` point to the non-virtual environment Python -installation which was used to create the virtual environment (known as the -virtual environment's base environment). It is sufficient to check +When a Python interpreter is running from a virtual environment, +:data:`sys.prefix` and :data:`sys.exec_prefix` +point to the directories of the virtual environment, +whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix` +point to those of the base Python used to create the environment. +It is sufficient to check ``sys.prefix == sys.base_prefix`` to determine if the current interpreter is running from a virtual environment.