Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

gh-101100: Consolidate documentation on `ModuleType` attributes (#124709) 

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Barry Warsaw <barry@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
This commit is contained in:
Alex Waygood 2024-10-09 11:53:57 +01:00 committed by GitHub
parent 7a303fc78a
commit 3024b16d51
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
23 changed files with 379 additions and 344 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
Doc/c-api/import.rst
View File

@ -136,14 +136,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.
@ -155,29 +155,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.

22
Doc/c-api/module.rst
View File

@ -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)
@ -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
@ -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

7
Doc/deprecations/pending-removal-in-3.14.rst
View File

@ -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.

15
Doc/deprecations/pending-removal-in-3.15.rst
View File

@ -1,6 +1,18 @@
Pending Removal in Python 3.15
------------------------------
* The import system:
* Setting :attr:`~module.__cached__` on a module while
failing to set :attr:`__spec__.cached <importlib.machinery.ModuleSpec.cached>`
is deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or
take into consideration by the import system or standard library. (:gh:`97879`)
* Setting :attr:`~module.__package__` on a module while
failing to set :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`
is deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or
take into consideration by the import system or standard library. (:gh:`97879`)
* :mod:`ctypes`:
* The undocumented :func:`!ctypes.SetPointerType` function
@ -17,9 +29,6 @@ Pending Removal in Python 3.15
* The :option:`!--cgi` flag to the :program:`python -m http.server`
command-line interface has been deprecated since Python 3.13.
* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
taken into consideration by the import system (:gh:`97879`).
* :class:`locale`:
* The :func:`~locale.getdefaultlocale` function

11
Doc/glossary.rst
View File

@ -461,7 +461,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
@ -791,8 +791,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
@ -862,6 +865,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`.

2
Doc/library/ast.rst
View File

@ -902,7 +902,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::

87
Doc/library/importlib.rst
View File

@ -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.
@ -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__` *(deprecated)*
- :attr:`module.__path__`
- :attr:`module.__package__` *(deprecated)*
- :attr:`module.__loader__` *(deprecated)*
When :meth:`exec_module` is available then backwards-compatible
functionality is provided.
@ -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`.
@ -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
@ -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.
@ -1216,7 +1197,7 @@ 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.
@ -1224,14 +1205,14 @@ find and load modules.
(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.
.. class:: AppleFrameworkLoader(name, path)
@ -1416,8 +1397,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)

3
Doc/library/pkgutil.rst
View File

@ -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.

3
Doc/library/sys.rst
View File

@ -1274,7 +1274,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.

65
Doc/library/types.rst
View File

@ -260,63 +260,18 @@ Standard names are defined for the following types:
The type of :term:`modules <module>`. The constructor takes the name of the
module to be created and optionally its :term:`docstring`.
.. note::
Use :func:`importlib.util.module_from_spec` to create a new module if you
wish to set the various import-controlled attributes.
.. seealso::
.. attribute:: __doc__
The :term:`docstring` of the module. Defaults to ``None``.
.. attribute:: __loader__
The :term:`loader` which loaded the module. Defaults to ``None``.
This attribute is to match :attr:`importlib.machinery.ModuleSpec.loader`
as stored in the :attr:`__spec__` object.
.. note::
A future version of Python may stop setting this attribute by default.
To guard against this potential change, preferably read from the
:attr:`__spec__` attribute instead or use
``getattr(module, "__loader__", None)`` if you explicitly need to use
this attribute.
.. versionchanged:: 3.4
Defaults to ``None``. Previously the attribute was optional.
.. attribute:: __name__
The name of the module. Expected to match
:attr:`importlib.machinery.ModuleSpec.name`.
.. attribute:: __package__
Which :term:`package` a module belongs to. If the module is top-level
(i.e. not a part of any specific package) then the attribute should be set
to ``''``, else it should be set to the name of the package (which can be
:attr:`__name__` if the module is a package itself). Defaults to ``None``.
This attribute is to match :attr:`importlib.machinery.ModuleSpec.parent`
as stored in the :attr:`__spec__` object.
.. note::
A future version of Python may stop setting this attribute by default.
To guard against this potential change, preferably read from the
:attr:`__spec__` attribute instead or use
``getattr(module, "__package__", None)`` if you explicitly need to use
this attribute.
.. versionchanged:: 3.4
Defaults to ``None``. Previously the attribute was optional.
.. attribute:: __spec__
A record of the module's import-system-related state. Expected to be an
instance of :class:`importlib.machinery.ModuleSpec`.
.. versionadded:: 3.4
:ref:`Documentation on module objects <module-objects>`
Provides details on the special attributes that can be found on
instances of :class:`!ModuleType`.
:func:`importlib.util.module_from_spec`
Modules created using the :class:`!ModuleType` constructor are
created with many of their special attributes unset or set to default
values. :func:`!module_from_spec` provides a more robust way of
creating :class:`!ModuleType` instances which ensures the various
attributes are set appropriately.
.. data:: EllipsisType

240
Doc/reference/datamodel.rst
View File

@ -865,6 +865,8 @@ Instances of arbitrary classes can be made callable by defining a
:meth:`~object.__call__` method in their class.
.. _module-objects:
Modules
-------
@ -890,52 +892,238 @@ Attribute assignment updates the module's namespace dictionary, e.g.,
.. index::
single: __name__ (module attribute)
single: __doc__ (module attribute)
single: __spec__ (module attribute)
single: __package__ (module attribute)
single: __loader__ (module attribute)
single: __path__ (module attribute)
single: __file__ (module attribute)
single: __cached__ (module attribute)
single: __doc__ (module attribute)
single: __annotations__ (module attribute)
single: __annotate__ (module attribute)
pair: module; namespace
Predefined (writable) attributes:
.. _import-mod-attrs:
:attr:`__name__`
The module's name.
Import-related attributes on module objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:attr:`__doc__`
The module's documentation string, or ``None`` if
unavailable.
Module objects have the following attributes that relate to the
:ref:`import system <importsystem>`. When a module is created using the machinery associated
with the import system, these attributes are filled in based on the module's
:term:`spec <module spec>`, before the :term:`loader` executes and loads the
module.
:attr:`__file__`
The pathname of the file from which the
module was loaded, if it was loaded from a file.
The :attr:`__file__`
attribute may be missing for certain types of modules, such as C modules
that are statically linked into the interpreter. For extension modules
loaded dynamically from a shared library, it's the pathname of the shared
library file.
To create a module dynamically rather than using the import system,
it's recommended to use :func:`importlib.util.module_from_spec`,
which will set the various import-controlled attributes to appropriate values.
It's also possible to use the :class:`types.ModuleType` constructor to create
modules directly, but this technique is more error-prone, as most attributes
must be manually set on the module object after it has been created when using
this approach.
:attr:`~object.__annotations__`
A dictionary containing
:term:`variable annotations <variable annotation>` collected during
module body execution. For best practices on working
with :attr:`!__annotations__`, see :mod:`annotationlib`.
.. caution::
With the exception of :attr:`~module.__name__`, it is **strongly**
recommended that you rely on :attr:`~module.__spec__` and its attributes
instead of any of the other individual attributes listed in this subsection.
Note that updating an attribute on :attr:`!__spec__` will not update the
corresponding attribute on the module itself:
.. doctest::
>>> import typing
>>> typing.__name__, typing.__spec__.name
('typing', 'typing')
>>> typing.__spec__.name = 'spelling'
>>> typing.__name__, typing.__spec__.name
('typing', 'spelling')
>>> typing.__name__ = 'keyboard_smashing'
>>> typing.__name__, typing.__spec__.name
('keyboard_smashing', 'spelling')
.. attribute:: module.__name__
The name used to uniquely identify the module in the import system.
For a directly executed module, this will be set to ``"__main__"``.
This attribute must be set to the fully qualified name of the module.
It is expected to match the value of
:attr:`module.__spec__.name <importlib.machinery.ModuleSpec.name>`.
.. attribute:: module.__spec__
A record of the module's import-system-related state.
Set to the :class:`module spec <importlib.machinery.ModuleSpec>` that was
used when importing the module. See :ref:`module-specs` for more details.
.. versionadded:: 3.4
.. attribute:: module.__package__
The :term:`package` a module belongs to.
If the module is top-level (that is, not a part of any specific package)
then the attribute should be set to ``''`` (the empty string). Otherwise,
it should be set to the name of the module's package (which can be equal to
:attr:`module.__name__` if the module itself is a package). See :pep:`366`
for further details.
This attribute is used instead of :attr:`~module.__name__` to calculate
explicit relative imports for main modules. It defaults to ``None`` for
modules created dynamically using the :class:`types.ModuleType` constructor;
use :func:`importlib.util.module_from_spec` instead to ensure the attribute
is set to a :class:`str`.
It is **strongly** recommended that you use
:attr:`module.__spec__.parent <importlib.machinery.ModuleSpec.parent>`
instead of :attr:`!module.__package__`. :attr:`__package__` is now only used
as a fallback if :attr:`!__spec__.parent` is not set, and this fallback
path is deprecated.
.. versionchanged:: 3.4
This attribute now defaults to ``None`` for modules created dynamically
using the :class:`types.ModuleType` constructor.
Previously the attribute was optional.
.. versionchanged:: 3.6
The value of :attr:`!__package__` is expected to be the same as
:attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
:attr:`__package__` is now only used as a fallback during import
resolution if :attr:`!__spec__.parent` is not defined.
.. versionchanged:: 3.10
:exc:`ImportWarning` is raised if an import resolution falls back to
:attr:`!__package__` instead of
:attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.
.. versionchanged:: 3.12
Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning` when
falling back to :attr:`!__package__` during import resolution.
.. deprecated-removed:: 3.13 3.15
:attr:`!__package__` will cease to be set or taken into consideration
by the import system or standard library.
.. attribute:: module.__loader__
The :term:`loader` object that the import machinery used to load the module.
This attribute is mostly useful for introspection, but can be used for
additional loader-specific functionality, for example getting data
associated with a loader.
:attr:`!__loader__` defaults to ``None`` for modules created dynamically
using the :class:`types.ModuleType` constructor;
use :func:`importlib.util.module_from_spec` instead to ensure the attribute
is set to a :term:`loader` object.
It is **strongly** recommended that you use
:attr:`module.__spec__.loader <importlib.machinery.ModuleSpec.loader>`
instead of :attr:`!module.__loader__`.
.. versionchanged:: 3.4
This attribute now defaults to ``None`` for modules created dynamically
using the :class:`types.ModuleType` constructor.
Previously the attribute was optional.
.. deprecated-removed:: 3.12 3.14
Setting :attr:`!__loader__` on a module while failing to set
:attr:`!__spec__.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.
.. attribute:: module.__path__
A (possibly empty) :term:`sequence` of strings enumerating the locations
where the package's submodules will be found. Non-package modules should
not have a :attr:`!__path__` attribute. See :ref:`package-path-rules` for
more details.
It is **strongly** recommended that you use
:attr:`module.__spec__.submodule_search_locations <importlib.machinery.ModuleSpec.submodule_search_locations>`
instead of :attr:`!module.__path__`.
.. attribute:: module.__file__
.. attribute:: module.__cached__
:attr:`!__file__` and :attr:`!__cached__` are both optional attributes that
may or may not be set. Both attributes should be a :class:`str` when they
are available.
:attr:`!__file__` indicates the pathname of the file from which the module
was loaded (if loaded from a file), or the pathname of the shared library
file for extension modules loaded dynamically from a shared library.
It might be missing for certain types of modules, such as C modules that are
statically linked into the interpreter, and the
:ref:`import system <importsystem>` may opt to leave it unset if it
has no semantic meaning (for example, a module loaded from a database).
If :attr:`!__file__` is set then the :attr:`!__cached__` attribute might
also be set, which is the path to any compiled version of
the code (for example, a byte-compiled file). The file does not need to exist
to set this attribute; the path can simply point to where the
compiled file *would* exist (see :pep:`3147`).
Note that :attr:`!__cached__` may be set even if :attr:`!__file__` is not
set. However, that scenario is quite atypical. Ultimately, the
:term:`loader` is what makes use of the module spec provided by the
:term:`finder` (from which :attr:`!__file__` and :attr:`!__cached__` are
derived). So if a loader can load from a cached module but otherwise does
not load from a file, that atypical scenario may be appropriate.
It is **strongly** recommended that you use
:attr:`module.__spec__.cached <importlib.machinery.ModuleSpec.cached>`
instead of :attr:`!module.__cached__`.
.. deprecated-removed:: 3.13 3.15
Setting :attr:`!__cached__` on a module while failing to set
:attr:`!__spec__.cached` is deprecated. In Python 3.15,
:attr:`!__cached__` will cease to be set or taken into consideration by
the import system or standard library.
Other writable attributes on module objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As well as the import-related attributes listed above, module objects also have
the following writable attributes:
.. attribute:: module.__doc__
The module's documentation string, or ``None`` if unavailable.
See also: :attr:`__doc__ attributes <definition.__doc__>`.
.. attribute:: module.__annotations__
A dictionary containing :term:`variable annotations <variable annotation>`
collected during module body execution. For best practices on working with
:attr:`!__annotations__`, see :mod:`annotationlib`.
.. versionchanged:: 3.14
Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
See :pep:`649`.
:attr:`~object.__annotate__`
The :term:`annotate function` for this module, or ``None``
if the module has no annotations. See :attr:`object.__annotate__`.
.. attribute:: module.__annotate__
The :term:`annotate function` for this module, or ``None`` if the module has
no annotations. See also: :attr:`~object.__annotate__` attributes.
.. versionadded:: 3.14
Module dictionaries
^^^^^^^^^^^^^^^^^^^
Module objects also have the following special read-only attribute:
.. index:: single: __dict__ (module attribute)
.. attribute:: module.__dict__
Special read-only attribute: :attr:`~object.__dict__` is the module's
namespace as a dictionary object.
The module's namespace as a dictionary object. Uniquely among the attributes
listed here, :attr:`!__dict__` cannot be accessed as a global variable from
within a module; it can only be accessed as an attribute on module objects.
.. impl-detail::
.. impl-detail::
Because of the way CPython clears module dictionaries, the module
dictionary will be cleared when the module falls out of scope even if the

169
Doc/reference/import.rst
View File

@ -513,8 +513,10 @@ holding is that if you have ``sys.modules['spam']`` and
``sys.modules['spam.foo']`` (as you would after the above import), the latter
must appear as the ``foo`` attribute of the former.
Module spec
-----------
.. _module-specs:
Module specs
------------
The import machinery uses a variety of information about each module
during import, especially before loading. Most of the information is
@ -527,163 +529,44 @@ and the loader that executes it. Most importantly, it allows the
import machinery to perform the boilerplate operations of loading,
whereas without a module spec the loader had that responsibility.
The module's spec is exposed as the ``__spec__`` attribute on a module object.
The module's spec is exposed as :attr:`module.__spec__`. Setting
:attr:`!__spec__` appropriately applies equally to
:ref:`modules initialized during interpreter startup <programs>`.
The one exception is ``__main__``, where :attr:`!__spec__` is
:ref:`set to None in some cases <main_spec>`.
See :class:`~importlib.machinery.ModuleSpec` for details on the contents of
the module spec.
.. versionadded:: 3.4
.. _import-mod-attrs:
Import-related module attributes
--------------------------------
The import machinery fills in these attributes on each module object
during loading, based on the module's spec, before the loader executes
the module.
It is **strongly** recommended that you rely on :attr:`__spec__` and
its attributes instead of any of the other individual attributes
listed below, except :attr:`__name__`.
.. attribute:: __name__
The ``__name__`` attribute must be set to the fully qualified name of
the module. This name is used to uniquely identify the module in
the import system.
.. attribute:: __loader__
The ``__loader__`` attribute must be set to the loader object that
the import machinery used when loading the module. This is mostly
for introspection, but can be used for additional loader-specific
functionality, for example getting data associated with a loader.
It is **strongly** recommended that you rely on :attr:`__spec__`
instead of this attribute.
.. versionchanged:: 3.12
The value of ``__loader__`` is expected to be the same as
``__spec__.loader``. The use of ``__loader__`` is deprecated and slated
for removal in Python 3.14.
.. attribute:: __package__
The module's ``__package__`` attribute may be set. Its value must
be a string, but it can be the same value as its ``__name__``. When
the module is a package, its ``__package__`` value should be set to
its ``__name__``. When the module is not a package, ``__package__``
should be set to the empty string for top-level modules, or for
submodules, to the parent package's name. See :pep:`366` for further
details.
This attribute is used instead of ``__name__`` to calculate explicit
relative imports for main modules, as defined in :pep:`366`.
It is **strongly** recommended that you rely on :attr:`__spec__`
instead of this attribute.
.. versionchanged:: 3.6
The value of ``__package__`` is expected to be the same as
``__spec__.parent``.
.. versionchanged:: 3.10
:exc:`ImportWarning` is raised if import falls back to
``__package__`` instead of
:attr:`~importlib.machinery.ModuleSpec.parent`.
.. versionchanged:: 3.12
Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning`
when falling back to ``__package__``.
.. deprecated-removed:: 3.13 3.15
``__package__`` will cease to be set or taken into consideration
by the import system or standard library.
.. attribute:: __spec__
The ``__spec__`` attribute must be set to the module spec that was
used when importing the module. Setting ``__spec__``
appropriately applies equally to :ref:`modules initialized during
interpreter startup <programs>`. The one exception is ``__main__``,
where ``__spec__`` is :ref:`set to None in some cases <main_spec>`.
When ``__spec__.parent`` is not set, ``__package__`` is used as
a fallback.
.. versionadded:: 3.4
.. versionchanged:: 3.6
``__spec__.parent`` is used as a fallback when ``__package__`` is
not defined.
.. attribute:: __path__
If the module is a package (either regular or namespace), the module
object's ``__path__`` attribute must be set. The value must be
iterable, but may be empty if ``__path__`` has no further significance.
If ``__path__`` is not empty, it must produce strings when iterated
over. More details on the semantics of ``__path__`` are given
:ref:`below <package-path-rules>`.
Non-package modules should not have a ``__path__`` attribute.
.. attribute:: __file__
.. attribute:: __cached__
``__file__`` is optional (if set, value must be a string). It indicates
the pathname of the file from which the module was loaded (if
loaded from a file), or the pathname of the shared library file
for extension modules loaded dynamically from a shared library.
It might be missing for certain types of modules, such as C
modules that are statically linked into the interpreter, and the
import system may opt to leave it unset if it has no semantic
meaning (e.g. a module loaded from a database).
If ``__file__`` is set then the ``__cached__`` attribute might also
be set, which is the path to any compiled version of
the code (e.g. byte-compiled file). The file does not need to exist
to set this attribute; the path can simply point to where the
compiled file would exist (see :pep:`3147`).
Note that ``__cached__`` may be set even if ``__file__`` is not
set. However, that scenario is quite atypical. Ultimately, the
loader is what makes use of the module spec provided by the finder
(from which ``__file__`` and ``__cached__`` are derived). So
if a loader can load from a cached module but otherwise does not load
from a file, that atypical scenario may be appropriate.
It is **strongly** recommended that you rely on :attr:`__spec__`
instead of ``__cached__``.
.. deprecated-removed:: 3.13 3.15
``__cached__`` will cease to be set or taken into consideration
by the import system or standard library.
.. _package-path-rules:
module.__path__
---------------
__path__ attributes on modules
------------------------------
By definition, if a module has a ``__path__`` attribute, it is a package.
The :attr:`~module.__path__` attribute should be a (possibly empty)
:term:`sequence` of strings enumerating the locations where the package's
submodules will be found. By definition, if a module has a :attr:`!__path__`
attribute, it is a :term:`package`.
A package's ``__path__`` attribute is used during imports of its subpackages.
A package's :attr:`~module.__path__` attribute is used during imports of its
subpackages.
Within the import machinery, it functions much the same as :data:`sys.path`,
i.e. providing a list of locations to search for modules during import.
However, ``__path__`` is typically much more constrained than
:data:`sys.path`.
However, :attr:`!__path__` is typically much more constrained than
:data:`!sys.path`.
``__path__`` must be an iterable of strings, but it may be empty.
The same rules used for :data:`sys.path` also apply to a package's
``__path__``, and :data:`sys.path_hooks` (described below) are
consulted when traversing a package's ``__path__``.
:attr:`!__path__`. :data:`sys.path_hooks` (described below) are
consulted when traversing a package's :attr:`!__path__`.
A package's ``__init__.py`` file may set or alter the package's ``__path__``
A package's ``__init__.py`` file may set or alter the package's
:attr:`~module.__path__`
attribute, and this was typically the way namespace packages were implemented
prior to :pep:`420`. With the adoption of :pep:`420`, namespace packages no
longer need to supply ``__init__.py`` files containing only ``__path__``
manipulation code; the import machinery automatically sets ``__path__``
longer need to supply ``__init__.py`` files containing only :attr:`!__path__`
manipulation code; the import machinery automatically sets :attr:`!__path__`
correctly for the namespace package.
Module reprs

5
Doc/tutorial/modules.rst
View File

@ -585,8 +585,9 @@ as the main module of a Python application must always use absolute imports.
Packages in Multiple Directories
--------------------------------
Packages support one more special attribute, :attr:`__path__`. This is
initialized to be a list containing the name of the directory holding the
Packages support one more special attribute, :attr:`~module.__path__`. This is
initialized to be a :term:`sequence` of strings containing the name of the
directory holding the
package's :file:`__init__.py` before the code in that file is executed. This
variable can be modified; doing so affects future searches for modules and
subpackages contained in the package.

8
Doc/whatsnew/2.6.rst
View File

@ -502,12 +502,12 @@ Python's :option:`-m` switch allows running a module as a script.
When you ran a module that was located inside a package, relative
imports didn't work correctly.
The fix for Python 2.6 adds a :attr:`__package__` attribute to
modules. When this attribute is present, relative imports will be
The fix for Python 2.6 adds a :attr:`module.__package__` attribute.
When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
:attr:`__name__` attribute.
:attr:`~module.__name__` attribute.
PEP 302-style importers can then set :attr:`__package__` as necessary.
PEP 302-style importers can then set :attr:`~module.__package__` as necessary.
The :mod:`runpy` module that implements the :option:`-m` switch now
does this, so relative imports will now work correctly in scripts
running from inside a package.

4
Doc/whatsnew/3.0.rst
View File

@ -357,8 +357,8 @@ New Syntax
provides a standardized way of annotating a function's parameters
and return value. There are no semantics attached to such
annotations except that they can be introspected at runtime using
the :attr:`__annotations__` attribute. The intent is to encourage
experimentation through metaclasses, decorators or frameworks.
the :attr:`~object.__annotations__` attribute. The intent is to
encourage experimentation through metaclasses, decorators or frameworks.
* :pep:`3102`: Keyword-only arguments. Named parameters occurring
after ``*args`` in the parameter list *must* be specified using

13
Doc/whatsnew/3.12.rst
View File

@ -1309,14 +1309,15 @@ Deprecated
may be removed in a future version of Python. Use the single-arg versions
of these functions instead. (Contributed by Ofey Chan in :gh:`89874`.)
* :exc:`DeprecationWarning` is now raised when ``__package__`` on a
module differs from ``__spec__.parent`` (previously it was
:exc:`ImportWarning`).
* :exc:`DeprecationWarning` is now raised when :attr:`~module.__package__` on a
module differs from
:attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>` (previously
it was :exc:`ImportWarning`).
(Contributed by Brett Cannon in :gh:`65961`.)
* Setting ``__package__`` or ``__cached__`` on a module is deprecated,
and will cease to be set or taken into consideration by the import system in Python 3.14.
(Contributed by Brett Cannon in :gh:`65961`.)
* Setting :attr:`~module.__package__` or :attr:`~module.__cached__` on a
module is deprecated, and will cease to be set or taken into consideration by
the import system in Python 3.14. (Contributed by Brett Cannon in :gh:`65961`.)
* The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
error in Python 3.16. Use ``not`` for logical negation of bools instead.

4
Doc/whatsnew/3.2.rst
View File

@ -312,8 +312,8 @@ cluttering source directories, the *pyc* files are now collected in a
Aside from the filenames and target directories, the new scheme has a few
aspects that are visible to the programmer:
* Imported modules now have a :attr:`__cached__` attribute which stores the name
of the actual file that was imported:
* Imported modules now have a :attr:`~module.__cached__` attribute which stores
the name of the actual file that was imported:
>>> import collections
>>> collections.__cached__ # doctest: +SKIP

3
Doc/whatsnew/3.4.rst
View File

@ -2271,7 +2271,8 @@ Changes in the Python API
:func:`super` and falling through all the way to the ABCs. For compatibility,
catch both :exc:`NotImplementedError` or the appropriate exception as needed.
* The module type now initializes the :attr:`__package__` and :attr:`__loader__`
* The module type now initializes the :attr:`~module.__package__` and
:attr:`~module.__loader__`
attributes to ``None`` by default. To determine if these attributes were set
in a backwards-compatible fashion, use e.g.
``getattr(module, '__loader__', None) is not None``. (:issue:`17115`.)

4
Doc/whatsnew/3.5.rst
View File

@ -423,8 +423,8 @@ are declared in the annotations::
return 'Hello ' + name
While these annotations are available at runtime through the usual
:attr:`__annotations__` attribute, *no automatic type checking happens at
runtime*. Instead, it is assumed that a separate off-line type checker
:attr:`~object.__annotations__` attribute, *no automatic type checking happens
at runtime*. Instead, it is assumed that a separate off-line type checker
(e.g. `mypy <https://mypy-lang.org>`_) will be used for on-demand
source code analysis.

4
Misc/NEWS.d/3.10.0a2.rst
View File

@ -226,8 +226,8 @@ thread at the time the function is called.
.. section: Core and Builtins
Enable ``from __future__ import annotations`` (:pep:`563`) by default. The
values found in :attr:`__annotations__` dicts are now strings, e.g. ``{"x":
"int"}`` instead of ``{"x": int}``.
values found in :attr:`~object.__annotations__` dicts are now strings, for
example ``{"x": "int"}`` instead of ``{"x": int}``.
..

4
Misc/NEWS.d/3.11.0a5.rst
View File

@ -486,8 +486,8 @@ Use ``dis.Positions`` in ``dis.Instruction`` instead of a regular ``tuple``.
.. nonce: geS-aP
.. section: Library
:mod:`pdb` now gracefully handles ``help`` when :attr:`__doc__` is missing,
for example when run with pregenerated optimized ``.pyc`` files.
:mod:`pdb` now gracefully handles ``help`` when :attr:`~module.__doc__` is
missing, for example when run with pregenerated optimized ``.pyc`` files.
..

4
Misc/NEWS.d/3.12.0a1.rst
View File

@ -4237,8 +4237,8 @@ by :mod:`asyncio` to AIX platform only.
.. nonce: 4dzB80
.. section: Library
Set :attr:`doctest.DocTest.lineno` to ``None`` when object does not have
:attr:`__doc__`.
Set :attr:`doctest.DocTest.lineno` to ``None`` when an object does not have
:attr:`~definition.__doc__`.
..

4
Misc/NEWS.d/next/Core and Builtins/2024-05-31-08-23-41.gh-issue-119180.KL4VxZ.rst
View File

@ -1,3 +1,3 @@
:func:`classmethod` and :func:`staticmethod` now wrap the
:attr:`__annotations__` and :attr:`!__annotate__` attributes of their
underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.
:attr:`~object.__annotations__` and :attr:`~object.__annotate__` attributes of
their underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.