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/doctest.py

@@ -1,561 +0,0 @@
-"""Mimic doctest in Sphinx.
-
-The extension automatically execute code snippets and checks their results.
-"""
-
-from __future__ import annotations
-
-import doctest
-import re
-import sys
-import time
-from io import StringIO
-from os import path
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Sequence
-
-from docutils import nodes
-from docutils.nodes import Element, Node, TextElement
-from docutils.parsers.rst import directives
-from packaging.specifiers import InvalidSpecifier, SpecifierSet
-from packaging.version import Version
-
-import sphinx
-from sphinx.builders import Builder
-from sphinx.locale import __
-from sphinx.util import logging
-from sphinx.util.console import bold  # type: ignore
-from sphinx.util.docutils import SphinxDirective
-from sphinx.util.osutil import relpath
-from sphinx.util.typing import OptionSpec
-
-if TYPE_CHECKING:
-    from sphinx.application import Sphinx
-
-
-logger = logging.getLogger(__name__)
-
-blankline_re = re.compile(r'^\s*<BLANKLINE>', re.MULTILINE)
-doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE)
-
-
-def is_allowed_version(spec: str, version: str) -> bool:
-    """Check `spec` satisfies `version` or not.
-
-    This obeys PEP-440 specifiers:
-    https://peps.python.org/pep-0440/#version-specifiers
-
-    Some examples:
-
-        >>> is_allowed_version('<=3.5', '3.3')
-        True
-        >>> is_allowed_version('<=3.2', '3.3')
-        False
-        >>> is_allowed_version('>3.2, <4.0', '3.3')
-        True
-    """
-    return Version(version) in SpecifierSet(spec)
-
-
-# set up the necessary directives
-
-class TestDirective(SphinxDirective):
-    """
-    Base class for doctest-related directives.
-    """
-
-    has_content = True
-    required_arguments = 0
-    optional_arguments = 1
-    final_argument_whitespace = True
-
-    def run(self) -> list[Node]:
-        # use ordinary docutils nodes for test code: they get special attributes
-        # so that our builder recognizes them, and the other builders are happy.
-        code = '\n'.join(self.content)
-        test = None
-        if self.name == 'doctest':
-            if '<BLANKLINE>' in code:
-                # convert <BLANKLINE>s to ordinary blank lines for presentation
-                test = code
-                code = blankline_re.sub('', code)
-            if doctestopt_re.search(code) and 'no-trim-doctest-flags' not in self.options:
-                if not test:
-                    test = code
-                code = doctestopt_re.sub('', code)
-        nodetype: type[TextElement] = nodes.literal_block
-        if self.name in ('testsetup', 'testcleanup') or 'hide' in self.options:
-            nodetype = nodes.comment
-        if self.arguments:
-            groups = [x.strip() for x in self.arguments[0].split(',')]
-        else:
-            groups = ['default']
-        node = nodetype(code, code, testnodetype=self.name, groups=groups)
-        self.set_source_info(node)
-        if test is not None:
-            # only save if it differs from code
-            node['test'] = test
-        if self.name == 'doctest':
-            node['language'] = 'pycon'
-        elif self.name == 'testcode':
-            node['language'] = 'python'
-        elif self.name == 'testoutput':
-            # don't try to highlight output
-            node['language'] = 'none'
-        node['options'] = {}
-        if self.name in ('doctest', 'testoutput') and 'options' in self.options:
-            # parse doctest-like output comparison flags
-            option_strings = self.options['options'].replace(',', ' ').split()
-            for option in option_strings:
-                prefix, option_name = option[0], option[1:]
-                if prefix not in '+-':
-                    self.state.document.reporter.warning(
-                        __("missing '+' or '-' in '%s' option.") % option,
-                        line=self.lineno)
-                    continue
-                if option_name not in doctest.OPTIONFLAGS_BY_NAME:
-                    self.state.document.reporter.warning(
-                        __("'%s' is not a valid option.") % option_name,
-                        line=self.lineno)
-                    continue
-                flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]]
-                node['options'][flag] = (option[0] == '+')
-        if self.name == 'doctest' and 'pyversion' in self.options:
-            try:
-                spec = self.options['pyversion']
-                python_version = '.'.join([str(v) for v in sys.version_info[:3]])
-                if not is_allowed_version(spec, python_version):
-                    flag = doctest.OPTIONFLAGS_BY_NAME['SKIP']
-                    node['options'][flag] = True  # Skip the test
-            except InvalidSpecifier:
-                self.state.document.reporter.warning(
-                    __("'%s' is not a valid pyversion option") % spec,
-                    line=self.lineno)
-        if 'skipif' in self.options:
-            node['skipif'] = self.options['skipif']
-        if 'trim-doctest-flags' in self.options:
-            node['trim_flags'] = True
-        elif 'no-trim-doctest-flags' in self.options:
-            node['trim_flags'] = False
-        return [node]
-
-
-class TestsetupDirective(TestDirective):
-    option_spec: OptionSpec = {
-        'skipif': directives.unchanged_required
-    }
-
-
-class TestcleanupDirective(TestDirective):
-    option_spec: OptionSpec = {
-        'skipif': directives.unchanged_required
-    }
-
-
-class DoctestDirective(TestDirective):
-    option_spec: OptionSpec = {
-        'hide': directives.flag,
-        'no-trim-doctest-flags': directives.flag,
-        'options': directives.unchanged,
-        'pyversion': directives.unchanged_required,
-        'skipif': directives.unchanged_required,
-        'trim-doctest-flags': directives.flag,
-    }
-
-
-class TestcodeDirective(TestDirective):
-    option_spec: OptionSpec = {
-        'hide': directives.flag,
-        'no-trim-doctest-flags': directives.flag,
-        'pyversion': directives.unchanged_required,
-        'skipif': directives.unchanged_required,
-        'trim-doctest-flags': directives.flag,
-    }
-
-
-class TestoutputDirective(TestDirective):
-    option_spec: OptionSpec = {
-        'hide': directives.flag,
-        'no-trim-doctest-flags': directives.flag,
-        'options': directives.unchanged,
-        'pyversion': directives.unchanged_required,
-        'skipif': directives.unchanged_required,
-        'trim-doctest-flags': directives.flag,
-    }
-
-
-parser = doctest.DocTestParser()
-
-
-# helper classes
-
-class TestGroup:
-    def __init__(self, name: str) -> None:
-        self.name = name
-        self.setup: list[TestCode] = []
-        self.tests: list[list[TestCode]] = []
-        self.cleanup: list[TestCode] = []
-
-    def add_code(self, code: TestCode, prepend: bool = False) -> None:
-        if code.type == 'testsetup':
-            if prepend:
-                self.setup.insert(0, code)
-            else:
-                self.setup.append(code)
-        elif code.type == 'testcleanup':
-            self.cleanup.append(code)
-        elif code.type == 'doctest':
-            self.tests.append([code])
-        elif code.type == 'testcode':
-            self.tests.append([code, None])
-        elif code.type == 'testoutput':
-            if self.tests and len(self.tests[-1]) == 2:
-                self.tests[-1][1] = code
-        else:
-            raise RuntimeError(__('invalid TestCode type'))
-
-    def __repr__(self) -> str:
-        return (f'TestGroup(name={self.name!r}, setup={self.setup!r}, '
-                f'cleanup={self.cleanup!r}, tests={self.tests!r})')
-
-
-class TestCode:
-    def __init__(self, code: str, type: str, filename: str,
-                 lineno: int, options: dict | None = None) -> None:
-        self.code = code
-        self.type = type
-        self.filename = filename
-        self.lineno = lineno
-        self.options = options or {}
-
-    def __repr__(self) -> str:
-        return (f'TestCode({self.code!r}, {self.type!r}, filename={self.filename!r}, '
-                f'lineno={self.lineno!r}, options={self.options!r})')
-
-
-class SphinxDocTestRunner(doctest.DocTestRunner):
-    def summarize(self, out: Callable, verbose: bool = None  # type: ignore
-                  ) -> tuple[int, int]:
-        string_io = StringIO()
-        old_stdout = sys.stdout
-        sys.stdout = string_io
-        try:
-            res = super().summarize(verbose)
-        finally:
-            sys.stdout = old_stdout
-        out(string_io.getvalue())
-        return res
-
-    def _DocTestRunner__patched_linecache_getlines(self, filename: str,
-                                                   module_globals: Any = None) -> Any:
-        # this is overridden from DocTestRunner adding the try-except below
-        m = self._DocTestRunner__LINECACHE_FILENAME_RE.match(filename)  # type: ignore
-        if m and m.group('name') == self.test.name:
-            try:
-                example = self.test.examples[int(m.group('examplenum'))]
-            # because we compile multiple doctest blocks with the same name
-            # (viz. the group name) this might, for outer stack frames in a
-            # traceback, get the wrong test which might not have enough examples
-            except IndexError:
-                pass
-            else:
-                return example.source.splitlines(True)
-        return self.save_linecache_getlines(filename, module_globals)  # type: ignore
-
-
-# the new builder -- use sphinx-build.py -b doctest to run
-
-class DocTestBuilder(Builder):
-    """
-    Runs test snippets in the documentation.
-    """
-    name = 'doctest'
-    epilog = __('Testing of doctests in the sources finished, look at the '
-                'results in %(outdir)s/output.txt.')
-
-    def init(self) -> None:
-        # default options
-        self.opt = self.config.doctest_default_flags
-
-        # HACK HACK HACK
-        # doctest compiles its snippets with type 'single'. That is nice
-        # for doctest examples but unusable for multi-statement code such
-        # as setup code -- to be able to use doctest error reporting with
-        # that code nevertheless, we monkey-patch the "compile" it uses.
-        doctest.compile = self.compile  # type: ignore
-
-        sys.path[0:0] = self.config.doctest_path
-
-        self.type = 'single'
-
-        self.total_failures = 0
-        self.total_tries = 0
-        self.setup_failures = 0
-        self.setup_tries = 0
-        self.cleanup_failures = 0
-        self.cleanup_tries = 0
-
-        date = time.strftime('%Y-%m-%d %H:%M:%S')
-
-        self.outfile = open(path.join(self.outdir, 'output.txt'), 'w', encoding='utf-8')
-        self.outfile.write(('Results of doctest builder run on %s\n'
-                            '==================================%s\n') %
-                           (date, '=' * len(date)))
-
-    def _out(self, text: str) -> None:
-        logger.info(text, nonl=True)
-        self.outfile.write(text)
-
-    def _warn_out(self, text: str) -> None:
-        if self.app.quiet or self.app.warningiserror:
-            logger.warning(text)
-        else:
-            logger.info(text, nonl=True)
-        self.outfile.write(text)
-
-    def get_target_uri(self, docname: str, typ: str | None = None) -> str:
-        return ''
-
-    def get_outdated_docs(self) -> set[str]:
-        return self.env.found_docs
-
-    def finish(self) -> None:
-        # write executive summary
-        def s(v: int) -> str:
-            return 's' if v != 1 else ''
-        repl = (self.total_tries, s(self.total_tries),
-                self.total_failures, s(self.total_failures),
-                self.setup_failures, s(self.setup_failures),
-                self.cleanup_failures, s(self.cleanup_failures))
-        self._out('''
-Doctest summary
-===============
-%5d test%s
-%5d failure%s in tests
-%5d failure%s in setup code
-%5d failure%s in cleanup code
-''' % repl)
-        self.outfile.close()
-
-        if self.total_failures or self.setup_failures or self.cleanup_failures:
-            self.app.statuscode = 1
-
-    def write(self, build_docnames: Iterable[str], updated_docnames: Sequence[str],
-              method: str = 'update') -> None:
-        if build_docnames is None:
-            build_docnames = sorted(self.env.all_docs)
-
-        logger.info(bold('running tests...'))
-        for docname in build_docnames:
-            # no need to resolve the doctree
-            doctree = self.env.get_doctree(docname)
-            self.test_doc(docname, doctree)
-
-    def get_filename_for_node(self, node: Node, docname: str) -> str:
-        """Try to get the file which actually contains the doctest, not the
-        filename of the document it's included in."""
-        try:
-            filename = relpath(node.source, self.env.srcdir)\
-                .rsplit(':docstring of ', maxsplit=1)[0]
-        except Exception:
-            filename = self.env.doc2path(docname, False)
-        return filename
-
-    @staticmethod
-    def get_line_number(node: Node) -> int | None:
-        """Get the real line number or admit we don't know."""
-        # TODO:  Work out how to store or calculate real (file-relative)
-        #       line numbers for doctest blocks in docstrings.
-        if ':docstring of ' in path.basename(node.source or ''):
-            # The line number is given relative to the stripped docstring,
-            # not the file.  This is correct where it is set, in
-            # `docutils.nodes.Node.setup_child`, but Sphinx should report
-            # relative to the file, not the docstring.
-            return None
-        if node.line is not None:
-            # TODO: find the root cause of this off by one error.
-            return node.line - 1
-        return None
-
-    def skipped(self, node: Element) -> bool:
-        if 'skipif' not in node:
-            return False
-        else:
-            condition = node['skipif']
-            context: dict[str, Any] = {}
-            if self.config.doctest_global_setup:
-                exec(self.config.doctest_global_setup, context)  # NoQA: S102
-            should_skip = eval(condition, context)  # NoQA: PGH001
-            if self.config.doctest_global_cleanup:
-                exec(self.config.doctest_global_cleanup, context)  # NoQA: S102
-            return should_skip
-
-    def test_doc(self, docname: str, doctree: Node) -> None:
-        groups: dict[str, TestGroup] = {}
-        add_to_all_groups = []
-        self.setup_runner = SphinxDocTestRunner(verbose=False,
-                                                optionflags=self.opt)
-        self.test_runner = SphinxDocTestRunner(verbose=False,
-                                               optionflags=self.opt)
-        self.cleanup_runner = SphinxDocTestRunner(verbose=False,
-                                                  optionflags=self.opt)
-
-        self.test_runner._fakeout = self.setup_runner._fakeout  # type: ignore
-        self.cleanup_runner._fakeout = self.setup_runner._fakeout  # type: ignore
-
-        if self.config.doctest_test_doctest_blocks:
-            def condition(node: Node) -> bool:
-                return (isinstance(node, (nodes.literal_block, nodes.comment)) and
-                        'testnodetype' in node) or \
-                    isinstance(node, nodes.doctest_block)
-        else:
-            def condition(node: Node) -> bool:
-                return isinstance(node, (nodes.literal_block, nodes.comment)) \
-                    and 'testnodetype' in node
-        for node in doctree.findall(condition):  # type: Element
-            if self.skipped(node):
-                continue
-
-            source = node['test'] if 'test' in node else node.astext()
-            filename = self.get_filename_for_node(node, docname)
-            line_number = self.get_line_number(node)
-            if not source:
-                logger.warning(__('no code/output in %s block at %s:%s'),
-                               node.get('testnodetype', 'doctest'),
-                               filename, line_number)
-            code = TestCode(source, type=node.get('testnodetype', 'doctest'),
-                            filename=filename, lineno=line_number,
-                            options=node.get('options'))
-            node_groups = node.get('groups', ['default'])
-            if '*' in node_groups:
-                add_to_all_groups.append(code)
-                continue
-            for groupname in node_groups:
-                if groupname not in groups:
-                    groups[groupname] = TestGroup(groupname)
-                groups[groupname].add_code(code)
-        for code in add_to_all_groups:
-            for group in groups.values():
-                group.add_code(code)
-        if self.config.doctest_global_setup:
-            code = TestCode(self.config.doctest_global_setup,
-                            'testsetup', filename=None, lineno=0)
-            for group in groups.values():
-                group.add_code(code, prepend=True)
-        if self.config.doctest_global_cleanup:
-            code = TestCode(self.config.doctest_global_cleanup,
-                            'testcleanup', filename=None, lineno=0)
-            for group in groups.values():
-                group.add_code(code)
-        if not groups:
-            return
-
-        self._out('\nDocument: %s\n----------%s\n' %
-                  (docname, '-' * len(docname)))
-        for group in groups.values():
-            self.test_group(group)
-        # Separately count results from setup code
-        res_f, res_t = self.setup_runner.summarize(self._out, verbose=False)
-        self.setup_failures += res_f
-        self.setup_tries += res_t
-        if self.test_runner.tries:
-            res_f, res_t = self.test_runner.summarize(self._out, verbose=True)
-            self.total_failures += res_f
-            self.total_tries += res_t
-        if self.cleanup_runner.tries:
-            res_f, res_t = self.cleanup_runner.summarize(self._out,
-                                                         verbose=True)
-            self.cleanup_failures += res_f
-            self.cleanup_tries += res_t
-
-    def compile(self, code: str, name: str, type: str, flags: Any, dont_inherit: bool) -> Any:
-        return compile(code, name, self.type, flags, dont_inherit)
-
-    def test_group(self, group: TestGroup) -> None:
-        ns: dict = {}
-
-        def run_setup_cleanup(runner: Any, testcodes: list[TestCode], what: Any) -> bool:
-            examples = []
-            for testcode in testcodes:
-                example = doctest.Example(testcode.code, '', lineno=testcode.lineno)
-                examples.append(example)
-            if not examples:
-                return True
-            # simulate a doctest with the code
-            sim_doctest = doctest.DocTest(examples, {},
-                                          f'{group.name} ({what} code)',
-                                          testcodes[0].filename, 0, None)
-            sim_doctest.globs = ns
-            old_f = runner.failures
-            self.type = 'exec'  # the snippet may contain multiple statements
-            runner.run(sim_doctest, out=self._warn_out, clear_globs=False)
-            if runner.failures > old_f:
-                return False
-            return True
-
-        # run the setup code
-        if not run_setup_cleanup(self.setup_runner, group.setup, 'setup'):
-            # if setup failed, don't run the group
-            return
-
-        # run the tests
-        for code in group.tests:
-            if len(code) == 1:
-                # ordinary doctests (code/output interleaved)
-                try:
-                    test = parser.get_doctest(code[0].code, {}, group.name,
-                                              code[0].filename, code[0].lineno)
-                except Exception:
-                    logger.warning(__('ignoring invalid doctest code: %r'), code[0].code,
-                                   location=(code[0].filename, code[0].lineno))
-                    continue
-                if not test.examples:
-                    continue
-                for example in test.examples:
-                    # apply directive's comparison options
-                    new_opt = code[0].options.copy()
-                    new_opt.update(example.options)
-                    example.options = new_opt
-                self.type = 'single'  # as for ordinary doctests
-            else:
-                # testcode and output separate
-                output = code[1].code if code[1] else ''
-                options = code[1].options if code[1] else {}
-                # disable <BLANKLINE> processing as it is not needed
-                options[doctest.DONT_ACCEPT_BLANKLINE] = True
-                # find out if we're testing an exception
-                m = parser._EXCEPTION_RE.match(output)  # type: ignore
-                if m:
-                    exc_msg = m.group('msg')
-                else:
-                    exc_msg = None
-                example = doctest.Example(code[0].code, output, exc_msg=exc_msg,
-                                          lineno=code[0].lineno, options=options)
-                test = doctest.DocTest([example], {}, group.name,
-                                       code[0].filename, code[0].lineno, None)
-                self.type = 'exec'  # multiple statements again
-            # DocTest.__init__ copies the globs namespace, which we don't want
-            test.globs = ns
-            # also don't clear the globs namespace after running the doctest
-            self.test_runner.run(test, out=self._warn_out, clear_globs=False)
-
-        # run the cleanup
-        run_setup_cleanup(self.cleanup_runner, group.cleanup, 'cleanup')
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_directive('testsetup', TestsetupDirective)
-    app.add_directive('testcleanup', TestcleanupDirective)
-    app.add_directive('doctest', DoctestDirective)
-    app.add_directive('testcode', TestcodeDirective)
-    app.add_directive('testoutput', TestoutputDirective)
-    app.add_builder(DocTestBuilder)
-    # this config value adds to sys.path
-    app.add_config_value('doctest_path', [], False)
-    app.add_config_value('doctest_test_doctest_blocks', 'default', False)
-    app.add_config_value('doctest_global_setup', '', False)
-    app.add_config_value('doctest_global_cleanup', '', False)
-    app.add_config_value(
-        'doctest_default_flags',
-        doctest.DONT_ACCEPT_TRUE_FOR_1 | doctest.ELLIPSIS | doctest.IGNORE_EXCEPTION_DETAIL,
-        False)
-    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

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

@@ -1,90 +0,0 @@
-"""Measure durations of Sphinx processing."""
-
-from __future__ import annotations
-
-from datetime import datetime, timedelta
-from itertools import islice
-from operator import itemgetter
-from typing import Any, cast
-
-from docutils import nodes
-
-import sphinx
-from sphinx.application import Sphinx
-from sphinx.domains import Domain
-from sphinx.locale import __
-from sphinx.util import logging
-
-logger = logging.getLogger(__name__)
-
-
-class DurationDomain(Domain):
-    """A domain for durations of Sphinx processing."""
-    name = 'duration'
-
-    @property
-    def reading_durations(self) -> dict[str, timedelta]:
-        return self.data.setdefault('reading_durations', {})
-
-    def note_reading_duration(self, duration: timedelta) -> None:
-        self.reading_durations[self.env.docname] = duration
-
-    def clear(self) -> None:
-        self.reading_durations.clear()
-
-    def clear_doc(self, docname: str) -> None:
-        self.reading_durations.pop(docname, None)
-
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, timedelta]) -> None:
-        for docname, duration in otherdata.items():
-            if docname in docnames:
-                self.reading_durations[docname] = duration
-
-
-def on_builder_inited(app: Sphinx) -> None:
-    """Initialize DurationDomain on bootstrap.
-
-    This clears results of last build.
-    """
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
-    domain.clear()
-
-
-def on_source_read(app: Sphinx, docname: str, content: list[str]) -> None:
-    """Start to measure reading duration."""
-    app.env.temp_data['started_at'] = datetime.now()
-
-
-def on_doctree_read(app: Sphinx, doctree: nodes.document) -> None:
-    """Record a reading duration."""
-    started_at = app.env.temp_data.get('started_at')
-    duration = datetime.now() - started_at
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
-    domain.note_reading_duration(duration)
-
-
-def on_build_finished(app: Sphinx, error: Exception) -> None:
-    """Display duration ranking on current build."""
-    domain = cast(DurationDomain, app.env.get_domain('duration'))
-    durations = sorted(domain.reading_durations.items(), key=itemgetter(1), reverse=True)
-    if not durations:
-        return
-
-    logger.info('')
-    logger.info(__('====================== slowest reading durations ======================='))
-    for docname, d in islice(durations, 5):
-        logger.info('%d.%03d %s', d.seconds, d.microseconds / 1000, docname)
-
-
-def setup(app: Sphinx) -> dict[str, Any]:
-    app.add_domain(DurationDomain)
-    app.connect('builder-inited', on_builder_inited)
-    app.connect('source-read', on_source_read)
-    app.connect('doctree-read', on_doctree_read)
-    app.connect('build-finished', on_build_finished)
-
-    return {
-        'version': sphinx.__display_version__,
-        'parallel_read_safe': True,
-        'parallel_write_safe': True,
-    }