Skip to content

Commit

Permalink
[3.12] gh-101100: Consolidate documentation on ModuleType attributes (
Browse files Browse the repository at this point in the history
#124709) (#125211)

Co-authored-by: Hugo van Kemenade <[email protected]>
Co-authored-by: Barry Warsaw <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>
  • Loading branch information
4 people authored Oct 9, 2024
1 parent 046687c commit cba3776
Show file tree
Hide file tree
Showing 21 changed files with 348 additions and 324 deletions.
26 changes: 13 additions & 13 deletions Doc/c-api/import.rst
Original file line number Diff line number Diff line change
Expand Up @@ -120,14 +120,14 @@ Importing Modules
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
not set already, with the appropriate values. The spec's loader will
be set to the module's ``__loader__`` (if set) and to an instance of
:class:`~importlib.machinery.SourceFileLoader` otherwise.
The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
set, if not set already, with the appropriate values. The spec's loader
will be set to the module's :attr:`!__loader__` (if set) and to an instance
of :class:`~importlib.machinery.SourceFileLoader` otherwise.
The module's :attr:`__file__` attribute will be set to the code object's
:attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
be set.
The module's :attr:`~module.__file__` attribute will be set to the code
object's :attr:`~codeobject.co_filename`. If applicable,
:attr:`~module.__cached__` will also be set.
This function will reload the module if it was already imported. See
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
Expand All @@ -139,29 +139,29 @@ Importing Modules
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. versionchanged:: 3.12
The setting of :attr:`__cached__` and :attr:`__loader__` is
deprecated. See :class:`~importlib.machinery.ModuleSpec` for
The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
alternatives.
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
the module object is set to *pathname* if it is non-``NULL``.
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
attribute of the module object is set to *pathname* if it is non-``NULL``.
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
attribute of the module object is set to *cpathname* if it is
non-``NULL``. Of the three functions, this is the preferred one to use.
.. versionadded:: 3.3
.. versionchanged:: 3.12
Setting :attr:`__cached__` is deprecated. See
Setting :attr:`~module.__cached__` is deprecated. See
:class:`~importlib.machinery.ModuleSpec` for alternatives.
Expand Down
22 changes: 12 additions & 10 deletions Doc/c-api/module.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,19 @@ Module Objects
single: __package__ (module attribute)
single: __loader__ (module attribute)
Return a new module object with the :attr:`__name__` attribute set to *name*.
The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
:attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
to ``None``); the caller is responsible for providing a :attr:`__file__`
attribute.
Return a new module object with :attr:`module.__name__` set to *name*.
The module's :attr:`!__name__`, :attr:`~module.__doc__`,
:attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
filled in (all but :attr:`!__name__` are set to ``None``). The caller is
responsible for setting a :attr:`~module.__file__` attribute.
Return ``NULL`` with an exception set on error.
.. versionadded:: 3.3
.. versionchanged:: 3.4
:attr:`__package__` and :attr:`__loader__` are set to ``None``.
:attr:`~module.__package__` and :attr:`~module.__loader__` are now set to
``None``.
.. c:function:: PyObject* PyModule_New(const char *name)
Expand Down Expand Up @@ -77,8 +78,9 @@ Module Objects
single: __name__ (module attribute)
single: SystemError (built-in exception)
Return *module*'s :attr:`__name__` value. If the module does not provide one,
or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
Return *module*'s :attr:`~module.__name__` value. If the module does not
provide one, or if it is not a string, :exc:`SystemError` is raised and
``NULL`` is returned.
.. versionadded:: 3.3
Expand Down Expand Up @@ -108,8 +110,8 @@ Module Objects
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
:attr:`__file__` attribute. If this is not defined, or if it is not a
unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
:attr:`~module.__file__` attribute. If this is not defined, or if it is not a
string, raise :exc:`SystemError` and return ``NULL``; otherwise return
a reference to a Unicode object.
.. versionadded:: 3.2
Expand Down
7 changes: 7 additions & 0 deletions Doc/deprecations/pending-removal-in-3.14.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
Pending Removal in Python 3.14
------------------------------

* The import system:

* Setting :attr:`~module.__loader__` on a module while
failing to set :attr:`__spec__.loader <importlib.machinery.ModuleSpec.loader>`
is deprecated. In Python 3.14, :attr:`!__loader__` will cease to be set or
taken into consideration by the import system or the standard library.

* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
of :class:`!argparse.BooleanOptionalAction` are deprecated
and will be removed in 3.14.
Expand Down
11 changes: 8 additions & 3 deletions Doc/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -437,7 +437,7 @@ Glossary
<meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
entry finders <path entry finder>` for use with :data:`sys.path_hooks`.

See :ref:`importsystem` and :mod:`importlib` for much more detail.
See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail.

floor division
Mathematical division that rounds down to nearest integer. The floor
Expand Down Expand Up @@ -750,8 +750,11 @@ Glossary
loader
An object that loads a module. It must define a method named
:meth:`load_module`. A loader is typically returned by a
:term:`finder`. See :pep:`302` for details and
:class:`importlib.abc.Loader` for an :term:`abstract base class`.
:term:`finder`. See also:

* :ref:`finders-and-loaders`
* :class:`importlib.abc.Loader`
* :pep:`302`

locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
Expand Down Expand Up @@ -821,6 +824,8 @@ Glossary
A namespace containing the import-related information used to load a
module. An instance of :class:`importlib.machinery.ModuleSpec`.

See also :ref:`module-specs`.

MRO
See :term:`method resolution order`.

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -889,7 +889,7 @@ Statements
(indicating a "simple" target). A "simple" target consists solely of a
:class:`Name` node that does not appear between parentheses; all other
targets are considered complex. Only simple targets appear in
the :attr:`__annotations__` dictionary of modules and classes.
the :attr:`~object.__annotations__` dictionary of modules and classes.

.. doctest::

Expand Down
87 changes: 34 additions & 53 deletions Doc/library/importlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ ABC hierarchy::
An abstract method for finding a :term:`spec <module spec>` for
the specified module. If this is a top-level import, *path* will
be ``None``. Otherwise, this is a search for a subpackage or
module and *path* will be the value of :attr:`__path__` from the
module and *path* will be the value of :attr:`~module.__path__` from the
parent package. If a spec cannot be found, ``None`` is returned.
When passed in, ``target`` is a module object that the finder may
use to make a more educated guess about what spec to return.
Expand Down Expand Up @@ -355,34 +355,12 @@ ABC hierarchy::
(note that some of these attributes can change when a module is
reloaded):

- :attr:`__name__`
The module's fully qualified name.
It is ``'__main__'`` for an executed module.

- :attr:`__file__`
The location the :term:`loader` used to load the module.
For example, for modules loaded from a .py file this is the filename.
It is not set on all modules (e.g. built-in modules).

- :attr:`__cached__`
The filename of a compiled version of the module's code.
It is not set on all modules (e.g. built-in modules).

- :attr:`__path__`
The list of locations where the package's submodules will be found.
Most of the time this is a single directory.
The import system passes this attribute to ``__import__()`` and to finders
in the same way as :data:`sys.path` but just for the package.
It is not set on non-package modules so it can be used
as an indicator that the module is a package.

- :attr:`__package__`
The fully qualified name of the package the module is in (or the
empty string for a top-level module).
If the module is a package then this is the same as :attr:`__name__`.

- :attr:`__loader__`
The :term:`loader` used to load the module.
- :attr:`module.__name__`
- :attr:`module.__file__`
- :attr:`module.__cached__`
- :attr:`module.__path__`
- :attr:`module.__package__`
- :attr:`module.__loader__` *(deprecated)*

When :meth:`exec_module` is available then backwards-compatible
functionality is provided.
Expand Down Expand Up @@ -418,7 +396,8 @@ ABC hierarchy::
can implement this abstract method to give direct access
to the data stored. :exc:`OSError` is to be raised if the *path* cannot
be found. The *path* is expected to be constructed using a module's
:attr:`__file__` attribute or an item from a package's :attr:`__path__`.
:attr:`~module.__file__` attribute or an item from a package's
:attr:`~module.__path__`.

.. versionchanged:: 3.4
Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
Expand Down Expand Up @@ -505,9 +484,9 @@ ABC hierarchy::

.. abstractmethod:: get_filename(fullname)

An abstract method that is to return the value of :attr:`__file__` for
the specified module. If no path is available, :exc:`ImportError` is
raised.
An abstract method that is to return the value of
:attr:`~module.__file__` for the specified module. If no path is
available, :exc:`ImportError` is raised.

If source code is available, then the method should return the path to
the source file, regardless of whether a bytecode was used to load the
Expand Down Expand Up @@ -1166,43 +1145,45 @@ find and load modules.
.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)

A specification for a module's import-system-related state. This is
typically exposed as the module's :attr:`__spec__` attribute. Many
typically exposed as the module's :attr:`~module.__spec__` attribute. Many
of these attributes are also available directly on a module: for example,
``module.__spec__.origin == module.__file__``. Note, however, that
while the *values* are usually equivalent, they can differ since there is
no synchronization between the two objects. For example, it is possible to update
the module's :attr:`__file__` at runtime and this will not be automatically
reflected in the module's :attr:`__spec__.origin`, and vice versa.
no synchronization between the two objects. For example, it is possible to
update the module's :attr:`~module.__file__` at runtime and this will not be
automatically reflected in the module's
:attr:`__spec__.origin <ModuleSpec.origin>`, and vice versa.

.. versionadded:: 3.4

.. attribute:: name

The module's fully qualified name
(see :attr:`__name__` attributes on modules).
The module's fully qualified name (see :attr:`module.__name__`).
The :term:`finder` should always set this attribute to a non-empty string.

.. attribute:: loader

The :term:`loader` used to load the module
(see :attr:`__loader__` attributes on modules).
The :term:`loader` used to load the module (see :attr:`module.__loader__`).
The :term:`finder` should always set this attribute.

.. attribute:: origin

The location the :term:`loader` should use to load the module
(see :attr:`__file__` attributes on modules).
For example, for modules loaded from a .py file this is the filename.
(see :attr:`module.__file__`).
For example, for modules loaded from a ``.py`` file this is the filename.
The :term:`finder` should always set this attribute to a meaningful value
for the :term:`loader` to use. In the uncommon case that there is not one
(like for namespace packages), it should be set to ``None``.

.. attribute:: submodule_search_locations

The list of locations where the package's submodules will be found
(see :attr:`__path__` attributes on modules).
Most of the time this is a single directory.
The :term:`finder` should set this attribute to a list, even an empty one, to indicate
A (possibly empty) :term:`sequence` of strings enumerating the locations
in which a package's submodules will be found
(see :attr:`module.__path__`). Most of the time there will only be a
single directory in this list.

The :term:`finder` should set this attribute to a sequence, even an empty
one, to indicate
to the import system that the module is a package. It should be set to ``None`` for
non-package modules. It is set automatically later to a special object for
namespace packages.
Expand All @@ -1216,22 +1197,22 @@ find and load modules.
.. attribute:: cached

The filename of a compiled version of the module's code
(see :attr:`__cached__` attributes on modules).
(see :attr:`module.__cached__`).
The :term:`finder` should always set this attribute but it may be ``None``
for modules that do not need compiled code stored.

.. attribute:: parent

(Read-only) The fully qualified name of the package the module is in (or the
empty string for a top-level module).
See :attr:`__package__` attributes on modules.
See :attr:`module.__package__`.
If the module is a package then this is the same as :attr:`name`.

.. attribute:: has_location

``True`` if the spec's :attr:`origin` refers to a loadable location,
``False`` otherwise. This value impacts how :attr:`origin` is interpreted
and how the module's :attr:`__file__` is populated.
``False`` otherwise. This value impacts how :attr:`!origin` is interpreted
and how the module's :attr:`~module.__file__` is populated.


:mod:`importlib.util` -- Utility code for importers
Expand Down Expand Up @@ -1353,8 +1334,8 @@ an :term:`importer`.

.. versionchanged:: 3.7
Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
**package** is in fact not a package (i.e. lacks a :attr:`__path__`
attribute).
**package** is in fact not a package (i.e. lacks a
:attr:`~module.__path__` attribute).

.. function:: module_from_spec(spec)

Expand Down
3 changes: 2 additions & 1 deletion Doc/library/pkgutil.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ support.
__path__ = extend_path(__path__, __name__)

For each directory on :data:`sys.path` that has a subdirectory that matches the
package name, add the subdirectory to the package's :attr:`__path__`. This is useful
package name, add the subdirectory to the package's
:attr:`~module.__path__`. This is useful
if one wants to distribute different parts of a single logical package as multiple
directories.

Expand Down
3 changes: 2 additions & 1 deletion Doc/library/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1239,7 +1239,8 @@ always available.
that implement Python's default import semantics. The
:meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at
least the absolute name of the module being imported. If the module to be
imported is contained in a package, then the parent package's :attr:`__path__`
imported is contained in a package, then the parent package's
:attr:`~module.__path__`
attribute is passed in as a second argument. The method returns a
:term:`module spec`, or ``None`` if the module cannot be found.

Expand Down
Loading

0 comments on commit cba3776

Please sign in to comment.