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

256
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,57 +892,243 @@ 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::
.. versionchanged:: 3.14
Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
See :pep:`649`.
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:
:attr:`~object.__annotate__`
The :term:`annotate function` for this module, or ``None``
if the module has no annotations. See :attr:`object.__annotate__`.
.. doctest::
.. versionadded:: 3.14
>>> 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`.
.. 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
dictionary still has live references. To avoid this, copy the dictionary
or keep the module around while using its dictionary directly.
Because of the way CPython clears module dictionaries, the module
dictionary will be cleared when the module falls out of scope even if the
dictionary still has live references. To avoid this, copy the dictionary
or keep the module around while using its dictionary directly.
.. _class-attrs-and-methods:

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.