Merge branch 'main' into pythongh-115999-refactor-load-global

Author: mpage

Doc/c-api/tuple.rst

@@ -167,7 +167,8 @@ type.
 
    .. c:member:: const char *name
 
-      Name of the struct sequence type.
+      Fully qualified name of the type; null-terminated UTF-8 encoded.
+      The name must contain the module name.
 
    .. c:member:: const char *doc
 

Doc/c-api/unicode.rst

@@ -1438,6 +1438,31 @@ They all return ``NULL`` or ``-1`` if an exception occurs.
    This function returns ``-1`` upon failure, so one should call
    :c:func:`PyErr_Occurred` to check for errors.
 
+   .. seealso::
+
+      The :c:func:`PyUnicode_Equal` function.
+
+
+.. c:function:: int PyUnicode_Equal(PyObject *a, PyObject *b)
+
+   Test if two strings are equal:
+
+   * Return ``1`` if *a* is equal to *b*.
+   * Return ``0`` if *a* is not equal to *b*.
+   * Set a :exc:`TypeError` exception and return ``-1`` if *a* or *b* is not a
+     :class:`str` object.
+
+   The function always succeeds if *a* and *b* are :class:`str` objects.
+
+   The function works for :class:`str` subclasses, but does not honor custom
+   ``__eq__()`` method.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_Compare` function.
+
+   .. versionadded:: 3.14
+
 
 .. c:function:: int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)
 

Doc/data/stable_abi.dat

@@ -1160,16 +1160,12 @@ Glossary
       (subscript) notation uses :class:`slice` objects internally.
 
    soft deprecated
-      A soft deprecation can be used when using an API which should no longer
-      be used to write new code, but it remains safe to continue using it in
-      existing code. The API remains documented and tested, but will not be
-      developed further (no enhancement).
+      A soft deprecated API should not be used in new code,
+      but it is safe for already existing code to use it.
+      The API remains documented and tested, but will not be enhanced further.
 
-      The main difference between a "soft" and a (regular) "hard" deprecation
-      is that the soft deprecation does not imply scheduling the removal of the
-      deprecated API.
-
-      Another difference is that a soft deprecation does not issue a warning.
+      Soft deprecation, unlike normal deprecation, does not plan on removing the API
+      and will not emit warnings.
 
       See `PEP 387: Soft Deprecation
       <https://peps.python.org/pep-0387/#soft-deprecation>`_.

Doc/glossary.rst

@@ -213,9 +213,8 @@ In addition to these methods, lock objects can also be used via the
 
 .. index:: pair: module; signal
 
-* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
-  exception will be received by an arbitrary thread.  (When the :mod:`signal`
-  module is available, interrupts always go to the main thread.)
+* Interrupts always go to the main thread (the :exc:`KeyboardInterrupt`
+  exception will be received by that thread.)
 
 * Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
   equivalent to calling :func:`_thread.exit`.
@@ -229,7 +228,3 @@ In addition to these methods, lock objects can also be used via the
   :keyword:`try` ... :keyword:`finally` clauses or executing object
   destructors.
 
-* When the main thread exits, it does not do any of its usual cleanup (except
-  that :keyword:`try` ... :keyword:`finally` clauses are honored), and the
-  standard I/O files are not flushed.
-

Doc/library/_thread.rst

@@ -100,6 +100,13 @@ You can also get a :ref:`distribution's version number <version>`, list its
 :ref:`requirements`.
 
 
+.. exception:: PackageNotFoundError
+
+   Subclass of :class:`ModuleNotFoundError` raised by several functions in this
+   module when queried for a distribution package which is not installed in the
+   current Python environment.
+
+
 Functional API
 ==============
 
@@ -111,31 +118,53 @@ This package provides the following functionality via its public API.
 Entry points
 ------------
 
-The ``entry_points()`` function returns a collection of entry points.
-Entry points are represented by ``EntryPoint`` instances;
-each ``EntryPoint`` has a ``.name``, ``.group``, and ``.value`` attributes and
-a ``.load()`` method to resolve the value. There are also ``.module``,
-``.attr``, and ``.extras`` attributes for getting the components of the
-``.value`` attribute.
+.. function:: entry_points(**select_params)
+
+   Returns a :class:`EntryPoints` instance describing entry points for the
+   current environment. Any given keyword parameters are passed to the
+   :meth:`!select` method for comparison to the attributes of
+   the individual entry point definitions.
+
+   Note: it is not currently possible to query for entry points based on
+   their :attr:`!EntryPoint.dist` attribute (as different :class:`!Distribution`
+   instances do not currently compare equal, even if they have the same attributes)
+
+.. class:: EntryPoints
+
+   Details of a collection of installed entry points.
+
+   Also provides a ``.groups`` attribute that reports all identifed entry
+   point groups, and a ``.names`` attribute that reports all identified entry
+   point names.
+
+.. class:: EntryPoint
+
+   Details of an installed entry point.
+
+   Each :class:`!EntryPoint` instance has ``.name``, ``.group``, and ``.value``
+   attributes and a ``.load()`` method to resolve the value. There are also
+   ``.module``, ``.attr``, and ``.extras`` attributes for getting the
+   components of the ``.value`` attribute, and ``.dist`` for obtaining
+   information regarding the distribution package that provides the entry point.
 
 Query all entry points::
 
     >>> eps = entry_points()  # doctest: +SKIP
 
-The ``entry_points()`` function returns an ``EntryPoints`` object,
-a collection of all ``EntryPoint`` objects with ``names`` and ``groups``
+The :func:`!entry_points` function returns a :class:`!EntryPoints` object,
+a collection of all :class:`!EntryPoint` objects with ``names`` and ``groups``
 attributes for convenience::
 
     >>> sorted(eps.groups)  # doctest: +SKIP
     ['console_scripts', 'distutils.commands', 'distutils.setup_keywords', 'egg_info.writers', 'setuptools.installation']
 
-``EntryPoints`` has a ``select`` method to select entry points
+:class:`!EntryPoints` has a :meth:`!select` method to select entry points
 matching specific properties. Select entry points in the
 ``console_scripts`` group::
 
     >>> scripts = eps.select(group='console_scripts')  # doctest: +SKIP
 
-Equivalently, since ``entry_points`` passes keyword arguments
+Equivalently, since :func:`!entry_points` passes keyword arguments
 through to select::
 
     >>> scripts = entry_points(group='console_scripts')  # doctest: +SKIP
@@ -189,31 +218,41 @@ for more information on entry points, their definition, and usage.
 Distribution metadata
 ---------------------
 
-Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ includes some metadata,
-which you can extract using the
-``metadata()`` function::
+.. function:: metadata(distribution_name)
+
+   Return the distribution metadata corresponding to the named
+   distribution package as a :class:`PackageMetadata` instance.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+.. class:: PackageMetadata
+
+   A concrete implementation of the
+    `PackageMetadata protocol <https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata>`_.
+
+    In addition to providing the defined protocol methods and attributes, subscripting
+    the instance is equivalent to calling the :meth:`!get` method.
+
+Every `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
+includes some metadata, which you can extract using the :func:`!metadata` function::
 
     >>> wheel_metadata = metadata('wheel')  # doctest: +SKIP
 
-The keys of the returned data structure, a ``PackageMetadata``,
-name the metadata keywords, and
+The keys of the returned data structure name the metadata keywords, and
 the values are returned unparsed from the distribution metadata::
 
     >>> wheel_metadata['Requires-Python']  # doctest: +SKIP
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
 
-``PackageMetadata`` also presents a ``json`` attribute that returns
+:class:`PackageMetadata` also presents a :attr:`!json` attribute that returns
 all the metadata in a JSON-compatible form per :PEP:`566`::
 
     >>> wheel_metadata.json['requires_python']
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
 
-.. note::
-
-    The actual type of the object returned by ``metadata()`` is an
-    implementation detail and should be accessed only through the interface
-    described by the
-    `PackageMetadata protocol <https://importlib-metadata.readthedocs.io/en/latest/api.html#importlib_metadata.PackageMetadata>`_.
+The full set of available metadata is not described here.
+See the PyPA `Core metadata specification <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
 
 .. versionchanged:: 3.10
    The ``Description`` is now included in the metadata when presented
@@ -227,7 +266,15 @@ all the metadata in a JSON-compatible form per :PEP:`566`::
 Distribution versions
 ---------------------
 
-The ``version()`` function is the quickest way to get a
+.. function:: version(distribution_name)
+
+   Return the installed distribution package version for the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+The :func:`!version` function is the quickest way to get a
 `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_'s version
 number, as a string::
 
@@ -240,12 +287,28 @@ number, as a string::
 Distribution files
 ------------------
 
-You can also get the full set of files contained within a distribution. The
-``files()`` function takes a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_ name
-and returns all of the
-files installed by this distribution. Each file object returned is a
-``PackagePath``, a :class:`pathlib.PurePath` derived object with additional ``dist``,
-``size``, and ``hash`` properties as indicated by the metadata. For example::
+.. function:: files(distribution_name)
+
+   Return the full set of files contained within the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+   Returns :const:`None` if the distribution is found but the installation
+   database records reporting the files associated with the distribuion package
+   are missing.
+
+.. class:: PackagePath
+
+    A :class:`pathlib.PurePath` derived object with additional ``dist``,
+    ``size``, and ``hash`` properties corresponding to the distribution
+    package's installation metadata for that file.
+
+The :func:`!files` function takes a
+`Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
+name and returns all of the files installed by this distribution. Each file is reported
+as a :class:`PackagePath` instance. For example::
 
     >>> util = [p for p in files('wheel') if 'util.py' in str(p)][0]  # doctest: +SKIP
     >>> util  # doctest: +SKIP
@@ -268,16 +331,16 @@ Once you have the file, you can also read its contents::
             return s.encode('utf-8')
         return s
 
-You can also use the ``locate`` method to get a the absolute path to the
-file::
+You can also use the :meth:`!locate` method to get the absolute
+path to the file::
 
     >>> util.locate()  # doctest: +SKIP
     PosixPath('/home/gustav/example/lib/site-packages/wheel/util.py')
 
 In the case where the metadata file listing files
-(RECORD or SOURCES.txt) is missing, ``files()`` will
-return ``None``. The caller may wish to wrap calls to
-``files()`` in `always_iterable
+(``RECORD`` or ``SOURCES.txt``) is missing, :func:`!files` will
+return :const:`None`. The caller may wish to wrap calls to
+:func:`!files` in `always_iterable
 <https://more-itertools.readthedocs.io/en/stable/api.html#more_itertools.always_iterable>`_
 or otherwise guard against this condition if the target
 distribution is not known to have the metadata present.
@@ -287,8 +350,16 @@ distribution is not known to have the metadata present.
 Distribution requirements
 -------------------------
 
+.. function:: requires(distribution_name)
+
+   Return the declared dependency specifiers for the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
 To get the full set of requirements for a `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_,
-use the ``requires()``
+use the :func:`!requires`
 function::
 
     >>> requires('wheel')  # doctest: +SKIP
@@ -301,6 +372,16 @@ function::
 Mapping import to distribution packages
 ---------------------------------------
 
+.. function:: packages_distributions()
+
+   Return a mapping from the top level module and import package
+   names found via :attr:`sys.meta_path` to the names of the distribution
+   packages (if any) that provide the corresponding files.
+
+   To allow for namespace packages (which may have members provided by
+   multiple distribution packages), each top level import name maps to a
+   list of distribution names rather than mapping directly to a single name.
+
 A convenience method to resolve the `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_
 name (or names, in the case of a namespace package)
 that provide each importable top-level
@@ -320,23 +401,42 @@ function is not reliable with such installs.
 Distributions
 =============
 
-While the above API is the most common and convenient usage, you can get all
-of that information from the ``Distribution`` class. A ``Distribution`` is an
-abstract object that represents the metadata for
-a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_. You can
-get the ``Distribution`` instance::
+.. function:: distribution(distribution_name)
+
+   Return a :class:`Distribution` instance describing the named
+   distribution package.
+
+   Raises :exc:`PackageNotFoundError` if the named distribution
+   package is not installed in the current Python environment.
+
+.. class:: Distribution
+
+   Details of an installed distribution package.
+
+   Note: different :class:`!Distribution` instances do not currently compare
+   equal, even if they relate to the same installed distribution and
+   accordingly have the same attributes.
+
+While the module level API described above is the most common and convenient usage,
+you can get all of that information from the :class:`!Distribution` class.
+:class:`!Distribution` is an abstract object that represents the metadata for
+a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_.
+You can get the concreate :class:`!Distribution` subclass instance for an installed
+distribution package by calling the :func:`distribution` function::
 
     >>> from importlib.metadata import distribution  # doctest: +SKIP
     >>> dist = distribution('wheel')  # doctest: +SKIP
+    >>> type(dist)  # doctest: +SKIP
+    <class 'importlib.metadata.PathDistribution'>
 
 Thus, an alternative way to get the version number is through the
-``Distribution`` instance::
+:class:`!Distribution` instance::
 
     >>> dist.version  # doctest: +SKIP
     '0.32.3'
 
-There are all kinds of additional metadata available on the ``Distribution``
-instance::
+There are all kinds of additional metadata available on :class:`!Distribution`
+instances::
 
     >>> dist.metadata['Requires-Python']  # doctest: +SKIP
     '>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*'
@@ -350,7 +450,7 @@ metadata::
     'file:///path/to/wheel-0.32.3.editable-py3-none-any.whl'
 
 The full set of available metadata is not described here.
-See the `Core metadata specifications <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
+See the PyPA `Core metadata specification <https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata>`_ for additional details.
 
 .. versionadded:: 3.13
    The ``.origin`` property was added.