https://github.com/python/cpython/commit/67a363106b195d6ec21386d7cbc1266ecb781b68
commit: 67a363106b195d6ec21386d7cbc1266ecb781b68
branch: 3.12
author: Jelle Zijlstra <[email protected]>
committer: JelleZijlstra <[email protected]>
date: 2024-09-28T06:09:38-07:00
summary:
[3.12] docs: improve venv docs (GH-124540) (#124728)
- Move "versionchanged" notes that apply to the whole class to the
end of the class docs
- Remove or move notes next to the method list that apply to individual
methods.
- Mark up parameters using the appropriate syntax
- Do not capitalize "boolean"
- Shorten some text
(cherry picked from commit c976d789a98047ae7ddec6d13c9ea7086d9fa3f9)
files:
M Doc/library/venv.rst
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 57b0ee7157cf36..3bc8faeff05d98 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -167,29 +167,29 @@ creation according to their needs, the
:class:`EnvBuilder` class.
The :class:`EnvBuilder` class accepts the following keyword arguments on
instantiation:
- * ``system_site_packages`` -- a Boolean value indicating that the system
Python
+ * *system_site_packages* -- a boolean value indicating that the system
Python
site-packages should be available to the environment (defaults to
``False``).
- * ``clear`` -- a Boolean value which, if true, will delete the contents of
+ * *clear* -- a boolean value which, if true, will delete the contents of
any existing target directory, before creating the environment.
- * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink
the
+ * *symlinks* -- a boolean value indicating whether to attempt to symlink
the
Python binary rather than copying.
- * ``upgrade`` -- a Boolean value which, if true, will upgrade an existing
+ * *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``).
- * ``with_pip`` -- a Boolean value which, if true, ensures pip is
+ * *with_pip* -- a boolean value which, if true, ensures pip is
installed in the virtual environment. This uses :mod:`ensurepip` with
the ``--default-pip`` option.
- * ``prompt`` -- a String to be used after virtual environment is activated
+ * *prompt* -- a string to be used after virtual environment is activated
(defaults to ``None`` which means directory name of the environment would
be used). If the special string ``"."`` is provided, the basename of the
current directory is used as the prompt.
- * ``upgrade_deps`` -- Update the base venv modules to the latest on PyPI
+ * *upgrade_deps* -- Update the base venv modules to the latest on PyPI
.. versionchanged:: 3.4
Added the ``with_pip`` parameter
@@ -200,10 +200,7 @@ creation according to their needs, the :class:`EnvBuilder`
class.
.. versionchanged:: 3.9
Added the ``upgrade_deps`` parameter
- Creators of third-party virtual environment tools will be free to use the
- provided :class:`EnvBuilder` class as a base class.
-
- The returned env-builder is an object which has a method, ``create``:
+ :class:`EnvBuilder` may be used as a base class.
.. method:: create(env_dir)
@@ -303,14 +300,14 @@ creation according to their needs, the
:class:`EnvBuilder` class.
.. method:: upgrade_dependencies(context)
- Upgrades the core venv dependency packages (currently ``pip``)
+ Upgrades the core venv dependency packages (currently :pypi:`pip`)
in the environment. This is done by shelling out to the
``pip`` executable in the environment.
.. versionadded:: 3.9
.. versionchanged:: 3.12
- ``setuptools`` is no longer a core venv dependency.
+ :pypi:`setuptools` is no longer a core venv dependency.
.. method:: post_setup(context)
@@ -318,22 +315,12 @@ creation according to their needs, the
:class:`EnvBuilder` class.
implementations to pre-install packages in the virtual environment or
perform other post-creation steps.
- .. versionchanged:: 3.7.2
- Windows now uses redirector scripts for ``python[w].exe`` instead of
- copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
- nothing unless running from a build in the source tree.
-
- .. versionchanged:: 3.7.3
- Windows copies the redirector scripts as part of :meth:`setup_python`
- instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
- When using symlinks, the original executables will be linked.
-
- In addition, :class:`EnvBuilder` provides this utility method that can be
- called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
- assist in installing custom scripts into the virtual environment.
-
.. method:: install_scripts(context, path)
+ This method can be
+ called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses
to
+ assist in installing custom scripts into the virtual environment.
+
*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
@@ -358,6 +345,16 @@ creation according to their needs, the :class:`EnvBuilder`
class.
The directories are allowed to exist (for when an existing environment
is being upgraded).
+ .. versionchanged:: 3.7.2
+ Windows now uses redirector scripts for ``python[w].exe`` instead of
+ copying the actual binaries. In 3.7.2 only :meth:`setup_python` does
+ nothing unless running from a build in the source tree.
+
+ .. versionchanged:: 3.7.3
+ Windows copies the redirector scripts as part of :meth:`setup_python`
+ instead of :meth:`setup_scripts`. This was not the case in 3.7.2.
+ When using symlinks, the original executables will be linked.
+
There is also a module-level convenience function:
.. function:: create(env_dir, system_site_packages=False, clear=False, \
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
