Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit a56d52c

Browse files
smontanarosmontanaro
authored
Merge branch 'main' into gh-25949 
2 parents cdfbe7b + 52fcba6 commit a56d52c

19 files changed

Lines changed: 250 additions & 146 deletions

‎Doc/library/itertools.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ loops that truncate the stream.
198198
while (batch := list(islice(it, n))):
199199
yield batch
200200

201-
.. versionadded:: 3.12
201+
.. versionadded:: 3.12
202202

203203

204204
.. function:: chain(*iterables)

‎Doc/library/venv.rst‎

Lines changed: 84 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,22 @@
1515

1616
--------------
1717

18-
The :mod:`venv` module provides support for creating lightweight "virtual
19-
environments" with their own site directories, optionally isolated from system
20-
site directories. Each virtual environment has its own Python binary (which
21-
matches the version of the binary that was used to create this environment) and
22-
can have its own independent set of installed Python packages in its site
23-
directories.
18+
.. _venv-def:
19+
.. _venv-intro:
20+
21+
The :mod:`!venv` module supports creating lightweight "virtual environments",
22+
each with their own independent set of Python packages installed in
23+
their :mod:`site` directories.
24+
A virtual environment is created on top of an existing
25+
Python installation, known as the virtual environment's "base" Python, and may
26+
optionally be isolated from the packages in the base environment,
27+
so only those explicitly installed in the virtual environment are available.
2428

25-
See :pep:`405` for more information about Python virtual environments.
29+
When used from within a virtual environment, common installation tools such as
30+
`pip`_ will install Python packages into a virtual environment
31+
without needing to be told to do so explicitly.
32+
33+
See :pep:`405` for more background on Python virtual environments.
2634

2735
.. seealso::
2836

@@ -36,54 +44,72 @@ Creating virtual environments
3644

3745
.. include:: /using/venv-create.inc
3846

47+
.. _venv-explanation:
3948

40-
.. _venv-def:
49+
How venvs work
50+
--------------
4151

42-
.. note:: A virtual environment is a Python environment such that the Python
43-
interpreter, libraries and scripts installed into it are isolated from those
44-
installed in other virtual environments, and (by default) any libraries
45-
installed in a "system" Python, i.e., one which is installed as part of your
46-
operating system.
47-
48-
A virtual environment is a directory tree which contains Python executable
49-
files and other files which indicate that it is a virtual environment.
50-
51-
Common installation tools such as setuptools_ and pip_ work as
52-
expected with virtual environments. In other words, when a virtual
53-
environment is active, they install Python packages into the virtual
54-
environment without needing to be told to do so explicitly.
55-
56-
When a virtual environment is active (i.e., the virtual environment's Python
57-
interpreter is running), the attributes :attr:`sys.prefix` and
58-
:attr:`sys.exec_prefix` point to the base directory of the virtual
59-
environment, whereas :attr:`sys.base_prefix` and
60-
:attr:`sys.base_exec_prefix` point to the non-virtual environment Python
61-
installation which was used to create the virtual environment. If a virtual
62-
environment is not active, then :attr:`sys.prefix` is the same as
63-
:attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as
64-
:attr:`sys.base_exec_prefix` (they all point to a non-virtual environment
65-
Python installation).
66-
67-
When a virtual environment is active, any options that change the
68-
installation path will be ignored from all ``setuptools`` configuration
69-
files to prevent projects being inadvertently installed outside of the
70-
virtual environment.
71-
72-
When working in a command shell, users can make a virtual environment active
73-
by running an ``activate`` script in the virtual environment's executables
74-
directory (the precise filename and command to use the file is
75-
shell-dependent), which prepends the virtual environment's directory for
76-
executables to the ``PATH`` environment variable for the running shell. There
77-
should be no need in other circumstances to activate a virtual
78-
environment; scripts installed into virtual environments have a "shebang"
79-
line which points to the virtual environment's Python interpreter. This means
80-
that the script will run with that interpreter regardless of the value of
81-
``PATH``. On Windows, "shebang" line processing is supported if you have the
82-
Python Launcher for Windows installed (this was added to Python in 3.3 - see
83-
:pep:`397` for more details). Thus, double-clicking an installed script in a
84-
Windows Explorer window should run the script with the correct interpreter
85-
without there needing to be any reference to its virtual environment in
86-
``PATH``.
52+
When a Python interpreter is running from a virtual environment,
53+
:data:`sys.prefix` and :data:`sys.exec_prefix`
54+
point to the directories of the virtual environment,
55+
whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`
56+
point to those of the base Python used to create the environment.
57+
It is sufficient to check
58+
``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
59+
running from a virtual environment.
60+
61+
A virtual environment may be "activated" using a script in its binary directory
62+
(``bin`` on POSIX; ``Scripts`` on Windows).
63+
This will prepend that directory to your :envvar:`!PATH`, so that running
64+
:program:`!python` will invoke the environment's Python interpreter
65+
and you can run installed scripts without having to use their full path.
66+
The invocation of the activation script is platform-specific
67+
(:samp:`{<venv>}` must be replaced by the path to the directory
68+
containing the virtual environment):
69+
70+
+-------------+------------+--------------------------------------------------+
71+
| Platform | Shell | Command to activate virtual environment |
72+
+=============+============+==================================================+
73+
| POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` |
74+
| +------------+--------------------------------------------------+
75+
| | fish | :samp:`$ source {<venv>}/bin/activate.fish` |
76+
| +------------+--------------------------------------------------+
77+
| | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` |
78+
| +------------+--------------------------------------------------+
79+
| | PowerShell | :samp:`$ {<venv>}/bin/Activate.ps1` |
80+
+-------------+------------+--------------------------------------------------+
81+
| Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` |
82+
| +------------+--------------------------------------------------+
83+
| | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` |
84+
+-------------+------------+--------------------------------------------------+
85+
86+
.. versionadded:: 3.4
87+
:program:`!fish` and :program:`!csh` activation scripts.
88+
89+
.. versionadded:: 3.8
90+
PowerShell activation scripts installed under POSIX for PowerShell Core
91+
support.
92+
93+
You don't specifically *need* to activate a virtual environment,
94+
as you can just specify the full path to that environment's
95+
Python interpreter when invoking Python.
96+
Furthermore, all scripts installed in the environment
97+
should be runnable without activating it.
98+
99+
In order to achieve this, scripts installed into virtual environments have
100+
a "shebang" line which points to the environment's Python interpreter,
101+
i.e. :samp:`#!/{<path-to-venv>}/bin/python`.
102+
This means that the script will run with that interpreter regardless of the
103+
value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if
104+
you have the :ref:`launcher` installed. Thus, double-clicking an installed
105+
script in a Windows Explorer window should run it with the correct interpreter
106+
without the environment needing to be activated or on the :envvar:`!PATH`.
107+
108+
When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
109+
environment variable is set to the path of the environment.
110+
Since explicitly activating a virtual environment is not required to use it,
111+
:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine
112+
whether a virtual environment is being used.
87113

88114
.. warning:: Because scripts installed in environments should not expect the
89115
environment to be activated, their shebang lines contain the absolute paths
@@ -99,6 +125,11 @@ Creating virtual environments
99125
environment in its new location. Otherwise, software installed into the
100126
environment may not work as expected.
101127

128+
You can deactivate a virtual environment by typing ``deactivate`` in your shell.
129+
The exact mechanism is platform-specific and is an internal implementation
130+
detail (typically, a script or shell function will be used).
131+
132+
102133
.. _venv-api:
103134

104135
API

‎Doc/requirements.txt‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,7 @@ sphinx==4.5.0
77

88
blurb
99

10-
# sphinx-lint 0.6.2 yields many default role errors due to the new regular
11-
# expression used for default role detection, so we don't use the version
12-
# until the errors are fixed.
13-
sphinx-lint==0.6.5
10+
sphinx-lint==0.6.7
1411

1512
# The theme used by the documentation is stored separately, so we need
1613
# to install that as well.

‎Doc/using/venv-create.inc‎

Lines changed: 0 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual
105105
environment will be created, according to the given options, at each provided
106106
path.
107107
108-
Once a virtual environment has been created, it can be "activated" using a
109-
script in the virtual environment's binary directory. The invocation of the
110-
script is platform-specific (`<venv>` must be replaced by the path of the
111-
directory containing the virtual environment):
112-
113-
+-------------+-----------------+-----------------------------------------+
114-
| Platform | Shell | Command to activate virtual environment |
115-
+=============+=================+=========================================+
116-
| POSIX | bash/zsh | $ source <venv>/bin/activate |
117-
+-------------+-----------------+-----------------------------------------+
118-
| | fish | $ source <venv>/bin/activate.fish |
119-
+-------------+-----------------+-----------------------------------------+
120-
| | csh/tcsh | $ source <venv>/bin/activate.csh |
121-
+-------------+-----------------+-----------------------------------------+
122-
| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
123-
+-------------+-----------------+-----------------------------------------+
124-
| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
125-
+-------------+-----------------+-----------------------------------------+
126-
| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
127-
+-------------+-----------------+-----------------------------------------+
128-
129-
When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment
130-
variable is set to the path of the virtual environment. This can be used to
131-
check if one is running inside a virtual environment.
132-
133-
You don't specifically *need* to activate an environment; activation just
134-
prepends the virtual environment's binary directory to your path, so that
135-
"python" invokes the virtual environment's Python interpreter and you can run
136-
installed scripts without having to use their full path. However, all scripts
137-
installed in a virtual environment should be runnable without activating it,
138-
and run with the virtual environment's Python automatically.
139-
140-
You can deactivate a virtual environment by typing "deactivate" in your shell.
141-
The exact mechanism is platform-specific and is an internal implementation
142-
detail (typically a script or shell function will be used).
143-
144-
.. versionadded:: 3.4
145-
``fish`` and ``csh`` activation scripts.
146-
147-
.. versionadded:: 3.8
148-
PowerShell activation scripts installed under POSIX for PowerShell Core
149-
support.

‎Doc/whatsnew/3.10.rst‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2152,8 +2152,7 @@ Porting to Python 3.10
21522152
* The ``PY_SSIZE_T_CLEAN`` macro must now be defined to use
21532153
:c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` formats which use
21542154
``#``: ``es#``, ``et#``, ``s#``, ``u#``, ``y#``, ``z#``, ``U#`` and ``Z#``.
2155-
See :ref:`Parsing arguments and building values
2156-
<arg-parsing>` and the :pep:`353`.
2155+
See :ref:`arg-parsing` and :pep:`353`.
21572156
(Contributed by Victor Stinner in :issue:`40943`.)
21582157
21592158
* Since :c:func:`Py_REFCNT()` is changed to the inline static function,
@@ -2184,8 +2183,7 @@ Porting to Python 3.10
21842183
:c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome` and
21852184
:c:func:`Py_GetProgramName` functions now return ``NULL`` if called before
21862185
:c:func:`Py_Initialize` (before Python is initialized). Use the new
2187-
:ref:`Python Initialization Configuration API <init-config>` to get the
2188-
:ref:`Python Path Configuration. <init-path-config>`.
2186+
:ref:`init-config` API to get the :ref:`init-path-config`.
21892187
(Contributed by Victor Stinner in :issue:`42260`.)
21902188
21912189
* :c:func:`PyList_SET_ITEM`, :c:func:`PyTuple_SET_ITEM` and
@@ -2199,7 +2197,7 @@ Porting to Python 3.10
21992197
``picklebufobject.h``, ``pyarena.h``, ``pyctype.h``, ``pydebug.h``,
22002198
``pyfpe.h``, and ``pytime.h`` have been moved to the ``Include/cpython``
22012199
directory. These files must not be included directly, as they are already
2202-
included in ``Python.h``: :ref:`Include Files <api-includes>`. If they have
2200+
included in ``Python.h``; see :ref:`api-includes`. If they have
22032201
been included directly, consider including ``Python.h`` instead.
22042202
(Contributed by Nicholas Sim in :issue:`35134`.)
22052203

‎Doc/whatsnew/3.11.rst‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -799,6 +799,26 @@ locale
799799
``locale.getpreferredencoding(False)`` but ignores the
800800
:ref:`Python UTF-8 Mode <utf8-mode>`.
801801

802+
803+
.. _whatsnew311-logging:
804+
805+
logging
806+
-------
807+
808+
* Added :func:`~logging.getLevelNamesMapping`
809+
to return a mapping from logging level names (e.g. ``'CRITICAL'``)
810+
to the values of their corresponding :ref:`levels` (e.g. ``50``, by default).
811+
(Contributed by Andrei Kulakovin in :gh:`88024`.)
812+
813+
* Added a :meth:`~logging.handlers.SysLogHandler.createSocket` method
814+
to :class:`~logging.handlers.SysLogHandler`, to match
815+
:meth:`SocketHandler.createSocket()
816+
<logging.handlers.SocketHandler.createSocket>`.
817+
It is called automatically during handler initialization
818+
and when emitting an event, if there is no active socket.
819+
(Contributed by Kirill Pinchuk in :gh:`88457`.)
820+
821+
802822
math
803823
----
804824

@@ -1108,13 +1128,25 @@ warnings
11081128
providing a more concise way to locally ignore warnings or convert them to errors.
11091129
(Contributed by Zac Hatfield-Dodds in :issue:`47074`.)
11101130

1131+
1132+
.. _whatsnew311-zipfile:
1133+
11111134
zipfile
11121135
-------
11131136

1114-
* Added support for specifying member name encoding for reading
1115-
metadata in the zipfile's directory and file headers.
1137+
* Added support for specifying member name encoding for reading metadata
1138+
in a :class:`~zipfile.ZipFile`'s directory and file headers.
11161139
(Contributed by Stephen J. Turnbull and Serhiy Storchaka in :issue:`28080`.)
11171140

1141+
* Added :meth:`ZipFile.mkdir() <zipfile.ZipFile.mkdir>`
1142+
for creating new directories inside ZIP archives.
1143+
(Contributed by Sam Ezeh in :gh:`49083`.)
1144+
1145+
* Added :attr:`~zipfile.Path.stem`, :attr:`~zipfile.Path.suffix`
1146+
and :attr:`~zipfile.Path.suffixes` to :class:`zipfile.Path`.
1147+
(Contributed by Miguel Brito in :gh:`88261`.)
1148+
1149+
11181150
fcntl
11191151
-----
11201152

0 commit comments

Comments
 (0)