From 4dc832ebcbfe7b13bcbddb8808d274d1856f49a2 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Fri, 28 Feb 2025 23:56:20 +0530 Subject: [PATCH 1/9] gh-130160 use `.. program::` directive for documenting `venv` CLI --- Doc/library/venv.rst | 53 +++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index bed799aedfdfb1..7575e45f6cc8a9 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -64,6 +64,8 @@ See :pep:`405` for more background on Python virtual environments. Creating virtual environments ----------------------------- +.. program:: venv + :ref:`Virtual environments ` are created by executing the ``venv`` module: @@ -81,21 +83,6 @@ 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. - -.. 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: - -.. code-block:: ps1con - - PS> python -m venv C:\path\to\new\virtual\environment - The command, if run with ``-h``, will show the available options:: usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] @@ -135,6 +122,42 @@ 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. +.. option:: --system-site-packages + + Give the virtual environment access to the system site-packages directory. + +.. option:: --symlinks + + Try to use symlinks rather than copies, when symlinks are not the default for the platform. + +.. option:: --copies + + Try to use copies rather than symlinks, even when symlinks are the default for the platform. + +.. option:: --clear + + Delete the contents of the environment directory if it already exists, before environment creation. + +.. option:: --upgrade + + Upgrade the environment directory to use this version of Python, assuming Python has been upgraded in-place. + +.. option:: --without-pip + + Skips installing or upgrading pip in the virtual environment (pip is bootstrapped by default). + +.. option:: --prompt + + Provides an alternative prompt prefix for this environment. + +.. option:: --upgrade-deps + + Upgrade core dependencies (pip) to the latest version in PyPI. + +.. option:: --without-scm-ignore-files + + Skips adding SCM ignore files to the environment directory (Git is supported by default). + .. versionchanged:: 3.4 Installs pip by default, added the ``--without-pip`` and ``--copies`` From 14190514d692b23154c57052c79c7209def59b64 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Sun, 6 Apr 2025 03:25:16 +0530 Subject: [PATCH 2/9] Update Doc/library/venv.rst Co-authored-by: Semyon Moroz --- 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 7575e45f6cc8a9..f917d79e3b6ec5 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -63,7 +63,7 @@ See :pep:`405` for more background on Python virtual environments. Creating virtual environments ----------------------------- - +.. _venv-cli: .. program:: venv :ref:`Virtual environments ` are created by executing the ``venv`` From 918676c38529a8eed28dd060655500bd74b7727d Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Sun, 6 Apr 2025 03:25:40 +0530 Subject: [PATCH 3/9] Update Doc/library/venv.rst Co-authored-by: Semyon Moroz --- Doc/library/venv.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index f917d79e3b6ec5..7cf2e9d613bc34 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -122,6 +122,10 @@ 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. +.. option:: ENV_DIR + + A required argument specifying the directory to create the environment in. + .. option:: --system-site-packages Give the virtual environment access to the system site-packages directory. From 538579132eb599ef62206fe6c394a63f1b7dd847 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Wed, 21 May 2025 20:30:48 +0530 Subject: [PATCH 4/9] fix: removed duplicate line from docs --- Doc/library/venv.rst | 42 +++++++++++++++--------------------------- 1 file changed, 15 insertions(+), 27 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 7cf2e9d613bc34..0e8c20a538b340 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -83,6 +83,21 @@ 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. + +.. 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: + +.. code-block:: ps1con + + PS> python -m venv C:\path\to\new\virtual\environment + The command, if run with ``-h``, will show the available options:: usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] @@ -92,33 +107,6 @@ 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. - - 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. From 9a5281b0796903ac16576e56b7606df8982284b1 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 2 Jun 2025 18:16:18 +0530 Subject: [PATCH 5/9] Update Doc/library/venv.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- 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 0e8c20a538b340..08f6d0a1ce57c2 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -112,7 +112,7 @@ The command, if run with ``-h``, will show the available options:: .. option:: ENV_DIR - A required argument specifying the directory to create the environment in. + A required argument specifying the directory to create the environment in. .. option:: --system-site-packages From 2d042e16798cdc09864db1debfcabf7ef462e97c Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 2 Jun 2025 18:33:11 +0530 Subject: [PATCH 6/9] chore: reformatted flags --- Doc/library/venv.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 08f6d0a1ce57c2..8cdfdafb4351fb 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -63,8 +63,6 @@ See :pep:`405` for more background on Python virtual environments. Creating virtual environments ----------------------------- -.. _venv-cli: -.. program:: venv :ref:`Virtual environments ` are created by executing the ``venv`` module: @@ -110,9 +108,12 @@ 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. +.. _venv-cli: +.. program:: venv + .. option:: ENV_DIR - A required argument specifying the directory to create the environment in. + A required argument specifying the directory to create the environment in. .. option:: --system-site-packages From 889cc43d3556b4dd6df041daf02aed1d0e7c2407 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 2 Jun 2025 19:08:02 +0530 Subject: [PATCH 7/9] chore: removed whitespaces --- 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 8cdfdafb4351fb..f16e24eac08343 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -113,7 +113,7 @@ The command, if run with ``-h``, will show the available options:: .. option:: ENV_DIR - A required argument specifying the directory to create the environment in. + A required argument specifying the directory to create the environment in. .. option:: --system-site-packages From 8a3659baedd3eafa80eb0c06e91f223ba7f51111 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 2 Jun 2025 19:13:59 +0530 Subject: [PATCH 8/9] feat: add -h, --help option --- Doc/library/venv.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index f16e24eac08343..5b60efd66d1e55 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -115,6 +115,10 @@ The command, if run with ``-h``, will show the available options:: A required argument specifying the directory to create the environment in. +.. option:: -h, --help + + show the help message and exit + .. option:: --system-site-packages Give the virtual environment access to the system site-packages directory. From e6ab47b529e37c392f105170d52609e8ac27d5cc Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Mon, 2 Jun 2025 23:35:25 +0530 Subject: [PATCH 9/9] chore: removed -h,--help --- Doc/library/venv.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 5b60efd66d1e55..f16e24eac08343 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -115,10 +115,6 @@ The command, if run with ``-h``, will show the available options:: A required argument specifying the directory to create the environment in. -.. option:: -h, --help - - show the help message and exit - .. option:: --system-site-packages Give the virtual environment access to the system site-packages directory.