Sphinx 8.1.2__py3-none-any.whl → 8.2.0__py3-none-any.whl

sphinx/ext/autodoc/directive.py

@@ -1,35 +1,55 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.statemachine import StringList
-from docutils.utils import Reporter, assemble_option_dict
+from docutils.utils import assemble_option_dict
 
-from sphinx.ext.autodoc import Documenter, Options
+from sphinx.ext.autodoc import Options
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.parsing import nested_parse_to_nodes
 
 if TYPE_CHECKING:
+    from typing import Any
+
     from docutils.nodes import Node
     from docutils.parsers.rst.states import RSTState
+    from docutils.utils import Reporter
 
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
+    from sphinx.ext.autodoc import Documenter
 
 logger = logging.getLogger(__name__)
 
 
 # common option names for autodoc directives
-AUTODOC_DEFAULT_OPTIONS = ['members', 'undoc-members', 'inherited-members',
-                           'show-inheritance', 'private-members', 'special-members',
-                           'ignore-module-all', 'exclude-members', 'member-order',
-                           'imported-members', 'class-doc-from', 'no-value']
-
-AUTODOC_EXTENDABLE_OPTIONS = ['members', 'private-members', 'special-members',
-                              'exclude-members']
+AUTODOC_DEFAULT_OPTIONS = [
+    'members',
+    'undoc-members',
+    'no-index',
+    'no-index-entry',
+    'inherited-members',
+    'show-inheritance',
+    'private-members',
+    'special-members',
+    'ignore-module-all',
+    'exclude-members',
+    'member-order',
+    'imported-members',
+    'class-doc-from',
+    'no-value',
+]
+
+AUTODOC_EXTENDABLE_OPTIONS = frozenset({
+    'members',
+    'private-members',
+    'special-members',
+    'exclude-members',
+})
 
 
 class DummyOptionSpec(dict[str, Callable[[str], str]]):
@@ -46,8 +66,14 @@ class DummyOptionSpec(dict[str, Callable[[str], str]]):
 class DocumenterBridge:
     """A parameters container for Documenters."""
 
-    def __init__(self, env: BuildEnvironment, reporter: Reporter | None, options: Options,
-                 lineno: int, state: Any) -> None:
+    def __init__(
+        self,
+        env: BuildEnvironment,
+        reporter: Reporter | None,
+        options: Options,
+        lineno: int,
+        state: Any,
+    ) -> None:
         self.env = env
         self._reporter = reporter
         self.genopt = options
@@ -58,7 +84,7 @@ class DocumenterBridge:
 
 
 def process_documenter_options(
-    documenter: type[Documenter], config: Config, options: dict[str, str],
+    documenter: type[Documenter], config: Config, options: dict[str, str]
 ) -> Options:
     """Recognize options of Documenter from user input."""
     default_options = config.autodoc_default_options
@@ -83,8 +109,9 @@ def process_documenter_options(
     return Options(assemble_option_dict(options.items(), documenter.option_spec))
 
 
-def parse_generated_content(state: RSTState, content: StringList, documenter: Documenter,
-                            ) -> list[Node]:
+def parse_generated_content(
+    state: RSTState, content: StringList, documenter: Documenter
+) -> list[Node]:
     """Parse an item of content generated by Documenter."""
     with switch_source_input(state, content):
         if documenter.titles_allowed:
@@ -115,26 +142,35 @@ class AutodocDirective(SphinxDirective):
 
         try:
             source, lineno = reporter.get_source_and_line(  # type: ignore[attr-defined]
-                self.lineno)
+                self.lineno
+            )
         except AttributeError:
             source, lineno = (None, None)
         logger.debug('[autodoc] %s:%s: input:\n%s', source, lineno, self.block_text)
 
         # look up target Documenter
         objtype = self.name[4:]  # strip prefix (auto-).
-        doccls = self.env.app.registry.documenters[objtype]
+        doccls = self.env._registry.documenters[objtype]
 
         # process the options with the selected documenter's option_spec
         try:
-            documenter_options = process_documenter_options(doccls, self.config, self.options)
+            documenter_options = process_documenter_options(
+                doccls, self.config, self.options
+            )
         except (KeyError, ValueError, TypeError) as exc:
             # an option is either unknown or has a wrong type
-            logger.error('An option to %s is either unknown or has an invalid value: %s',
-                         self.name, exc, location=(self.env.docname, lineno))
+            logger.error(  # NoQA: TRY400
+                'An option to %s is either unknown or has an invalid value: %s',
+                self.name,
+                exc,
+                location=(self.env.docname, lineno),
+            )
             return []
 
         # generate the output
-        params = DocumenterBridge(self.env, reporter, documenter_options, lineno, self.state)
+        params = DocumenterBridge(
+            self.env, reporter, documenter_options, lineno, self.state
+        )
         documenter = doccls(params, self.arguments[0])
         documenter.generate(more_content=self.content)
         if not params.result:

sphinx/ext/autodoc/importer.py

@@ -9,6 +9,10 @@ import sys
 import traceback
 import typing
 from enum import Enum
+from importlib.abc import FileLoader
+from importlib.machinery import EXTENSION_SUFFIXES
+from importlib.util import decode_source, find_spec, module_from_spec, spec_from_loader
+from pathlib import Path
 from typing import TYPE_CHECKING, NamedTuple
 
 from sphinx.errors import PycodeError
@@ -26,18 +30,24 @@ from sphinx.util.inspect import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Mapping
+    from collections.abc import Iterator, Mapping
+    from importlib.machinery import ModuleSpec
     from types import ModuleType
-    from typing import Any
+    from typing import Any, Protocol
 
     from sphinx.ext.autodoc import ObjectMember
 
+    class _AttrGetter(Protocol):
+        def __call__(self, obj: Any, name: str, default: Any = ..., /) -> Any: ...
+
+
+_NATIVE_SUFFIXES: frozenset[str] = frozenset({'.pyx', *EXTENSION_SUFFIXES})
 logger = logging.getLogger(__name__)
 
 
 def _filter_enum_dict(
     enum_class: type[Enum],
-    attrgetter: Callable[[Any, str, Any], Any],
+    attrgetter: _AttrGetter,
     enum_class_dict: Mapping[str, object],
 ) -> Iterator[tuple[str, type, Any]]:
     """Find the attributes to document of an enumeration class.
@@ -51,19 +61,21 @@ def _filter_enum_dict(
     candidate_in_mro: set[str] = set()
     # sunder names that were picked up (and thereby allowed to be redefined)
     # see: https://docs.python.org/3/howto/enum.html#supported-dunder-names
-    sunder_names = {'_name_', '_value_', '_missing_', '_order_', '_generate_next_value_'}
+    sunder_names = {
+        '_name_',
+        '_value_',
+        '_missing_',
+        '_order_',
+        '_generate_next_value_',
+    }
     # attributes that can be picked up on a mixin type or the enum's data type
     public_names = {'name', 'value', *object.__dict__, *sunder_names}
     # names that are ignored by default
     ignore_names = Enum.__dict__.keys() - public_names
 
-    def is_native_api(obj: object, name: str) -> bool:
-        """Check whether *obj* is the same as ``Enum.__dict__[name]``."""
-        return unwrap_all(obj) is unwrap_all(Enum.__dict__[name])
-
     def should_ignore(name: str, value: Any) -> bool:
         if name in sunder_names:
-            return is_native_api(value, name)
+            return _is_native_enum_api(value, name)
         return name in ignore_names
 
     sentinel = object()
@@ -71,7 +83,7 @@ def _filter_enum_dict(
     def query(name: str, defining_class: type) -> tuple[str, type, Any] | None:
         value = attrgetter(enum_class, name, sentinel)
         if value is not sentinel:
-            return (name, defining_class, value)
+            return name, defining_class, value
         return None
 
     # attributes defined on a parent type, possibly shadowed later by
@@ -92,8 +104,14 @@ def _filter_enum_dict(
     # exclude members coming from the native Enum unless
     # they were redefined on a mixin type or the data type
     excluded_members = Enum.__dict__.keys() - candidate_in_mro
-    yield from filter(None, (query(name, enum_class) for name in enum_class_dict
-                             if name not in excluded_members))
+    yield from filter(
+        None,
+        (
+            query(name, enum_class)
+            for name in enum_class_dict
+            if name not in excluded_members
+        ),
+    )
 
     # check if allowed members from ``Enum`` were redefined at the enum level
     special_names = sunder_names | public_names
@@ -101,17 +119,22 @@ def _filter_enum_dict(
     special_names &= Enum.__dict__.keys()
     for name in special_names:
         if (
-            not is_native_api(enum_class_dict[name], name)
+            not _is_native_enum_api(enum_class_dict[name], name)
             and (item := query(name, enum_class)) is not None
         ):
             yield item
 
 
+def _is_native_enum_api(obj: object, name: str) -> bool:
+    """Check whether *obj* is the same as ``Enum.__dict__[name]``."""
+    return unwrap_all(obj) is unwrap_all(Enum.__dict__[name])
+
+
 def mangle(subject: Any, name: str) -> str:
     """Mangle the given name."""
     try:
         if isclass(subject) and name.startswith('__') and not name.endswith('__'):
-            return f"_{subject.__name__}{name}"
+            return f'_{subject.__name__}{name}'
     except AttributeError:
         pass
 
@@ -122,12 +145,12 @@ def unmangle(subject: Any, name: str) -> str | None:
     """Unmangle the given name."""
     try:
         if isclass(subject) and not name.endswith('__'):
-            prefix = "_%s__" % subject.__name__
+            prefix = f'_{subject.__name__}__'
             if name.startswith(prefix):
-                return name.replace(prefix, "__", 1)
+                return name.replace(prefix, '__', 1)
             else:
                 for cls in subject.__mro__:
-                    prefix = "_%s__" % cls.__name__
+                    prefix = f'_{cls.__name__}__'
                     if name.startswith(prefix):
                         # mangled attribute defined in parent class
                         return None
@@ -137,20 +160,87 @@ def unmangle(subject: Any, name: str) -> str | None:
     return name
 
 
-def import_module(modname: str) -> Any:
-    """Call importlib.import_module(modname), convert exceptions to ImportError."""
+def import_module(modname: str, try_reload: bool = False) -> Any:
+    if modname in sys.modules:
+        return sys.modules[modname]
+
+    original_module_names = frozenset(sys.modules)
     try:
-        return importlib.import_module(modname)
+        spec = find_spec(modname)
+        if spec is None:
+            msg = f'No module named {modname!r}'
+            raise ModuleNotFoundError(msg, name=modname)  # NoQA: TRY301
+        spec, pyi_path = _find_type_stub_spec(spec, modname)
+        if pyi_path is None:
+            module = importlib.import_module(modname)
+        else:
+            if spec.loader is None:
+                msg = 'missing loader'
+                raise ImportError(msg, name=spec.name)  # NoQA: TRY301
+            sys.modules[modname] = module = module_from_spec(spec)
+            spec.loader.exec_module(module)
+    except ImportError:
+        raise
     except BaseException as exc:
         # Importing modules may cause any side effects, including
         # SystemExit, so we need to catch all errors.
         raise ImportError(exc, traceback.format_exc()) from exc
+    if try_reload and os.environ.get('SPHINX_AUTODOC_RELOAD_MODULES'):
+        new_modules = [m for m in sys.modules if m not in original_module_names]
+        # Try reloading modules with ``typing.TYPE_CHECKING == True``.
+        try:
+            typing.TYPE_CHECKING = True  # type: ignore[misc]
+            # Ignore failures; we've already successfully loaded these modules
+            with contextlib.suppress(ImportError, KeyError):
+                for m in new_modules:
+                    mod_path = getattr(sys.modules[m], '__file__', '')
+                    if mod_path and mod_path.endswith('.pyi'):
+                        continue
+                    _reload_module(sys.modules[m])
+        finally:
+            typing.TYPE_CHECKING = False  # type: ignore[misc]
+        module = sys.modules[modname]
+    return module
+
+
+def _find_type_stub_spec(
+    spec: ModuleSpec, modname: str
+) -> tuple[ModuleSpec, Path | None]:
+    """Try finding a spec for a PEP 561 '.pyi' stub file for native modules."""
+    if spec.origin is None:
+        return spec, None
+
+    for suffix in _NATIVE_SUFFIXES:
+        if not spec.origin.endswith(suffix):
+            continue
+        pyi_path = Path(spec.origin.removesuffix(suffix) + '.pyi')
+        if not pyi_path.is_file():
+            continue
+        pyi_loader = _StubFileLoader(modname, path=str(pyi_path))
+        pyi_spec = spec_from_loader(modname, loader=pyi_loader)
+        if pyi_spec is not None:
+            return pyi_spec, pyi_path
+    return spec, None
+
+
+class _StubFileLoader(FileLoader):
+    """Load modules from ``.pyi`` stub files."""
+
+    def get_source(self, fullname: str) -> str:
+        path = self.get_filename(fullname)
+        for suffix in _NATIVE_SUFFIXES:
+            if not path.endswith(suffix):
+                continue
+            path = path.removesuffix(suffix) + '.pyi'
+        try:
+            source_bytes = self.get_data(path)
+        except OSError as exc:
+            raise ImportError from exc
+        return decode_source(source_bytes)
 
 
 def _reload_module(module: ModuleType) -> Any:
-    """
-    Call importlib.reload(module), convert exceptions to ImportError
-    """
+    """Call importlib.reload(module), convert exceptions to ImportError"""
     try:
         return importlib.reload(module)
     except BaseException as exc:
@@ -159,8 +249,12 @@ def _reload_module(module: ModuleType) -> Any:
         raise ImportError(exc, traceback.format_exc()) from exc
 
 
-def import_object(modname: str, objpath: list[str], objtype: str = '',
-                  attrgetter: Callable[[Any, str], Any] = safe_getattr) -> Any:
+def import_object(
+    modname: str,
+    objpath: list[str],
+    objtype: str = '',
+    attrgetter: _AttrGetter = safe_getattr,
+) -> Any:
     if objpath:
         logger.debug('[autodoc] from %s import %s', modname, '.'.join(objpath))
     else:
@@ -172,20 +266,7 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
         objpath = objpath.copy()
         while module is None:
             try:
-                original_module_names = frozenset(sys.modules)
-                module = import_module(modname)
-                if os.environ.get('SPHINX_AUTODOC_RELOAD_MODULES'):
-                    new_modules = [m for m in sys.modules if m not in original_module_names]
-                    # Try reloading modules with ``typing.TYPE_CHECKING == True``.
-                    try:
-                        typing.TYPE_CHECKING = True
-                        # Ignore failures; we've already successfully loaded these modules
-                        with contextlib.suppress(ImportError, KeyError):
-                            for m in new_modules:
-                                _reload_module(sys.modules[m])
-                    finally:
-                        typing.TYPE_CHECKING = False
-                    module = sys.modules[modname]
+                module = import_module(modname, try_reload=True)
                 logger.debug('[autodoc] import %s => %r', modname, module)
             except ImportError as exc:
                 logger.debug('[autodoc] import %s => failed', modname)
@@ -210,7 +291,7 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
                 logger.debug('[autodoc] => %r', obj)
             except TypeError:
                 # fallback of failure on logging for broken object
-                # refs: https://github.com/sphinx-doc/sphinx/issues/9095
+                # See: https://github.com/sphinx-doc/sphinx/issues/9095
                 logger.debug('[autodoc] => %r', (obj,))
 
             object_name = attrname
@@ -221,24 +302,32 @@ def import_object(modname: str, objpath: list[str], objtype: str = '',
             exc = exc_on_importing
 
         if objpath:
-            errmsg = ('autodoc: failed to import %s %r from module %r' %
-                      (objtype, '.'.join(objpath), modname))
+            errmsg = 'autodoc: failed to import %s %r from module %r' % (
+                objtype,
+                '.'.join(objpath),
+                modname,
+            )
         else:
             errmsg = f'autodoc: failed to import {objtype} {modname!r}'
 
         if isinstance(exc, ImportError):
             # import_module() raises ImportError having real exception obj and
             # traceback
-            real_exc, traceback_msg = exc.args
+            real_exc = exc.args[0]
+            traceback_msg = traceback.format_exception(exc)
             if isinstance(real_exc, SystemExit):
-                errmsg += ('; the module executes module level statement '
-                           'and it might call sys.exit().')
+                errmsg += (
+                    '; the module executes module level statement '
+                    'and it might call sys.exit().'
+                )
             elif isinstance(real_exc, ImportError) and real_exc.args:
                 errmsg += '; the following exception was raised:\n%s' % real_exc.args[0]
             else:
                 errmsg += '; the following exception was raised:\n%s' % traceback_msg
         else:
-            errmsg += '; the following exception was raised:\n%s' % traceback.format_exc()
+            errmsg += (
+                '; the following exception was raised:\n%s' % traceback.format_exc()
+            )
 
         logger.debug(errmsg)
         raise ImportError(errmsg) from exc
@@ -253,7 +342,7 @@ class Attribute(NamedTuple):
 def get_object_members(
     subject: Any,
     objpath: list[str],
-    attrgetter: Callable,
+    attrgetter: _AttrGetter,
     analyzer: ModuleAnalyzer | None = None,
 ) -> dict[str, Attribute]:
     """Get members and attributes of target object."""
@@ -266,11 +355,17 @@ def get_object_members(
 
     # enum members
     if isenumclass(subject):
-        for name, defining_class, value in _filter_enum_dict(subject, attrgetter, obj_dict):
+        for name, defining_class, value in _filter_enum_dict(
+            subject, attrgetter, obj_dict
+        ):
             # the order of occurrence of *name* matches the subject's MRO,
             # allowing inherited attributes to be shadowed correctly
             if unmangled := unmangle(defining_class, name):
-                members[unmangled] = Attribute(unmangled, defining_class is subject, value)
+                members[unmangled] = Attribute(
+                    name=unmangled,
+                    directly_defined=defining_class is subject,
+                    value=value,
+                )
 
     # members in __slots__
     try:
@@ -279,7 +374,9 @@ def get_object_members(
             from sphinx.ext.autodoc import SLOTSATTR
 
             for name in subject___slots__:
-                members[name] = Attribute(name, True, SLOTSATTR)
+                members[name] = Attribute(
+                    name=name, directly_defined=True, value=SLOTSATTR
+                )
     except (TypeError, ValueError):
         pass
 
@@ -290,7 +387,9 @@ def get_object_members(
             directly_defined = name in obj_dict
             unmangled = unmangle(subject, name)
             if unmangled and unmangled not in members:
-                members[unmangled] = Attribute(unmangled, directly_defined, value)
+                members[unmangled] = Attribute(
+                    name=unmangled, directly_defined=directly_defined, value=value
+                )
         except AttributeError:
             continue
 
@@ -299,20 +398,25 @@ def get_object_members(
         for name in getannotations(cls):
             unmangled = unmangle(cls, name)
             if unmangled and unmangled not in members:
-                members[unmangled] = Attribute(unmangled, cls is subject, INSTANCEATTR)
+                members[unmangled] = Attribute(
+                    name=unmangled, directly_defined=cls is subject, value=INSTANCEATTR
+                )
 
     if analyzer:
         # append instance attributes (cf. self.attr1) if analyzer knows
         namespace = '.'.join(objpath)
-        for (ns, name) in analyzer.find_attr_docs():
+        for ns, name in analyzer.find_attr_docs():
             if namespace == ns and name not in members:
-                members[name] = Attribute(name, True, INSTANCEATTR)
+                members[name] = Attribute(
+                    name=name, directly_defined=True, value=INSTANCEATTR
+                )
 
     return members
 
 
-def get_class_members(subject: Any, objpath: Any, attrgetter: Callable,
-                      inherit_docstrings: bool = True) -> dict[str, ObjectMember]:
+def get_class_members(
+    subject: Any, objpath: Any, attrgetter: _AttrGetter, inherit_docstrings: bool = True
+) -> dict[str, ObjectMember]:
     """Get members and attributes of target class."""
     from sphinx.ext.autodoc import INSTANCEATTR, ObjectMember
 
@@ -323,11 +427,15 @@ def get_class_members(subject: Any, objpath: Any, attrgetter: Callable,
 
     # enum members
     if isenumclass(subject):
-        for name, defining_class, value in _filter_enum_dict(subject, attrgetter, obj_dict):
+        for name, defining_class, value in _filter_enum_dict(
+            subject, attrgetter, obj_dict
+        ):
             # the order of occurrence of *name* matches the subject's MRO,
             # allowing inherited attributes to be shadowed correctly
             if unmangled := unmangle(defining_class, name):
-                members[unmangled] = ObjectMember(unmangled, value, class_=defining_class)
+                members[unmangled] = ObjectMember(
+                    unmangled, value, class_=defining_class
+                )
 
     # members in __slots__
     try:
@@ -336,8 +444,9 @@ def get_class_members(subject: Any, objpath: Any, attrgetter: Callable,
             from sphinx.ext.autodoc import SLOTSATTR
 
             for name, docstring in subject___slots__.items():
-                members[name] = ObjectMember(name, SLOTSATTR, class_=subject,
-                                             docstring=docstring)
+                members[name] = ObjectMember(
+                    name, SLOTSATTR, class_=subject, docstring=docstring
+                )
     except (TypeError, ValueError):
         pass
 
@@ -379,19 +488,27 @@ def get_class_members(subject: Any, objpath: Any, attrgetter: Callable,
                     else:
                         docstring = None
 
-                    members[unmangled] = ObjectMember(unmangled, INSTANCEATTR, class_=cls,
-                                                      docstring=docstring)
+                    members[unmangled] = ObjectMember(
+                        unmangled, INSTANCEATTR, class_=cls, docstring=docstring
+                    )
 
             # append or complete instance attributes (cf. self.attr1) if analyzer knows
             if analyzer:
                 for (ns, name), docstring in analyzer.attr_docs.items():
                     if ns == qualname and name not in members:
                         # otherwise unknown instance attribute
-                        members[name] = ObjectMember(name, INSTANCEATTR, class_=cls,
-                                                     docstring='\n'.join(docstring))
-                    elif (ns == qualname and docstring and
-                          isinstance(members[name], ObjectMember) and
-                          not members[name].docstring):
+                        members[name] = ObjectMember(
+                            name,
+                            INSTANCEATTR,
+                            class_=cls,
+                            docstring='\n'.join(docstring),
+                        )
+                    elif (
+                        ns == qualname
+                        and docstring
+                        and isinstance(members[name], ObjectMember)
+                        and not members[name].docstring
+                    ):
                         if cls != subject and not inherit_docstrings:
                             # If we are in the MRO of the class and not the class itself,
                             # and we do not want to inherit docstrings, then skip setting

sphinx/ext/autodoc/mock.py

@@ -35,8 +35,12 @@ class _MockObject:
             superclass = args[1][-1].__class__
             if superclass is cls:
                 # subclassing MockObject
-                return _make_subclass(args[0], superclass.__display_name__,
-                                      superclass=superclass, attributes=args[2])
+                return _make_subclass(
+                    args[0],
+                    superclass.__display_name__,
+                    superclass=superclass,
+                    attributes=args[2],
+                )
 
         return super().__new__(cls)
 
@@ -70,12 +74,19 @@ class _MockObject:
         return self.__display_name__
 
 
-def _make_subclass(name: str, module: str, superclass: Any = _MockObject,
-                   attributes: Any = None, decorator_args: tuple[Any, ...] = ()) -> Any:
-    attrs = {'__module__': module,
-             '__display_name__': module + '.' + name,
-             '__name__': name,
-             '__sphinx_decorator_args__': decorator_args}
+def _make_subclass(
+    name: str,
+    module: str,
+    superclass: Any = _MockObject,
+    attributes: Any = None,
+    decorator_args: tuple[Any, ...] = (),
+) -> Any:
+    attrs = {
+        '__module__': module,
+        '__display_name__': module + '.' + name,
+        '__name__': name,
+        '__sphinx_decorator_args__': decorator_args,
+    }
     attrs.update(attributes or {})
 
     return type(name, (superclass,), attrs)
@@ -124,8 +135,12 @@ class MockFinder(MetaPathFinder):
         self.loader = MockLoader(self)
         self.mocked_modules: list[str] = []
 
-    def find_spec(self, fullname: str, path: Sequence[bytes | str] | None,
-                  target: ModuleType | None = None) -> ModuleSpec | None:
+    def find_spec(
+        self,
+        fullname: str,
+        path: Sequence[bytes | str] | None,
+        target: ModuleType | None = None,
+    ) -> ModuleSpec | None:
         for modname in self.modnames:
             # check if fullname is (or is a descendant of) one of our targets
             if modname == fullname or fullname.startswith(modname + '.'):