diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index 14b5b79829d5f6..685aa30a37bc2e 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -187,8 +187,9 @@ Type Objects .. c:function:: PyObject* PyType_GetFullyQualifiedName(PyTypeObject *type) - Return the type's fully qualified name. Equivalent to getting the - type's :attr:`__fully_qualified_name__ ` attribute. + Return the type's :term:`fully qualified name`. Equivalent to getting the + type's :attr:`__fully_qualified_name__ ` + attribute. .. versionadded:: 3.13 diff --git a/Doc/glossary.rst b/Doc/glossary.rst index dad745348f9b4b..99fce8578d175a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -435,6 +435,25 @@ Glossary division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75`` rounded *downward*. See :pep:`238`. + fully qualified name + The fully qualified name is the entire dotted path to a class or a + module. + + The :attr:`class.__fully_qualified_name__` attribute includes the module + name, except for built-in classes. Example:: + + >>> import collections + >>> collections.OrderedDict.__fully_qualified_name__ + 'collections.OrderedDict' + + When used to refer to modules, the *fully qualified name* means the + entire dotted path to the module, including any parent packages, + e.g. ``email.mime.text``:: + + >>> import email.mime.text + >>> email.mime.text.__name__ + 'email.mime.text' + function A series of statements which returns some value to a caller. It can also be passed zero or more :term:`arguments ` which may be used in diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index ad013944ce3ca3..1c2a87023e4651 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -587,13 +587,13 @@ doctest decides whether actual output matches an example's expected output: .. data:: IGNORE_EXCEPTION_DETAIL When specified, doctests expecting exceptions pass so long as an exception - of the expected type is raised, even if the details - (message and fully qualified exception name) don't match. + of the expected type is raised, even if the details (message and + :term:`fully qualified exception name `) don't match. For example, an example expecting ``ValueError: 42`` will pass if the actual exception raised is ``ValueError: 3*14``, but will fail if, say, a :exc:`TypeError` is raised instead. - It will also ignore any fully qualified name included before the + It will also ignore any :term:`fully qualified name` included before the exception class, which can vary between implementations and versions of Python and the code/libraries in use. Hence, all three of these variations will work with the flag specified: diff --git a/Doc/library/email.contentmanager.rst b/Doc/library/email.contentmanager.rst index 5b49339650f0e9..866087ad0aef0c 100644 --- a/Doc/library/email.contentmanager.rst +++ b/Doc/library/email.contentmanager.rst @@ -56,8 +56,8 @@ found: * the type itself (``typ``) - * the type's fully qualified name (``typ.__module__ + '.' + - typ.__qualname__``). + * the type's :term:`fully qualified name` + (:attr:`typ.__fully_qualified_name__ `). * the type's qualname (``typ.__qualname__``) * the type's name (``typ.__name__``). diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index fc954724bb72fe..07ad90d9f94c50 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -356,7 +356,7 @@ ABC hierarchy:: reloaded): - :attr:`__name__` - The module's fully qualified name. + The module's :term:`fully qualified name`. It is ``'__main__'`` for an executed module. - :attr:`__file__` @@ -377,8 +377,8 @@ ABC hierarchy:: 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). + The :term:`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__` @@ -1181,7 +1181,7 @@ find and load modules. (:attr:`__name__`) - The module's fully qualified name. + The module's :term:`fully qualified name`. The :term:`finder` should always set this attribute to a non-empty string. .. attribute:: loader @@ -1230,8 +1230,8 @@ find and load modules. (:attr:`__package__`) - (Read-only) The fully qualified name of the package the module is in (or the - empty string for a top-level module). + (Read-only) The :term:`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`. .. attribute:: has_location diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b463c0b6d0e402..6cce68e8ec51b9 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -182,7 +182,7 @@ attributes (see :ref:`import-mod-attrs` for module attributes): | | co_name | name with which this code | | | | object was defined | +-----------+-------------------+---------------------------+ -| | co_qualname | fully qualified name with | +| | co_qualname | qualified name with | | | | which this code object | | | | was defined | +-----------+-------------------+---------------------------+ diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index 85a53e6aa7a78b..a7012e3397060f 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -286,7 +286,7 @@ otherwise, the context is used to determine what to instantiate. The configuring dict is searched for the following keys: - * ``class`` (mandatory). This is the fully qualified name of the + * ``class`` (mandatory). This is the :term:`fully qualified name` of the handler class. * ``level`` (optional). The level of the handler. diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 93387fb0b45038..c4e9270351c51e 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -525,7 +525,7 @@ the function's code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. [#]_ -Similarly, classes are pickled by fully qualified name, so the same restrictions in +Similarly, classes are pickled by :term:`fully qualified name`, so the same restrictions in the unpickling environment apply. Note that none of the class's code or data is pickled, so in the following example the class attribute ``attr`` is not restored in the unpickling environment:: diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index af673ca1ef3901..d0a56f6f21de77 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5498,7 +5498,7 @@ types, where they are relevant. Some of these are not reported by the .. attribute:: class.__fully_qualified_name__ - The fully qualified name of the class instance: + The :term:`fully qualified name` of the class instance: ``f"{class.__module__}.{class.__qualname__}"``, or ``class.__qualname__`` if ``class.__module__`` is not a string or is equal to ``"builtins"``. diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index c90c554591e748..4d87e0b4e9e6c0 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -234,8 +234,8 @@ Command-line options test name using :meth:`fnmatch.fnmatchcase`; otherwise simple case-sensitive substring matching is used. - Patterns are matched against the fully qualified test method name as - imported by the test loader. + Patterns are matched against the :term:`fully qualified test method name + `_ as imported by the test loader. For example, ``-k foo`` matches ``foo_tests.SomeTest.test_something``, ``bar_tests.SomeTest.test_foo``, but not ``bar_tests.FooTest.test_something``. diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index 884de08eab1b16..cc1d55293e3df1 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -163,7 +163,8 @@ the disposition of the match. Each entry is a tuple of the form (*action*, category must be a subclass in order to match. * *module* is a string containing a regular expression that the start of the - fully qualified module name must match, case-sensitively. In :option:`-W` and + :term:`fully qualified module name ` must match, + case-sensitively. In :option:`-W` and :envvar:`PYTHONWARNINGS`, *module* is a literal string that the fully qualified module name must be equal to (case-sensitively), ignoring any whitespace at the start or end of *module*. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index f7d3d2d0bbec23..0f174196524a88 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1076,7 +1076,7 @@ indirectly) to mutable objects. single: co_qualname (code object attribute) Special read-only attributes: :attr:`co_name` gives the function name; -:attr:`co_qualname` gives the fully qualified function name; +:attr:`co_qualname` gives the qualified function name; :attr:`co_argcount` is the total number of positional arguments (including positional-only arguments and arguments with default values); :attr:`co_posonlyargcount` is the number of positional-only arguments diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index a7beeea29b4556..cd4e11532e381b 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -157,8 +157,8 @@ See also :pep:`420` for the namespace package specification. Searching ========= -To begin the search, Python needs the :term:`fully qualified ` -name of the module (or package, but for the purposes of this discussion, the +To begin the search, Python needs the :term:`fully qualified name` +of the module (or package, but for the purposes of this discussion, the difference is immaterial) being imported. This name may come from various arguments to the :keyword:`import` statement, or from the parameters to the :func:`importlib.import_module` or :func:`__import__` functions. @@ -547,7 +547,7 @@ listed below. .. attribute:: __name__ - The ``__name__`` attribute must be set to the fully qualified name of + The ``__name__`` attribute must be set to the :term:`fully qualified name` of the module. This name is used to uniquely identify the module in the import system. @@ -885,7 +885,7 @@ contribute portions to namespace packages, path entry finders must implement the :meth:`~importlib.abc.PathEntryFinder.find_spec` method. :meth:`~importlib.abc.PathEntryFinder.find_spec` takes two arguments: the -fully qualified name of the module being imported, and the (optional) target +:term:`fully qualified name` of the module being imported, and the (optional) target module. ``find_spec()`` returns a fully populated spec for the module. This spec will always have "loader" set (with one exception). @@ -905,7 +905,7 @@ a list containing the portion. implemented on the path entry finder, the legacy methods are ignored. :meth:`!find_loader` takes one argument, the - fully qualified name of the module being imported. ``find_loader()`` + :term:`fully qualified name` of the module being imported. ``find_loader()`` returns a 2-tuple where the first item is the loader and the second item is a namespace :term:`portion`. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 39c8d114f1e2c5..ad6cad04012a77 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -464,8 +464,8 @@ Miscellaneous options whether the actual warning category of the message is a subclass of the specified warning category. - The *module* field matches the (fully qualified) module name; this match is - case-sensitive. + The *module* field matches the :term:`fully qualified module name `; this match is case-sensitive. The *lineno* field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number. diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index 3481e594c0955f..9380b87878ad38 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -125,8 +125,8 @@ Other Language Changes equivalent of the :option:`-X frozen_modules <-X>` command-line option. (Contributed by Yilei Yang in :gh:`111374`.) -* Add :attr:`__fully_qualified_name__ ` read-only attribute - to types: the fully qualified type name. +* Add the :attr:`__fully_qualified_name__ ` + read-only attribute to types: the :term:`fully qualified name` of the type. (Contributed by Victor Stinner in :gh:`111696`.) @@ -1186,8 +1186,8 @@ New Features :exc:`KeyError` if the key missing. (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.) -* Add :c:func:`PyType_GetFullyQualifiedName` function: get the type's fully - qualified name. It is equivalent to getting the type's +* Add :c:func:`PyType_GetFullyQualifiedName` function: get the type's + :term:`fully qualified name`. It is equivalent to getting the type's :attr:`__fully_qualified_name__ ` attribute. (Contributed by Victor Stinner in :gh:`111696`.)