8000 Merge branch 'main' into patch-11 · python/cpython@ad3816b · GitHub
[go: up one dir, main page]
Skip to content

Commit ad3816b

Browse files
sobolevnsobolevn
authored
Merge branch 'main' into patch-11
2 parents f1a23cb + 8af04cd commit ad3816b

25 files changed

+294
-347
lines changed

‎Doc/conf.py

Lines changed: 0 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -239,28 +239,3 @@
239239
# Relative filename of the data files
240240
refcount_file = 'data/refcounts.dat'
241241
stable_abi_file = 'data/stable_abi.dat'
242-
243-
# Sphinx 2 and Sphinx 3 compatibility
244-
# -----------------------------------
245-
246-
# bpo-40204: Allow Sphinx 2 syntax in the C domain
247-
c_allow_pre_v3 = True
248-
249-
# bpo-40204: Disable warnings on Sphinx 2 syntax of the C domain since the
250-
# documentation is built with -W (warnings treated as errors).
251-
c_warn_on_allowed_pre_v3 = False
252-
253-
# Fix '!' not working with C domain when pre_v3 is enabled
254-
import sphinx
255-
256-
if sphinx.version_info[:2] < (5, 3):
257-
from sphinx.domains.c import CXRefRole
258-
259-
original_run = CXRefRole.run
260-
261-
def new_run(self):
262-
if self.disabled:
263-
return super(CXRefRole, self).run()
264-
return original_run(self)
265-
266-
CXRefRole.run = new_run

‎Doc/extending/newtypes.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ a special case, for which the new value passed to the handler is ``NULL``.
208208
Python supports two pairs of attribute handlers; a type that supports attributes
209209
only needs to implement the functions for one pair. The difference is that one
210210
pair takes the name of the attribute as a :c:expr:`char\*`, while the other
211-
accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more
211+
accepts a :c:expr:`PyObject*`. Each type can use whichever pair makes more
212212
sense for the implementation's convenience. ::
213213

214214
getattrfunc tp_getattr; /* char * version */
@@ -219,7 +219,7 @@ sense for the implementation's convenience. ::
219219

220220
If accessing attributes of an object is always a simple operation (this will be
221221
explained shortly), there are generic implementations which can be used to
222-
provide the :c:type:`PyObject\*` version of the attribute management functions.
222+
provide the :c:expr:`PyObject*` version of the attribute management functions.
223223
The actual need for type-specific attribute handlers almost completely
224224
disappeared starting with Python 2.2, though there are many examples which have
225225
not been updated to use some of the new generic mechanism that is available.
@@ -341,7 +341,7 @@ Type-specific Attribute Management
341341

342342
For simplicity, only the :c:expr:`char\*` version will be demonstrated here; the
343343
type of the name parameter is the only difference between the :c:expr:`char\*`
344-
and :c:type:`PyObject\*` flavors of the interface. This example effectively does
344+
and :c:expr:`PyObject*` flavors of the interface. This example effectively does
345345
the same thing as the generic example above, but does not use the generic
346346
support added in Python 2.2. It explains how the handler functions are
347347
called, so that if you do need to extend their functionality, you'll understand

‎Doc/extending/newtypes_tutorial.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ The Basics
2424
==========
2525

2626
The :term:`CPython` runtime sees all Python objects as variables of type
27-
:c:type:`PyObject\*`, which serves as a "base type" for all Python objects.
27+
:c:expr:`PyObject*`, which serves as a "base type" for all Python objects.
2828
The :c:type:`PyObject` structure itself only contains the object's
2929
:term:`reference count` and a pointer to the object's "type object".
3030
This is where the action is; the type object determines which (C) functions

‎Doc/howto/isolating-extensions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -411,7 +411,7 @@ that subclass, which may be defined in different module than yours.
411411
pass
412412
413413
For a method to get its "defining class", it must use the
414-
:c:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
414+
:data:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`
415415
:c:type:`calling convention <PyMethodDef>`
416416
and the corresponding :c:type:`PyCMethod` signature::
417417

‎Doc/library/importlib.metadata.rst

Lines changed: 73 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,39 @@
1313

1414
**Source code:** :source:`Lib/importlib/metadata/__init__.py`
1515

16-
``importlib.metadata`` is a library that provides access to installed
17-
package metadata, such as its entry points or its
18-
top-level name. Built in part on Python's import system, this library
16+
``importlib_metadata`` is a library that provides access to
17+
the metadata of an installed `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
18+
such as its entry points
19+
or its top-level names (`Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_\s, modules, if any).
20+
Built in part on Python's import system, this library
1921
intends to replace similar functionality in the `entry point
2022
API`_ and `metadata API`_ of ``pkg_resources``. Along with
2123
:mod:`importlib.resources`,
2224
this package can eliminate the need to use the older and less efficient
2325
``pkg_resources`` package.
2426

25-
By "installed package" we generally mean a third-party package installed into
26-
Python's ``site-packages`` directory via tools such as `pip
27-
<https://pypi.org/project/pip/>`_. Specifically,
28-
it means a package with either a discoverable ``dist-info`` or ``egg-info``
29-
directory, and metadata defined by :pep:`566` or its older specifications.
30-
By default, package metadata can live on the file system or in zip archives on
27+
``importlib_metadata`` operates on third-party *distribution packages*
28+
installed into Python's ``site-packages`` directory via tools such as
29+
`pip <https://pypi.org/project/pip/>`_.
30+
Specifically, it works with distributions with discoverable
31+
``dist-info`` or ``egg-info`` directories,
32+
and metadata defined by the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_.
33+
34+
.. important::
35+
36+
These are *not* necessarily equivalent to or correspond 1:1 with
37+
the top-level *import package* names
38+
that can be imported inside Python code.
39+
One *distribution package* can contain multiple *import packages*
40+
(and single modules),
41+
and one top-level *import package*
42+
may map to multiple *distribution packages*
43+
if it is a namespace package.
44+
You can use :ref:`package_distributions() <package-distributions>`
45+
to get a mapping between them.
46+
47+
By default, distribution metadata can live on the file system
48+
or in zip archives on
3149
:data:`sys.path`. Through an extension mechanism, the metadata can live almost
3250
anywhere.
3351

@@ -37,12 +55,19 @@ anywhere.
3755
https://importlib-metadata.readthedocs.io/
3856
The documentation for ``importlib_metadata``, which supplies a
3957
backport of ``importlib.metadata``.
58+
This includes an `API reference
59+
<https://importlib-metadata.readthedocs.io/en/latest/api.html>`__
60+
for this module's classes and functions,
61+
as well as a `migration guide
62+
<https://importlib-metadata.readthedocs.io/en/latest/migration.html>`__
63+
for existing users of ``pkg_resources``.
4064

4165

4266
Overview
4367
========
4468

45-
Let's say you wanted to get the version string for a package you've installed
69+
Let's say you wanted to get the version string for a
70+
`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ you've installed
4671
using ``pip``. We start by creating a virtual environment and installing
4772
something into it:
4873

@@ -151,19 +176,19 @@ for more information on entry points, their definition, and usage.
151176
The "selectable" entry points were introduced in ``importlib_metadata``
152177
3.6 and Python 3.10. Prior to those changes, ``entry_points`` accepted
153178
no parameters and always returned a dictionary of entry points, keyed
154-
by group. For compatibility, if no parameters are passed to entry_points,
155-
a ``SelectableGroups`` object is returned, implementing that dict
156-
interface. In the future, calling ``entry_points`` with no parameters
157-
will return an ``EntryPoints`` object. Users should rely on the selection
158-
interface to retrieve entry points by group.
179+
by group. With ``importlib_metadata`` 5.0 and Python 3.12,
180+
``entry_points`` always returns an ``EntryPoints`` object. See
181+
`backports.entry_points_selectable <https://pypi.org/project/backports.entry_points_selectable>`_
182+
for compatibility options.
159183

160184

161185
.. _metadata:
162186

163187
Distribution metadata
164188
---------------------
165189

166-
Every distribution includes some metadata, which you can extract using the
190+
Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,
191+
which you can extract using the
167192
``metadata()`` function::
168193

169194
>>> wheel_metadata = metadata('wheel') # doctest: +SKIP
@@ -201,7 +226,8 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
201226
Distribution versions
202227
---------------------
203228

204-
The ``version()`` function is the quickest way to get a distribution's version
229+
The ``version()`` function is the quickest way to get a
230+
`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_'s version
205231
number, as a string::
206232

207233
>>> version('wheel') # doctest: +SKIP
@@ -214,7 +240,8 @@ Distribution files
214240
------------------
215241

216242
You can also get the full set of files contained within a distribution. The
217-
``files()`` function takes a distribution package name and returns all of the
243+
``files()`` function takes a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ name
244+
and returns all of the
218245
files installed by this distribution. Each file object returned is a
219246
``PackagePath``, a :class:`pathlib.PurePath` derived object with additional ``dist``,
220247
``size``, and ``hash`` properties as indicated by the metadata. For example::
@@ -259,19 +286,24 @@ distribution is not known to have the metadata present.
259286
Distribution requirements
260287
-------------------------
261288

262-
To get the full set of requirements for a distribution, use the ``requires()``
289+
To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
290+
use the ``requires()``
263291
function::
264292

265293
>>> requires('wheel') # doctest: +SKIP
266294
["pytest (>=3.0.0) ; extra == 'test'", "pytest-cov ; extra == 'test'"]
267295

268296

269-
Package distributions
270-
---------------------
297+
.. _package-distributions:
298+
.. _import-distribution-package-mapping:
299+
300+
Mapping import to distribution packages
301+
---------------------------------------
271302

272-
A convenience method to resolve the distribution or
273-
distributions (in the case of a namespace package) for top-level
274-
Python packages or modules::
303+
A convenience method to resolve the `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
304+
name (or names, in the case of a namespace package)
305+
that provide each importable top-level
306+
Python module or `Import Package <https://packaging.python.org/en/latest/glossary/#term-Import-Package>`_::
275307

276308
>>> packages_distributions()
277309
{'importlib_metadata': ['importlib-metadata'], 'yaml': ['PyYAML'], 'jaraco': ['jaraco.classes', 'jaraco.functools'], ...}
@@ -285,7 +317,8 @@ Distributions
285317

286318
While the above API is the most common and convenient usage, you can get all
287319
of that information from the ``Distribution`` class. A ``Distribution`` is an
288-
abstract object that represents the metadata for a Python package. You can
320+
abstract object that represents the metadata for
321+
a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_. You can
289322
get the ``Distribution`` instance::
290323

291324
>>> from importlib.metadata import distribution # doctest: +SKIP
@@ -305,14 +338,16 @@ instance::
305338
>>> dist.metadata['License'] # doctest: +SKIP
306339
'MIT'
307340

308-
The full set of available metadata is not described here. See :pep:`566`
309-
for additional details.
341+
The full set of available metadata is not described here.
342+
See the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
310343

311344

312345
Distribution Discovery
313346
======================
314347

315-
By default, this package provides built-in support for discovery of metadata for file system and zip file packages. This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:
348+
By default, this package provides built-in support for discovery of metadata
349+
for file system and zip file `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_\s.
350+
This metadata finder search defaults to ``sys.path``, but varies slightly in how it interprets those values from how other import machinery does. In particular:
316351

317352
- ``importlib.metadata`` does not honor :class:`bytes` objects on ``sys.path``.
318353
- ``importlib.metadata`` will incidentally honor :py:class:`pathlib.Path` objects on ``sys.path`` even though such values will be ignored for imports.
@@ -321,15 +356,18 @@ By default, this package provides built-in support for discovery of metadata for
321356
Extending the search algorithm
322357
==============================
323358

324-
Because package metadata is not available through :data:`sys.path` searches, or
325-
package loaders directly, the metadata for a package is found through import
326-
system :ref:`finders <finders-and-loaders>`. To find a distribution package's metadata,
359+
Because `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ metadata
360+
is not available through :data:`sys.path` searches, or
361+
package loaders directly,
362+
the metadata for a distribution is found through import
363+
system `finders`_. To find a distribution package's metadata,
327364
``importlib.metadata`` queries the list of :term:`meta path finders <meta path finder>` on
328365
:data:`sys.meta_path`.
329366

330-
The default ``PathFinder`` for Python includes a hook that calls into
331-
``importlib.metadata.MetadataPathFinder`` for finding distributions
332-
loaded from typical file-system-based paths.
367+
By default ``importlib_metadata`` installs a finder for distribution packages
368+
found on the file system.
369+
This finder doesn't actually find any *distributions*,
370+
but it can find their metadata.
333371

334372
The abstract class :py:class:`importlib.abc.MetaPathFinder` defines the
335373
interface expected of finders by Python's import system.
@@ -358,4 +396,4 @@ a custom finder, return instances of this derived ``Distribution`` in the
358396

359397
.. _`entry point API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
360398
.. _`metadata API`: https://setuptools.readthedocs.io/en/latest/pkg_resources.html#metadata-api
361-
.. _`importlib_resources`: https://importlib-resources.readthedocs.io/en/latest/index.html
399+
.. _`finders`: https://docs.python.org/3/reference/import.html#finders-and-loaders

‎Doc/reference/expressions.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1766,6 +1766,13 @@ Or, when processing a file stream in chunks:
17661766
while chunk := file.read(9000):
17671767
process(chunk)
17681768
1769+
Assignment expressions must be surrounded by parentheses when used
1770+
as sub-expressions in slicing, conditional, lambda,
1771+
keyword-argument, and comprehension-if expressions
1772+
and in ``assert`` and ``with`` statements.
1773+
In all other places where they can be used, parentheses are not required,
1774+
including in ``if`` and ``while`` statements.
1775+
17691776
.. versionadded:: 3.8
17701777
See :pep:`572` for more details about assignment expressions.
17711778

‎Doc/requirements.txt

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

88
blurb
99

10-
sphinx-lint<1
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<1,!=0.6.2
1114

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

‎Doc/whatsnew/2.2.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1102,7 +1102,7 @@ code, none of the changes described here will affect you very much.
11021102
* A different argument parsing function, :c:func:`PyArg_UnpackTuple`, has been
11031103
added that's simpler and presumably faster. Instead of specifying a format
11041104
string, the caller simply gives the minimum and maximum number of arguments
1105-
expected, and a set of pointers to :c:type:`PyObject\*` variables that will be
1105+
expected, and a set of pointers to :c:expr:`PyObject*` variables that will be
11061106
filled in with argument values.
11071107

11081108
* Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method

‎Doc/whatsnew/2.5.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1725,7 +1725,7 @@ attribute of the function object to change this::
17251725
``ctypes.pythonapi`` object. This object does *not* release the global
17261726
interpreter lock before calling a function, because the lock must be held when
17271727
calling into the interpreter's code. There's a :class:`py_object()` type
1728-
constructor that will create a :c:type:`PyObject \*` pointer. A simple usage::
1728+
constructor that will create a :c:expr:`PyObject *` pointer. A simple usage::
17291729

17301730
import ctypes
17311731

‎Doc/whatsnew/3.10.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -669,6 +669,7 @@ Several other key features:
669669
GREEN = 1
670670
BLUE = 2
671671
672+
color = Color.GREEN
672673
match color:
673674
case Color.RED:
674675
print("I see red!")

‎Lib/asyncio/base_subprocess.py

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,9 @@ def _process_exited(self, returncode):
216216
self._proc.returncode = returncode
217217
self._call(self._protocol.process_exited)
218218
for p in self._pipes.values():
219-
p.pipe.close()
219+
if p is not None:
220+
p.pipe.close()
221+
220222
self._try_finish()
221223

222224
async def _wait(self):

0 commit comments

Comments
 (0)
0