Skip to content

Commit 3024b16

Browse files
AlexWaygoodhugovkwarsawJelleZijlstra
authored
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>
1 parent 7a303fc commit 3024b16

23 files changed

+379
-344
lines changed

‎Doc/c-api/import.rst

+13-13
Original file line numberDiff line numberDiff line change
@@ -136,14 +136,14 @@ Importing Modules
136136
such modules have no way to know that the module object is an unknown (and
137137
probably damaged with respect to the module author's intents) state.
138138
139-
The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
140-
not set already, with the appropriate values. The spec's loader will
141-
be set to the module's ``__loader__`` (if set) and to an instance of
142-
:class:`~importlib.machinery.SourceFileLoader` otherwise.
139+
The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
140+
set, if not set already, with the appropriate values. The spec's loader
141+
will be set to the module's :attr:`!__loader__` (if set) and to an instance
142+
of :class:`~importlib.machinery.SourceFileLoader` otherwise.
143143
144-
The module's :attr:`__file__` attribute will be set to the code object's
145-
:attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
146-
be set.
144+
The module's :attr:`~module.__file__` attribute will be set to the code
145+
object's :attr:`~codeobject.co_filename`. If applicable,
146+
:attr:`~module.__cached__` will also be set.
147147
148148
This function will reload the module if it was already imported. See
149149
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
@@ -155,29 +155,29 @@ Importing Modules
155155
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
156156
157157
.. versionchanged:: 3.12
158-
The setting of :attr:`__cached__` and :attr:`__loader__` is
159-
deprecated. See :class:`~importlib.machinery.ModuleSpec` for
158+
The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
159+
is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
160160
alternatives.
161161
162162
163163
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
164164
165-
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
166-
the module object is set to *pathname* if it is non-``NULL``.
165+
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
166+
attribute of the module object is set to *pathname* if it is non-``NULL``.
167167
168168
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
169169
170170
171171
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
172172
173-
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
173+
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
174174
attribute of the module object is set to *cpathname* if it is
175175
non-``NULL``. Of the three functions, this is the preferred one to use.
176176
177177
.. versionadded:: 3.3
178178
179179
.. versionchanged:: 3.12
180-
Setting :attr:`__cached__` is deprecated. See
180+
Setting :attr:`~module.__cached__` is deprecated. See
181181
:class:`~importlib.machinery.ModuleSpec` for alternatives.
182182
183183

‎Doc/c-api/module.rst

+12-10
Original file line numberDiff line numberDiff line change
@@ -37,18 +37,19 @@ Module Objects
3737
single: __package__ (module attribute)
3838
single: __loader__ (module attribute)
3939
40-
Return a new module object with the :attr:`__name__` attribute set to *name*.
41-
The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
42-
:attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
43-
to ``None``); the caller is responsible for providing a :attr:`__file__`
44-
attribute.
40+
Return a new module object with :attr:`module.__name__` set to *name*.
41+
The module's :attr:`!__name__`, :attr:`~module.__doc__`,
42+
:attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
43+
filled in (all but :attr:`!__name__` are set to ``None``). The caller is
44+
responsible for setting a :attr:`~module.__file__` attribute.
4545
4646
Return ``NULL`` with an exception set on error.
4747
4848
.. versionadded:: 3.3
4949
5050
.. versionchanged:: 3.4
51-
:attr:`__package__` and :attr:`__loader__` are set to ``None``.
51+
:attr:`~module.__package__` and :attr:`~module.__loader__` are now set to
52+
``None``.
5253
5354
5455
.. c:function:: PyObject* PyModule_New(const char *name)
@@ -77,8 +78,9 @@ Module Objects
7778
single: __name__ (module attribute)
7879
single: SystemError (built-in exception)
7980
80-
Return *module*'s :attr:`__name__` value. If the module does not provide one,
81-
or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
81+
Return *module*'s :attr:`~module.__name__` value. If the module does not
82+
provide one, or if it is not a string, :exc:`SystemError` is raised and
83+
``NULL`` is returned.
8284
8385
.. versionadded:: 3.3
8486
@@ -108,8 +110,8 @@ Module Objects
108110
single: SystemError (built-in exception)
109111
110112
Return the name of the file from which *module* was loaded using *module*'s
111-
:attr:`__file__` attribute. If this is not defined, or if it is not a
112-
unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
113+
:attr:`~module.__file__` attribute. If this is not defined, or if it is not a
114+
string, raise :exc:`SystemError` and return ``NULL``; otherwise return
113115
a reference to a Unicode object.
114116
115117
.. versionadded:: 3.2

‎Doc/deprecations/pending-removal-in-3.14.rst

+7
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
Pending Removal in Python 3.14
22
------------------------------
33

4+
* The import system:
5+
6+
* Setting :attr:`~module.__loader__` on a module while
7+
failing to set :attr:`__spec__.loader <importlib.machinery.ModuleSpec.loader>`
8+
is deprecated. In Python 3.14, :attr:`!__loader__` will cease to be set or
9+
taken into consideration by the import system or the standard library.
10+
411
* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
512
of :class:`!argparse.BooleanOptionalAction` are deprecated
613
and will be removed in 3.14.

‎Doc/deprecations/pending-removal-in-3.15.rst

+12-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
Pending Removal in Python 3.15
22
------------------------------
33

4+
* The import system:
5+
6+
* Setting :attr:`~module.__cached__` on a module while
7+
failing to set :attr:`__spec__.cached <importlib.machinery.ModuleSpec.cached>`
8+
is deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or
9+
take into consideration by the import system or standard library. (:gh:`97879`)
10+
11+
* Setting :attr:`~module.__package__` on a module while
12+
failing to set :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`
13+
is deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or
14+
take into consideration by the import system or standard library. (:gh:`97879`)
15+
416
* :mod:`ctypes`:
517

618
* The undocumented :func:`!ctypes.SetPointerType` function
@@ -17,9 +29,6 @@ Pending Removal in Python 3.15
1729
* The :option:`!--cgi` flag to the :program:`python -m http.server`
1830
command-line interface has been deprecated since Python 3.13.
1931

20-
* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
21-
taken into consideration by the import system (:gh:`97879`).
22-
2332
* :class:`locale`:
2433

2534
* The :func:`~locale.getdefaultlocale` function

‎Doc/glossary.rst

+8-3
Original file line numberDiff line numberDiff line change
@@ -461,7 +461,7 @@ Glossary
461461
<meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
462462
entry finders <path entry finder>` for use with :data:`sys.path_hooks`.
463463

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

466466
floor division
467467
Mathematical division that rounds down to nearest integer. The floor
@@ -791,8 +791,11 @@ Glossary
791791
loader
792792
An object that loads a module. It must define a method named
793793
:meth:`load_module`. A loader is typically returned by a
794-
:term:`finder`. See :pep:`302` for details and
795-
:class:`importlib.abc.Loader` for an :term:`abstract base class`.
794+
:term:`finder`. See also:
795+
796+
* :ref:`finders-and-loaders`
797+
* :class:`importlib.abc.Loader`
798+
* :pep:`302`
796799

797800
locale encoding
798801
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
@@ -862,6 +865,8 @@ Glossary
862865
A namespace containing the import-related information used to load a
863866
module. An instance of :class:`importlib.machinery.ModuleSpec`.
864867

868+
See also :ref:`module-specs`.
869+
865870
MRO
866871
See :term:`method resolution order`.
867872

‎Doc/library/ast.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -902,7 +902,7 @@ Statements
902902
(indicating a "simple" target). A "simple" target consists solely of a
903903
:class:`Name` node that does not appear between parentheses; all other
904904
targets are considered complex. Only simple targets appear in
905-
the :attr:`__annotations__` dictionary of modules and classes.
905+
the :attr:`~object.__annotations__` dictionary of modules and classes.
906906

907907
.. doctest::
908908

‎Doc/library/importlib.rst

+34-53
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,7 @@ ABC hierarchy::
249249
An abstract method for finding a :term:`spec <module spec>` for
250250
the specified module. If this is a top-level import, *path* will
251251
be ``None``. Otherwise, this is a search for a subpackage or
252-
module and *path* will be the value of :attr:`__path__` from the
252+
module and *path* will be the value of :attr:`~module.__path__` from the
253253
parent package. If a spec cannot be found, ``None`` is returned.
254254
When passed in, ``target`` is a module object that the finder may
255255
use to make a more educated guess about what spec to return.
@@ -355,34 +355,12 @@ ABC hierarchy::
355355
(note that some of these attributes can change when a module is
356356
reloaded):
357357

358-
- :attr:`__name__`
359-
The module's fully qualified name.
360-
It is ``'__main__'`` for an executed module.
361-
362-
- :attr:`__file__`
363-
The location the :term:`loader` used to load the module.
364-
For example, for modules loaded from a .py file this is the filename.
365-
It is not set on all modules (e.g. built-in modules).
366-
367-
- :attr:`__cached__`
368-
The filename of a compiled version of the module's code.
369-
It is not set on all modules (e.g. built-in modules).
370-
371-
- :attr:`__path__`
372-
The list of locations where the package's submodules will be found.
373-
Most of the time this is a single directory.
374-
The import system passes this attribute to ``__import__()`` and to finders
375-
in the same way as :data:`sys.path` but just for the package.
376-
It is not set on non-package modules so it can be used
377-
as an indicator that the module is a package.
378-
379-
- :attr:`__package__`
380-
The fully qualified name of the package the module is in (or the
381-
empty string for a top-level module).
382-
If the module is a package then this is the same as :attr:`__name__`.
383-
384-
- :attr:`__loader__`
385-
The :term:`loader` used to load the module.
358+
- :attr:`module.__name__`
359+
- :attr:`module.__file__`
360+
- :attr:`module.__cached__` *(deprecated)*
361+
- :attr:`module.__path__`
362+
- :attr:`module.__package__` *(deprecated)*
363+
- :attr:`module.__loader__` *(deprecated)*
386364

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

423402
.. versionchanged:: 3.4
424403
Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
@@ -505,9 +484,9 @@ ABC hierarchy::
505484

506485
.. abstractmethod:: get_filename(fullname)
507486

508-
An abstract method that is to return the value of :attr:`__file__` for
509-
the specified module. If no path is available, :exc:`ImportError` is
510-
raised.
487+
An abstract method that is to return the value of
488+
:attr:`~module.__file__` for the specified module. If no path is
489+
available, :exc:`ImportError` is raised.
511490

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

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

11771157
.. versionadded:: 3.4
11781158

11791159
.. attribute:: name
11801160

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

11851164
.. attribute:: loader
11861165

1187-
The :term:`loader` used to load the module
1188-
(see :attr:`__loader__` attributes on modules).
1166+
The :term:`loader` used to load the module (see :attr:`module.__loader__`).
11891167
The :term:`finder` should always set this attribute.
11901168

11911169
.. attribute:: origin
11921170

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

12001178
.. attribute:: submodule_search_locations
12011179

1202-
The list of locations where the package's submodules will be found
1203-
(see :attr:`__path__` attributes on modules).
1204-
Most of the time this is a single directory.
1205-
The :term:`finder` should set this attribute to a list, even an empty one, to indicate
1180+
A (possibly empty) :term:`sequence` of strings enumerating the locations
1181+
in which a package's submodules will be found
1182+
(see :attr:`module.__path__`). Most of the time there will only be a
1183+
single directory in this list.
1184+
1185+
The :term:`finder` should set this attribute to a sequence, even an empty
1186+
one, to indicate
12061187
to the import system that the module is a package. It should be set to ``None`` for
12071188
non-package modules. It is set automatically later to a special object for
12081189
namespace packages.
@@ -1216,22 +1197,22 @@ find and load modules.
12161197
.. attribute:: cached
12171198

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

12231204
.. attribute:: parent
12241205

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

12301211
.. attribute:: has_location
12311212

12321213
``True`` if the spec's :attr:`origin` refers to a loadable location,
1233-
``False`` otherwise. This value impacts how :attr:`origin` is interpreted
1234-
and how the module's :attr:`__file__` is populated.
1214+
``False`` otherwise. This value impacts how :attr:`!origin` is interpreted
1215+
and how the module's :attr:`~module.__file__` is populated.
12351216

12361217

12371218
.. class:: AppleFrameworkLoader(name, path)
@@ -1416,8 +1397,8 @@ an :term:`importer`.
14161397

14171398
.. versionchanged:: 3.7
14181399
Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
1419-
**package** is in fact not a package (i.e. lacks a :attr:`__path__`
1420-
attribute).
1400+
**package** is in fact not a package (i.e. lacks a
1401+
:attr:`~module.__path__` attribute).
14211402

14221403
.. function:: module_from_spec(spec)
14231404

‎Doc/library/pkgutil.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ support.
2626
__path__ = extend_path(__path__, __name__)
2727

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

‎Doc/library/sys.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -1274,7 +1274,8 @@ always available.
12741274
that implement Python's default import semantics. The
12751275
:meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at
12761276
least the absolute name of the module being imported. If the module to be
1277-
imported is contained in a package, then the parent package's :attr:`__path__`
1277+
imported is contained in a package, then the parent package's
1278+
:attr:`~module.__path__`
12781279
attribute is passed in as a second argument. The method returns a
12791280
:term:`module spec`, or ``None`` if the module cannot be found.
12801281

0 commit comments

Comments
 (0)