py2docfx 0.1.11.dev1830301__py3-none-any.whl → 0.1.11.dev1859874__py3-none-any.whl

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/directive.py

@@ -1,148 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Callable
-
-from docutils import nodes
-from docutils.nodes import Element, Node
-from docutils.parsers.rst.states import RSTState
-from docutils.statemachine import StringList
-from docutils.utils import Reporter, assemble_option_dict
-
-from sphinx.config import Config
-from sphinx.environment import BuildEnvironment
-from sphinx.ext.autodoc import Documenter, Options
-from sphinx.util import logging
-from sphinx.util.docutils import SphinxDirective, switch_source_input
-from sphinx.util.nodes import nested_parse_with_titles
-
-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']
-
-
-class DummyOptionSpec(dict):
-    """An option_spec allows any options."""
-
-    def __bool__(self) -> bool:
-        """Behaves like some options are defined."""
-        return True
-
-    def __getitem__(self, key: str) -> Callable[[str], str]:
-        return lambda x: x
-
-
-class DocumenterBridge:
-    """A parameters container for Documenters."""
-
-    def __init__(self, env: BuildEnvironment, reporter: Reporter | None, options: Options,
-                 lineno: int, state: Any) -> None:
-        self.env = env
-        self._reporter = reporter
-        self.genopt = options
-        self.lineno = lineno
-        self.record_dependencies: set[str] = set()
-        self.result = StringList()
-        self.state = state
-
-
-def process_documenter_options(documenter: type[Documenter], config: Config, options: dict
-                               ) -> Options:
-    """Recognize options of Documenter from user input."""
-    for name in AUTODOC_DEFAULT_OPTIONS:
-        if name not in documenter.option_spec:
-            continue
-        else:
-            negated = options.pop('no-' + name, True) is None
-            if name in config.autodoc_default_options and not negated:
-                if name in options and isinstance(config.autodoc_default_options[name], str):
-                    # take value from options if present or extend it
-                    # with autodoc_default_options if necessary
-                    if name in AUTODOC_EXTENDABLE_OPTIONS:
-                        if options[name] is not None and options[name].startswith('+'):
-                            options[name] = ','.join([config.autodoc_default_options[name],
-                                                      options[name][1:]])
-                else:
-                    options[name] = config.autodoc_default_options[name]
-
-            elif options.get(name) is not None:
-                # remove '+' from option argument if there's nothing to merge it with
-                options[name] = options[name].lstrip('+')
-
-    return Options(assemble_option_dict(options.items(), documenter.option_spec))
-
-
-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:
-            node: Element = nodes.section()
-            # necessary so that the child nodes get the right source/line set
-            node.document = state.document
-            nested_parse_with_titles(state, content, node)
-        else:
-            node = nodes.paragraph()
-            node.document = state.document
-            state.nested_parse(content, 0, node)
-
-        return node.children
-
-
-class AutodocDirective(SphinxDirective):
-    """A directive class for all autodoc directives. It works as a dispatcher of Documenters.
-
-    It invokes a Documenter upon running. After the processing, it parses and returns
-    the content generated by Documenter.
-    """
-    option_spec = DummyOptionSpec()
-    has_content = True
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = True
-
-    def run(self) -> list[Node]:
-        reporter = self.state.document.reporter
-
-        try:
-            source, lineno = reporter.get_source_and_line(self.lineno)  # type: ignore
-        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]
-
-        # process the options with the selected documenter's option_spec
-        try:
-            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))
-            return []
-
-        # generate the output
-        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:
-            return []
-
-        logger.debug('[autodoc] output:\n%s', '\n'.join(params.result))
-
-        # record all filenames as dependencies -- this will at least
-        # partially make automatic invalidation possible
-        for fn in params.record_dependencies:
-            self.state.document.settings.record_dependencies.add(fn)
-
-        result = parse_generated_content(self.state, params.result, documenter)
-        return result

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/importer.py

@@ -1,307 +0,0 @@
-"""Importer utilities for autodoc"""
-
-from __future__ import annotations
-
-import importlib
-import traceback
-import warnings
-from typing import TYPE_CHECKING, Any, Callable, NamedTuple
-
-from sphinx.ext.autodoc.mock import ismock, undecorate
-from sphinx.pycode import ModuleAnalyzer, PycodeError
-from sphinx.util import logging
-from sphinx.util.inspect import (getannotations, getmro, getslots, isclass, isenumclass,
-                                 safe_getattr)
-
-if TYPE_CHECKING:
-    from sphinx.ext.autodoc import ObjectMember
-
-logger = logging.getLogger(__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}"
-    except AttributeError:
-        pass
-
-    return name
-
-
-def unmangle(subject: Any, name: str) -> str | None:
-    """Unmangle the given name."""
-    try:
-        if isclass(subject) and not name.endswith('__'):
-            prefix = "_%s__" % subject.__name__
-            if name.startswith(prefix):
-                return name.replace(prefix, "__", 1)
-            else:
-                for cls in subject.__mro__:
-                    prefix = "_%s__" % cls.__name__
-                    if name.startswith(prefix):
-                        # mangled attribute defined in parent class
-                        return None
-    except AttributeError:
-        pass
-
-    return name
-
-
-def import_module(modname: str, warningiserror: bool = False) -> Any:
-    """
-    Call importlib.import_module(modname), convert exceptions to ImportError
-    """
-    try:
-        with warnings.catch_warnings():
-            warnings.filterwarnings("ignore", category=ImportWarning)
-            with logging.skip_warningiserror(not warningiserror):
-                return importlib.import_module(modname)
-    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
-
-
-def import_object(modname: str, objpath: list[str], objtype: str = '',
-                  attrgetter: Callable[[Any, str], Any] = safe_getattr,
-                  warningiserror: bool = False) -> Any:
-    if objpath:
-        logger.debug('[autodoc] from %s import %s', modname, '.'.join(objpath))
-    else:
-        logger.debug('[autodoc] import %s', modname)
-
-    try:
-        module = None
-        exc_on_importing = None
-        objpath = list(objpath)
-        while module is None:
-            try:
-                module = import_module(modname, warningiserror=warningiserror)
-                logger.debug('[autodoc] import %s => %r', modname, module)
-            except ImportError as exc:
-                logger.debug('[autodoc] import %s => failed', modname)
-                exc_on_importing = exc
-                if '.' in modname:
-                    # retry with parent module
-                    modname, name = modname.rsplit('.', 1)
-                    objpath.insert(0, name)
-                else:
-                    raise
-
-        obj = module
-        parent = None
-        object_name = None
-        for attrname in objpath:
-            parent = obj
-            logger.debug('[autodoc] getattr(_, %r)', attrname)
-            mangled_name = mangle(obj, attrname)
-            obj = attrgetter(obj, mangled_name)
-
-            try:
-                logger.debug('[autodoc] => %r', obj)
-            except TypeError:
-                # fallback of failure on logging for broken object
-                # refs: https://github.com/sphinx-doc/sphinx/issues/9095
-                logger.debug('[autodoc] => %r', (obj,))
-
-            object_name = attrname
-        return [module, parent, object_name, obj]
-    except (AttributeError, ImportError) as exc:
-        if isinstance(exc, AttributeError) and exc_on_importing:
-            # restore ImportError
-            exc = exc_on_importing
-
-        if objpath:
-            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
-            if isinstance(real_exc, SystemExit):
-                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()
-
-        logger.debug(errmsg)
-        raise ImportError(errmsg) from exc
-
-
-class Attribute(NamedTuple):
-    name: str
-    directly_defined: bool
-    value: Any
-
-
-def get_object_members(
-    subject: Any,
-    objpath: list[str],
-    attrgetter: Callable,
-    analyzer: ModuleAnalyzer | None = None
-) -> dict[str, Attribute]:
-    """Get members and attributes of target object."""
-    from sphinx.ext.autodoc import INSTANCEATTR
-
-    # the members directly defined in the class
-    obj_dict = attrgetter(subject, '__dict__', {})
-
-    members: dict[str, Attribute] = {}
-
-    # enum members
-    if isenumclass(subject):
-        for name, value in subject.__members__.items():
-            if name not in members:
-                members[name] = Attribute(name, True, value)
-
-        superclass = subject.__mro__[1]
-        for name in obj_dict:
-            if name not in superclass.__dict__:
-                value = safe_getattr(subject, name)
-                members[name] = Attribute(name, True, value)
-
-    # members in __slots__
-    try:
-        __slots__ = getslots(subject)
-        if __slots__:
-            from sphinx.ext.autodoc import SLOTSATTR
-
-            for name in __slots__:
-                members[name] = Attribute(name, True, SLOTSATTR)
-    except (TypeError, ValueError):
-        pass
-
-    # other members
-    for name in dir(subject):
-        try:
-            value = attrgetter(subject, name)
-            directly_defined = name in obj_dict
-            name = unmangle(subject, name)
-            if name and name not in members:
-                members[name] = Attribute(name, directly_defined, value)
-        except AttributeError:
-            continue
-
-    # annotation only member (ex. attr: int)
-    for i, cls in enumerate(getmro(subject)):
-        for name in getannotations(cls):
-            name = unmangle(cls, name)
-            if name and name not in members:
-                members[name] = Attribute(name, i == 0, INSTANCEATTR)
-
-    if analyzer:
-        # append instance attributes (cf. self.attr1) if analyzer knows
-        namespace = '.'.join(objpath)
-        for (ns, name) in analyzer.find_attr_docs():
-            if namespace == ns and name not in members:
-                members[name] = Attribute(name, True, INSTANCEATTR)
-
-    return members
-
-
-def get_class_members(subject: Any, objpath: list[str], attrgetter: Callable,
-                      inherit_docstrings: bool = True) -> dict[str, ObjectMember]:
-    """Get members and attributes of target class."""
-    from sphinx.ext.autodoc import INSTANCEATTR, ObjectMember
-
-    # the members directly defined in the class
-    obj_dict = attrgetter(subject, '__dict__', {})
-
-    members: dict[str, ObjectMember] = {}
-
-    # enum members
-    if isenumclass(subject):
-        for name, value in subject.__members__.items():
-            if name not in members:
-                members[name] = ObjectMember(name, value, class_=subject)
-
-        superclass = subject.__mro__[1]
-        for name in obj_dict:
-            if name not in superclass.__dict__:
-                value = safe_getattr(subject, name)
-                members[name] = ObjectMember(name, value, class_=subject)
-
-    # members in __slots__
-    try:
-        __slots__ = getslots(subject)
-        if __slots__:
-            from sphinx.ext.autodoc import SLOTSATTR
-
-            for name, docstring in __slots__.items():
-                members[name] = ObjectMember(name, SLOTSATTR, class_=subject,
-                                             docstring=docstring)
-    except (TypeError, ValueError):
-        pass
-
-    # other members
-    for name in dir(subject):
-        try:
-            value = attrgetter(subject, name)
-            if ismock(value):
-                value = undecorate(value)
-
-            unmangled = unmangle(subject, name)
-            if unmangled and unmangled not in members:
-                if name in obj_dict:
-                    members[unmangled] = ObjectMember(unmangled, value, class_=subject)
-                else:
-                    members[unmangled] = ObjectMember(unmangled, value)
-        except AttributeError:
-            continue
-
-    try:
-        for cls in getmro(subject):
-            try:
-                modname = safe_getattr(cls, '__module__')
-                qualname = safe_getattr(cls, '__qualname__')
-                analyzer = ModuleAnalyzer.for_module(modname)
-                analyzer.analyze()
-            except AttributeError:
-                qualname = None
-                analyzer = None
-            except PycodeError:
-                analyzer = None
-
-            # annotation only member (ex. attr: int)
-            for name in getannotations(cls):
-                name = unmangle(cls, name)
-                if name and name not in members:
-                    if analyzer and (qualname, name) in analyzer.attr_docs:
-                        docstring = '\n'.join(analyzer.attr_docs[qualname, name])
-                    else:
-                        docstring = None
-
-                    members[name] = ObjectMember(name, 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):
-                        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
-                            # the docstring below
-                            continue
-                        # attribute is already known, because dir(subject) enumerates it.
-                        # But it has no docstring yet
-                        members[name].docstring = '\n'.join(docstring)
-    except AttributeError:
-        pass
-
-    return members

py2docfx/venv/template/Lib/site-packages/sphinx/ext/autodoc/mock.py

@@ -1,195 +0,0 @@
-"""mock for autodoc"""
-
-from __future__ import annotations
-
-import contextlib
-import os
-import sys
-from importlib.abc import Loader, MetaPathFinder
-from importlib.machinery import ModuleSpec
-from types import MethodType, ModuleType
-from typing import Any, Generator, Iterator, Sequence
-
-from sphinx.util import logging
-from sphinx.util.inspect import isboundmethod, safe_getattr
-
-logger = logging.getLogger(__name__)
-
-
-class _MockObject:
-    """Used by autodoc_mock_imports."""
-
-    __display_name__ = '_MockObject'
-    __name__ = ''
-    __sphinx_mock__ = True
-    __sphinx_decorator_args__: tuple[Any, ...] = ()
-
-    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
-        if len(args) == 3 and isinstance(args[1], tuple):
-            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 super().__new__(cls)
-
-    def __init__(self, *args: Any, **kwargs: Any) -> None:
-        self.__qualname__ = self.__name__
-
-    def __len__(self) -> int:
-        return 0
-
-    def __contains__(self, key: str) -> bool:
-        return False
-
-    def __iter__(self) -> Iterator:
-        return iter([])
-
-    def __mro_entries__(self, bases: tuple) -> tuple:
-        return (self.__class__,)
-
-    def __getitem__(self, key: Any) -> _MockObject:
-        return _make_subclass(str(key), self.__display_name__, self.__class__)()
-
-    def __getattr__(self, key: str) -> _MockObject:
-        return _make_subclass(key, self.__display_name__, self.__class__)()
-
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
-        call = self.__class__()
-        call.__sphinx_decorator_args__ = args
-        return call
-
-    def __repr__(self) -> str:
-        return self.__display_name__
-
-
-def _make_subclass(name: str, module: str, superclass: Any = _MockObject,
-                   attributes: Any = None, decorator_args: tuple = ()) -> Any:
-    attrs = {'__module__': module,
-             '__display_name__': module + '.' + name,
-             '__name__': name,
-             '__sphinx_decorator_args__': decorator_args}
-    attrs.update(attributes or {})
-
-    return type(name, (superclass,), attrs)
-
-
-class _MockModule(ModuleType):
-    """Used by autodoc_mock_imports."""
-    __file__ = os.devnull
-    __sphinx_mock__ = True
-
-    def __init__(self, name: str) -> None:
-        super().__init__(name)
-        self.__all__: list[str] = []
-        self.__path__: list[str] = []
-
-    def __getattr__(self, name: str) -> _MockObject:
-        return _make_subclass(name, self.__name__)()
-
-    def __repr__(self) -> str:
-        return self.__name__
-
-
-class MockLoader(Loader):
-    """A loader for mocking."""
-    def __init__(self, finder: MockFinder) -> None:
-        super().__init__()
-        self.finder = finder
-
-    def create_module(self, spec: ModuleSpec) -> ModuleType:
-        logger.debug('[autodoc] adding a mock module as %s!', spec.name)
-        self.finder.mocked_modules.append(spec.name)
-        return _MockModule(spec.name)
-
-    def exec_module(self, module: ModuleType) -> None:
-        pass  # nothing to do
-
-
-class MockFinder(MetaPathFinder):
-    """A finder for mocking."""
-
-    def __init__(self, modnames: list[str]) -> None:
-        super().__init__()
-        self.modnames = modnames
-        self.loader = MockLoader(self)
-        self.mocked_modules: list[str] = []
-
-    def find_spec(self, fullname: str, path: Sequence[bytes | str] | None,
-                  target: ModuleType = 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 + '.'):
-                return ModuleSpec(fullname, self.loader)
-
-        return None
-
-    def invalidate_caches(self) -> None:
-        """Invalidate mocked modules on sys.modules."""
-        for modname in self.mocked_modules:
-            sys.modules.pop(modname, None)
-
-
-@contextlib.contextmanager
-def mock(modnames: list[str]) -> Generator[None, None, None]:
-    """Insert mock modules during context::
-
-        with mock(['target.module.name']):
-            # mock modules are enabled here
-            ...
-    """
-    try:
-        finder = MockFinder(modnames)
-        sys.meta_path.insert(0, finder)
-        yield
-    finally:
-        sys.meta_path.remove(finder)
-        finder.invalidate_caches()
-
-
-def ismockmodule(subject: Any) -> bool:
-    """Check if the object is a mocked module."""
-    return isinstance(subject, _MockModule)
-
-
-def ismock(subject: Any) -> bool:
-    """Check if the object is mocked."""
-    # check the object has '__sphinx_mock__' attribute
-    try:
-        if safe_getattr(subject, '__sphinx_mock__', None) is None:
-            return False
-    except AttributeError:
-        return False
-
-    # check the object is mocked module
-    if isinstance(subject, _MockModule):
-        return True
-
-    # check the object is bound method
-    if isinstance(subject, MethodType) and isboundmethod(subject):
-        tmp_subject = subject.__func__
-    else:
-        tmp_subject = subject
-
-    try:
-        # check the object is mocked object
-        __mro__ = safe_getattr(type(tmp_subject), '__mro__', [])
-        if len(__mro__) > 2 and __mro__[-2] is _MockObject:
-            # A mocked object has a MRO that ends with (..., _MockObject, object).
-            return True
-    except AttributeError:
-        pass
-
-    return False
-
-
-def undecorate(subject: _MockObject) -> Any:
-    """Unwrap mock if *subject* is decorated by mocked object.
-
-    If not decorated, returns given *subject* itself.
-    """
-    if ismock(subject) and subject.__sphinx_decorator_args__:
-        return subject.__sphinx_decorator_args__[0]
-    else:
-        return subject