From 4f8b2d51d8497a2c4af6bca39bc0a5d2377e60c7 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:30:25 +0300 Subject: [PATCH 01/17] Suggest .venv before venv --- Doc/library/venv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index fff1075c2473eb..a9e0b0495bbb37 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -37,7 +37,7 @@ A virtual environment is (amongst other things): are by default isolated from software in other virtual environments and Python interpreters and libraries installed in the operating system. -* Contained in a directory, conventionally either named ``venv`` or ``.venv`` in +* Contained in a directory, conventionally either named ``.venv`` or ``venv`` in the project directory, or under a container directory for lots of virtual environments, such as ``~/.virtualenvs``. From 8b96ad75205e9cf145befad0c25180636e2cae9e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:30:53 +0300 Subject: [PATCH 02/17] Proofreading --- Doc/library/venv.rst | 2 +- Doc/using/venv-create.inc | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index a9e0b0495bbb37..aa5c26413393f7 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -44,7 +44,7 @@ A virtual environment is (amongst other things): * Not checked into source control systems such as Git. * Considered as disposable -- it should be simple to delete and recreate it from - scratch. You don't place any project code in the environment + scratch. You don't place any project code in the environment. * Not considered as movable or copyable -- you just recreate the same environment in the target location. diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 354eb1541ceac2..8caa3ff7e4525a 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -1,10 +1,10 @@ -Creation of :ref:`virtual environments ` is done by executing the -command ``venv``:: +:ref:`Virtual environments ` are created by executing the ``venv`` +command:: python -m venv /path/to/new/virtual/environment -Running this command creates the target directory (creating any parent -directories that don't exist already) and places a ``pyvenv.cfg`` file in it +This creates the target directory (creating any parent +directories that don't already exist) and places a ``pyvenv.cfg`` file in it with a ``home`` key pointing to the Python installation from which the command was run (a common name for the target directory is ``.venv``). It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink From 09d9bff3bd64f01e742500150a15a7bb5ba48f5f Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:31:31 +0300 Subject: [PATCH 03/17] Document pyvenv was removed in 3.8 --- Doc/using/venv-create.inc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 8caa3ff7e4525a..6df6372a3ae1cd 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -17,10 +17,9 @@ re-used. .. versionchanged:: 3.5 The use of ``venv`` is now recommended for creating virtual environments. -.. deprecated:: 3.6 +.. deprecated-removed:: 3.6 3.8 ``pyvenv`` was the recommended tool for creating virtual environments for - Python 3.3 and 3.4, and is - :ref:`deprecated in Python 3.6 `. + Python 3.3 and 3.4. .. highlight:: none From a4901935b06fa595904f778a5bfd8790e227584e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:42:43 +0300 Subject: [PATCH 04/17] Fix without-scm-ignore-file -> without-scm-ignore-files option and help text --- Doc/using/venv-create.inc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 6df6372a3ae1cd..4856160e268de4 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -36,7 +36,7 @@ The command, if run with ``-h``, will show the available options:: usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps] - [--without-scm-ignore-file] + [--without-scm-ignore-files] ENV_DIR [ENV_DIR ...] Creates virtual Python environments in one or more target directories. @@ -64,18 +64,17 @@ The command, if run with ``-h``, will show the available options:: environment. --upgrade-deps Upgrade core dependencies (pip) to the latest version in PyPI - --without-scm-ignore-file - Skips adding the default SCM ignore file to the - environment directory (the default is a .gitignore - file). + --without-scm-ignore-files + Skips adding SCM ignore files to the environment + directory (Git is supported by default). Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. .. versionchanged:: 3.13 - ``--without-scm-ignore-file`` was added along with creating an ignore file - for ``git`` by default. + ``--without-scm-ignore-files`` was added along with creating an ignore file + for Git by default. .. versionchanged:: 3.12 From 694c65d4ff2c54181cb6c572daff0a119aeca987 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:46:15 +0300 Subject: [PATCH 05/17] Realign --help to match output --- Doc/using/venv-create.inc | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 4856160e268de4..3d3c0a3fae1159 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -42,31 +42,31 @@ The command, if run with ``-h``, will show the available options:: Creates virtual Python environments in one or more target directories. positional arguments: - ENV_DIR A directory to create the environment in. + ENV_DIR A directory to create the environment in. options: - -h, --help show this help message and exit - --system-site-packages + -h, --help show this help message and exit + --system-site-packages Give the virtual environment access to the system site-packages dir. - --symlinks Try to use symlinks rather than copies, when + --symlinks Try to use symlinks rather than copies, when symlinks are not the default for the platform. - --copies Try to use copies rather than symlinks, even when + --copies Try to use copies rather than symlinks, even when symlinks are the default for the platform. - --clear Delete the contents of the environment directory if - it already exists, before environment creation. - --upgrade Upgrade the environment directory to use this - version of Python, assuming Python has been upgraded - in-place. - --without-pip Skips installing or upgrading pip in the virtual + --clear Delete the contents of the environment directory + if it already exists, before environment creation. + --upgrade Upgrade the environment directory to use this + version of Python, assuming Python has been + upgraded in-place. + --without-pip Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default) - --prompt PROMPT Provides an alternative prompt prefix for this + --prompt PROMPT Provides an alternative prompt prefix for this environment. - --upgrade-deps Upgrade core dependencies (pip) to the latest + --upgrade-deps Upgrade core dependencies (pip) to the latest version in PyPI - --without-scm-ignore-files - Skips adding SCM ignore files to the environment - directory (Git is supported by default). + --without-scm-ignore-files + Skips adding SCM ignore files to the environment + directory (Git is supported by default). Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. From fc04bddd91ec9785b6255b046d55ea1205def297 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:47:30 +0300 Subject: [PATCH 06/17] Sort versionchanged oldest first, like elsewhere --- Doc/using/venv-create.inc | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 3d3c0a3fae1159..fed8fc1050b935 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -71,26 +71,27 @@ The command, if run with ``-h``, will show the available options:: Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. -.. versionchanged:: 3.13 - - ``--without-scm-ignore-files`` was added along with creating an ignore file - for Git by default. - -.. versionchanged:: 3.12 - - ``setuptools`` is no longer a core venv dependency. - -.. versionchanged:: 3.9 - Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI .. versionchanged:: 3.4 Installs pip by default, added the ``--without-pip`` and ``--copies`` - options + options. .. versionchanged:: 3.4 In earlier versions, if the target directory already existed, an error was raised, unless the ``--clear`` or ``--upgrade`` option was provided. +.. versionchanged:: 3.9 + Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI. + +.. versionchanged:: 3.12 + + ``setuptools`` is no longer a core venv dependency. + +.. versionchanged:: 3.13 + + ``--without-scm-ignore-files`` was added along with creating an ignore file + for Git by default. + .. note:: While symlinks are supported on Windows, they are not recommended. Of particular note is that double-clicking ``python.exe`` in File Explorer From ead04263b06dc9dc2dba051797915abc2772a46b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 13:56:20 +0300 Subject: [PATCH 07/17] Highlight console commands --- Doc/using/venv-create.inc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index fed8fc1050b935..d839b22713968a 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -1,5 +1,7 @@ :ref:`Virtual environments ` are created by executing the ``venv`` -command:: +command: + +.. code-block:: bash python -m venv /path/to/new/virtual/environment @@ -102,7 +104,9 @@ The command, if run with ``-h``, will show the available options:: script by setting the execution policy for the user. You can do this by issuing the following PowerShell command: - PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + .. code-block:: powershell + + PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser See `About Execution Policies `_ From f15cded3decbf7c22b74955c7372f44fbd5df896 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:02:43 +0300 Subject: [PATCH 08/17] Replace Latin abbreviation --- Doc/library/venv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index aa5c26413393f7..d7c0c725cc727d 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -117,7 +117,7 @@ should be runnable without activating it. In order to achieve this, scripts installed into virtual environments have a "shebang" line which points to the environment's Python interpreter, -i.e. :samp:`#!/{}/bin/python`. +that is :samp:`#!/{}/bin/python`. This means that the script will run with that interpreter regardless of the value of :envvar:`PATH`. On Windows, "shebang" line processing is supported if you have the :ref:`launcher` installed. Thus, double-clicking an installed From 388351a9c587edfcb0e5402ed42e73d713c298de Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:07:15 +0300 Subject: [PATCH 09/17] Code font for directory names --- Doc/library/venv.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index d7c0c725cc727d..b1eea6bec0e526 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -345,8 +345,8 @@ creation according to their needs, the :class:`EnvBuilder` class. .. method:: install_scripts(context, path) *path* is the path to a directory that should contain subdirectories - "common", "posix", "nt", each containing scripts destined for the bin - directory in the environment. The contents of "common" and the + ``common``, ``posix``, ``nt``, each containing scripts destined for the + bin directory in the environment. The contents of ``common`` and the directory corresponding to :data:`os.name` are copied after some text replacement of placeholders: From 552a786d920e31dd340bcc0d15343d2af7b3d390 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:08:25 +0300 Subject: [PATCH 10/17] Git is the SCM, git is a command --- Doc/library/venv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index b1eea6bec0e526..07cc09e3597fba 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -371,7 +371,7 @@ creation according to their needs, the :class:`EnvBuilder` class. .. method:: create_git_ignore_file(context) Creates a ``.gitignore`` file within the virtual environment that causes - the entire directory to be ignored by the ``git`` source control manager. + the entire directory to be ignored by the Git source control manager. .. versionadded:: 3.13 From 76c6bcfc04fe5df0cbcc5e3b5e8adae5c9b392ae Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:10:24 +0300 Subject: [PATCH 11/17] Parameters in italics --- Doc/library/venv.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 07cc09e3597fba..b734e40fe9c1ec 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -387,16 +387,16 @@ There is also a module-level convenience function: .. versionadded:: 3.3 .. versionchanged:: 3.4 - Added the ``with_pip`` parameter + Added the *with_pip* parameter .. versionchanged:: 3.6 - Added the ``prompt`` parameter + Added the *prompt* parameter .. versionchanged:: 3.9 - Added the ``upgrade_deps`` parameter + Added the *upgrade_deps* parameter .. versionchanged:: 3.13 - Added the ``scm_ignore_files`` parameter + Added the *scm_ignore_files* parameter An example of extending ``EnvBuilder`` -------------------------------------- From 2afa69d22f4a099e9fe3693e95d1d4414d7a8cf8 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 16 Sep 2024 14:17:12 +0300 Subject: [PATCH 12/17] program formatting --- Doc/using/venv-create.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index d839b22713968a..96fbd14b2a758d 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -20,8 +20,8 @@ re-used. The use of ``venv`` is now recommended for creating virtual environments. .. deprecated-removed:: 3.6 3.8 - ``pyvenv`` was the recommended tool for creating virtual environments for - Python 3.3 and 3.4. + :program:`pyvenv` was the recommended tool for creating virtual environments + for Python 3.3 and 3.4. .. highlight:: none From 02e99acb07dba0cfcefb4983f2720eba1baaee4e Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 23 Sep 2024 20:55:55 +0300 Subject: [PATCH 13/17] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/venv.rst | 8 ++++---- Doc/using/venv-create.inc | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index b734e40fe9c1ec..31042dd0fec983 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -37,7 +37,7 @@ A virtual environment is (amongst other things): are by default isolated from software in other virtual environments and Python interpreters and libraries installed in the operating system. -* Contained in a directory, conventionally either named ``.venv`` or ``venv`` in +* Contained in a directory, conventionally named ``.venv`` or ``venv`` in the project directory, or under a container directory for lots of virtual environments, such as ``~/.virtualenvs``. @@ -117,7 +117,7 @@ should be runnable without activating it. In order to achieve this, scripts installed into virtual environments have a "shebang" line which points to the environment's Python interpreter, -that is :samp:`#!/{}/bin/python`. +:samp:`#!/{}/bin/python`. This means that the script will run with that interpreter regardless of the value of :envvar:`PATH`. On Windows, "shebang" line processing is supported if you have the :ref:`launcher` installed. Thus, double-clicking an installed @@ -345,8 +345,8 @@ creation according to their needs, the :class:`EnvBuilder` class. .. method:: install_scripts(context, path) *path* is the path to a directory that should contain subdirectories - ``common``, ``posix``, ``nt``, each containing scripts destined for the - bin directory in the environment. The contents of ``common`` and the + ``common``, ``posix``, ``nt``; each containing scripts destined for the + ``bin`` directory in the environment. The contents of ``common`` and the directory corresponding to :data:`os.name` are copied after some text replacement of placeholders: diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc index 96fbd14b2a758d..a11eb62c210a2c 100644 --- a/Doc/using/venv-create.inc +++ b/Doc/using/venv-create.inc @@ -1,11 +1,11 @@ :ref:`Virtual environments ` are created by executing the ``venv`` -command: +module: -.. code-block:: bash +.. code-block:: shell python -m venv /path/to/new/virtual/environment -This creates the target directory (creating any parent +This creates the target directory (and any parent directories that don't already exist) and places a ``pyvenv.cfg`` file in it with a ``home`` key pointing to the Python installation from which the command was run (a common name for the target directory is ``.venv``). It also creates @@ -21,7 +21,7 @@ re-used. .. deprecated-removed:: 3.6 3.8 :program:`pyvenv` was the recommended tool for creating virtual environments - for Python 3.3 and 3.4. + for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly. .. highlight:: none From f6643909bcb5d5c74e5a1b77add12aa2efbefcd0 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 23 Sep 2024 10:58:37 -0700 Subject: [PATCH 14/17] Move venv-create.inc into venv.rst --- Doc/library/venv.rst | 125 +++++++++++++++++++++++++++++++++++++- Doc/using/venv-create.inc | 124 ------------------------------------- 2 files changed, 124 insertions(+), 125 deletions(-) delete mode 100644 Doc/using/venv-create.inc diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 31042dd0fec983..fb603099399f69 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -61,7 +61,130 @@ See :pep:`405` for more background on Python virtual environments. Creating virtual environments ----------------------------- -.. include:: /using/venv-create.inc +:ref:`Virtual environments ` are created by executing the ``venv`` +module: + +.. code-block:: shell + + python -m venv /path/to/new/virtual/environment + +This creates the target directory (and any parent +directories that don't already exist) and places a ``pyvenv.cfg`` file in it +with a ``home`` key pointing to the Python installation from which the command +was run (a common name for the target directory is ``.venv``). It also creates +a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink +of the Python binary/binaries (as appropriate for the platform or arguments +used at environment creation time). It also creates an (initially empty) +``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is +``Lib\site-packages``). If an existing directory is specified, it will be +re-used. + +.. versionchanged:: 3.5 + The use of ``venv`` is now recommended for creating virtual environments. + +.. deprecated-removed:: 3.6 3.8 + :program:`pyvenv` was the recommended tool for creating virtual environments + for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly. + +.. highlight:: none + +On Windows, invoke the ``venv`` command as follows:: + + c:\>Python35\python -m venv c:\path\to\myenv + +Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for +your :ref:`Python installation `:: + + c:\>python -m venv c:\path\to\myenv + +The command, if run with ``-h``, will show the available options:: + + usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] + [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps] + [--without-scm-ignore-files] + ENV_DIR [ENV_DIR ...] + + Creates virtual Python environments in one or more target directories. + + positional arguments: + ENV_DIR A directory to create the environment in. + + options: + -h, --help show this help message and exit + --system-site-packages + Give the virtual environment access to the system + site-packages dir. + --symlinks Try to use symlinks rather than copies, when + symlinks are not the default for the platform. + --copies Try to use copies rather than symlinks, even when + symlinks are the default for the platform. + --clear Delete the contents of the environment directory + if it already exists, before environment creation. + --upgrade Upgrade the environment directory to use this + version of Python, assuming Python has been + upgraded in-place. + --without-pip Skips installing or upgrading pip in the virtual + environment (pip is bootstrapped by default) + --prompt PROMPT Provides an alternative prompt prefix for this + environment. + --upgrade-deps Upgrade core dependencies (pip) to the latest + version in PyPI + --without-scm-ignore-files + Skips adding SCM ignore files to the environment + directory (Git is supported by default). + + Once an environment has been created, you may wish to activate it, e.g. by + sourcing an activate script in its bin directory. + + +.. versionchanged:: 3.4 + Installs pip by default, added the ``--without-pip`` and ``--copies`` + options. + +.. versionchanged:: 3.4 + In earlier versions, if the target directory already existed, an error was + raised, unless the ``--clear`` or ``--upgrade`` option was provided. + +.. versionchanged:: 3.9 + Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI. + +.. versionchanged:: 3.12 + + ``setuptools`` is no longer a core venv dependency. + +.. versionchanged:: 3.13 + + ``--without-scm-ignore-files`` was added along with creating an ignore file + for Git by default. + +.. note:: + While symlinks are supported on Windows, they are not recommended. Of + particular note is that double-clicking ``python.exe`` in File Explorer + will resolve the symlink eagerly and ignore the virtual environment. + +.. note:: + On Microsoft Windows, it may be required to enable the ``Activate.ps1`` + script by setting the execution policy for the user. You can do this by + issuing the following PowerShell command: + + .. code-block:: powershell + + PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + + See `About Execution Policies + `_ + for more information. + +The created ``pyvenv.cfg`` file also includes the +``include-system-site-packages`` key, set to ``true`` if ``venv`` is +run with the ``--system-site-packages`` option, ``false`` otherwise. + +Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be +invoked to bootstrap ``pip`` into the virtual environment. + +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. .. _venv-explanation: diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc deleted file mode 100644 index a11eb62c210a2c..00000000000000 --- a/Doc/using/venv-create.inc +++ /dev/null @@ -1,124 +0,0 @@ -:ref:`Virtual environments ` are created by executing the ``venv`` -module: - -.. code-block:: shell - - python -m venv /path/to/new/virtual/environment - -This creates the target directory (and any parent -directories that don't already exist) and places a ``pyvenv.cfg`` file in it -with a ``home`` key pointing to the Python installation from which the command -was run (a common name for the target directory is ``.venv``). It also creates -a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink -of the Python binary/binaries (as appropriate for the platform or arguments -used at environment creation time). It also creates an (initially empty) -``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is -``Lib\site-packages``). If an existing directory is specified, it will be -re-used. - -.. versionchanged:: 3.5 - The use of ``venv`` is now recommended for creating virtual environments. - -.. deprecated-removed:: 3.6 3.8 - :program:`pyvenv` was the recommended tool for creating virtual environments - for Python 3.3 and 3.4, and replaced in 3.5 by executing ``venv`` directly. - -.. highlight:: none - -On Windows, invoke the ``venv`` command as follows:: - - c:\>Python35\python -m venv c:\path\to\myenv - -Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for -your :ref:`Python installation `:: - - c:\>python -m venv c:\path\to\myenv - -The command, if run with ``-h``, will show the available options:: - - usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] - [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps] - [--without-scm-ignore-files] - ENV_DIR [ENV_DIR ...] - - Creates virtual Python environments in one or more target directories. - - positional arguments: - ENV_DIR A directory to create the environment in. - - options: - -h, --help show this help message and exit - --system-site-packages - Give the virtual environment access to the system - site-packages dir. - --symlinks Try to use symlinks rather than copies, when - symlinks are not the default for the platform. - --copies Try to use copies rather than symlinks, even when - symlinks are the default for the platform. - --clear Delete the contents of the environment directory - if it already exists, before environment creation. - --upgrade Upgrade the environment directory to use this - version of Python, assuming Python has been - upgraded in-place. - --without-pip Skips installing or upgrading pip in the virtual - environment (pip is bootstrapped by default) - --prompt PROMPT Provides an alternative prompt prefix for this - environment. - --upgrade-deps Upgrade core dependencies (pip) to the latest - version in PyPI - --without-scm-ignore-files - Skips adding SCM ignore files to the environment - directory (Git is supported by default). - - Once an environment has been created, you may wish to activate it, e.g. by - sourcing an activate script in its bin directory. - - -.. versionchanged:: 3.4 - Installs pip by default, added the ``--without-pip`` and ``--copies`` - options. - -.. versionchanged:: 3.4 - In earlier versions, if the target directory already existed, an error was - raised, unless the ``--clear`` or ``--upgrade`` option was provided. - -.. versionchanged:: 3.9 - Add ``--upgrade-deps`` option to upgrade pip + setuptools to the latest on PyPI. - -.. versionchanged:: 3.12 - - ``setuptools`` is no longer a core venv dependency. - -.. versionchanged:: 3.13 - - ``--without-scm-ignore-files`` was added along with creating an ignore file - for Git by default. - -.. note:: - While symlinks are supported on Windows, they are not recommended. Of - particular note is that double-clicking ``python.exe`` in File Explorer - will resolve the symlink eagerly and ignore the virtual environment. - -.. note:: - On Microsoft Windows, it may be required to enable the ``Activate.ps1`` - script by setting the execution policy for the user. You can do this by - issuing the following PowerShell command: - - .. code-block:: powershell - - PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser - - See `About Execution Policies - `_ - for more information. - -The created ``pyvenv.cfg`` file also includes the -``include-system-site-packages`` key, set to ``true`` if ``venv`` is -run with the ``--system-site-packages`` option, ``false`` otherwise. - -Unless the ``--without-pip`` option is given, :mod:`ensurepip` will be -invoked to bootstrap ``pip`` into the virtual environment. - -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. From ca4ed661dce4f913be01c17c21034b5d45d986b5 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 24 Sep 2024 02:54:28 +0300 Subject: [PATCH 15/17] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/venv.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index fb603099399f69..27dc9702664fca 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -71,7 +71,7 @@ module: This creates the target directory (and any parent directories that don't already exist) and places a ``pyvenv.cfg`` file in it with a ``home`` key pointing to the Python installation from which the command -was run (a common name for the target directory is ``.venv``). It also creates +was run. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink of the Python binary/binaries (as appropriate for the platform or arguments used at environment creation time). It also creates an (initially empty) @@ -88,14 +88,11 @@ re-used. .. highlight:: none -On Windows, invoke the ``venv`` command as follows:: +On Windows, invoke the ``venv`` command as follows: - c:\>Python35\python -m venv c:\path\to\myenv +.. code-block:: ps1con -Alternatively, if you configured the ``PATH`` and ``PATHEXT`` variables for -your :ref:`Python installation `:: - - c:\>python -m venv c:\path\to\myenv + PS> python -m venv C:\path\to\new\virtual\environment The command, if run with ``-h``, will show the available options:: From 90f0a63ee7243f9a96b282dd8d20b36d6333b408 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 25 Sep 2024 11:52:41 +0100 Subject: [PATCH 16/17] Update Doc/library/venv.rst Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/library/venv.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 27dc9702664fca..2701b3e5661fd8 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -151,8 +151,10 @@ The command, if run with ``-h``, will show the available options:: .. versionchanged:: 3.13 - ``--without-scm-ignore-files`` was added along with creating an ignore file - for Git by default. + Added the ``--without-scm-ignore-files`` option. + +.. versionchanged:: 3.13 + ``venv`` now creates a :file:`.gitignore` file for Git by default. .. note:: While symlinks are supported on Windows, they are not recommended. Of From 644a35bd66cbe6c2c0713dba618a7703c0f84eeb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 26 Sep 2024 02:47:30 +0300 Subject: [PATCH 17/17] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- Doc/library/venv.rst | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 2701b3e5661fd8..7fc77b717f23f1 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -68,16 +68,15 @@ module: python -m venv /path/to/new/virtual/environment -This creates the target directory (and any parent -directories that don't already exist) and places a ``pyvenv.cfg`` file in it -with a ``home`` key pointing to the Python installation from which the command -was run. It also creates -a ``bin`` (or ``Scripts`` on Windows) subdirectory containing a copy/symlink -of the Python binary/binaries (as appropriate for the platform or arguments -used at environment creation time). It also creates an (initially empty) -``lib/pythonX.Y/site-packages`` subdirectory (on Windows, this is -``Lib\site-packages``). If an existing directory is specified, it will be -re-used. +This creates the target directory (including parent directories as needed) +and places a :file:`pyvenv.cfg` file in it with a ``home`` key +pointing to the Python installation from which the command was run. +It also creates a :file:`bin` (or :file:`Scripts` on Windows) subdirectory +containing a copy or symlink of the Python executable +(as appropriate for the platform or arguments used at environment creation time). +It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory +(on Windows, this is :file:`Lib\site-packages`). +If an existing directory is specified, it will be re-used. .. versionchanged:: 3.5 The use of ``venv`` is now recommended for creating virtual environments. @@ -152,7 +151,6 @@ The command, if run with ``-h``, will show the available options:: .. versionchanged:: 3.13 Added the ``--without-scm-ignore-files`` option. - .. versionchanged:: 3.13 ``venv`` now creates a :file:`.gitignore` file for Git by default. @@ -174,7 +172,7 @@ The command, if run with ``-h``, will show the available options:: `_ for more information. -The created ``pyvenv.cfg`` file also includes the +The created :file:`pyvenv.cfg` file also includes the ``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with the ``--system-site-packages`` option, ``false`` otherwise.