py2docfx 0.1.11.dev1869610__py3-none-any.whl → 0.1.11.dev1872139__py3-none-any.whl

py2docfx/venv/1/Lib/site-packages/sphinx/testing/path.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import builtins
+import os
+import shutil
+import sys
+from typing import IO, Any, Callable
+
+FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding()
+
+
+def getumask() -> int:
+    """Get current umask value"""
+    umask = os.umask(0)  # Note: Change umask value temporarily to obtain it
+    os.umask(umask)
+
+    return umask
+
+
+UMASK = getumask()
+
+
+class path(str):
+    """
+    Represents a path which behaves like a string.
+    """
+
+    @property
+    def parent(self) -> path:
+        """
+        The name of the directory the file or directory is in.
+        """
+        return self.__class__(os.path.dirname(self))
+
+    def basename(self) -> str:
+        return os.path.basename(self)
+
+    def abspath(self) -> path:
+        """
+        Returns the absolute path.
+        """
+        return self.__class__(os.path.abspath(self))
+
+    def isabs(self) -> bool:
+        """
+        Returns ``True`` if the path is absolute.
+        """
+        return os.path.isabs(self)
+
+    def isdir(self) -> bool:
+        """
+        Returns ``True`` if the path is a directory.
+        """
+        return os.path.isdir(self)
+
+    def isfile(self) -> bool:
+        """
+        Returns ``True`` if the path is a file.
+        """
+        return os.path.isfile(self)
+
+    def islink(self) -> bool:
+        """
+        Returns ``True`` if the path is a symbolic link.
+        """
+        return os.path.islink(self)
+
+    def ismount(self) -> bool:
+        """
+        Returns ``True`` if the path is a mount point.
+        """
+        return os.path.ismount(self)
+
+    def rmtree(self, ignore_errors: bool = False, onerror: Callable | None = None) -> None:
+        """
+        Removes the file or directory and any files or directories it may
+        contain.
+
+        :param ignore_errors:
+            If ``True`` errors are silently ignored, otherwise an exception
+            is raised in case an error occurs.
+
+        :param onerror:
+            A callback which gets called with the arguments `func`, `path` and
+            `exc_info`. `func` is one of :func:`os.listdir`, :func:`os.remove`
+            or :func:`os.rmdir`. `path` is the argument to the function which
+            caused it to fail and `exc_info` is a tuple as returned by
+            :func:`sys.exc_info`.
+        """
+        shutil.rmtree(self, ignore_errors=ignore_errors, onerror=onerror)
+
+    def copytree(self, destination: str, symlinks: bool = False) -> None:
+        """
+        Recursively copy a directory to the given `destination`. If the given
+        `destination` does not exist it will be created.
+
+        :param symlinks:
+            If ``True`` symbolic links in the source tree result in symbolic
+            links in the destination tree otherwise the contents of the files
+            pointed to by the symbolic links are copied.
+        """
+        shutil.copytree(self, destination, symlinks=symlinks)
+        if os.environ.get('SPHINX_READONLY_TESTDIR'):
+            # If source tree is marked read-only (e.g. because it is on a read-only
+            # filesystem), `shutil.copytree` will mark the destination as read-only
+            # as well.  To avoid failures when adding additional files/directories
+            # to the destination tree, ensure destination directories are not marked
+            # read-only.
+            for root, _dirs, files in os.walk(destination):
+                os.chmod(root, 0o755 & ~UMASK)
+                for name in files:
+                    os.chmod(os.path.join(root, name), 0o644 & ~UMASK)
+
+    def movetree(self, destination: str) -> None:
+        """
+        Recursively move the file or directory to the given `destination`
+        similar to the  Unix "mv" command.
+
+        If the `destination` is a file it may be overwritten depending on the
+        :func:`os.rename` semantics.
+        """
+        shutil.move(self, destination)
+
+    move = movetree
+
+    def unlink(self) -> None:
+        """
+        Removes a file.
+        """
+        os.unlink(self)
+
+    def stat(self) -> Any:
+        """
+        Returns a stat of the file.
+        """
+        return os.stat(self)
+
+    def utime(self, arg: Any) -> None:
+        os.utime(self, arg)
+
+    def open(self, mode: str = 'r', **kwargs: Any) -> IO:
+        return open(self, mode, **kwargs)
+
+    def write_text(self, text: str, encoding: str = 'utf-8', **kwargs: Any) -> None:
+        """
+        Writes the given `text` to the file.
+        """
+        with open(self, 'w', encoding=encoding, **kwargs) as f:
+            f.write(text)
+
+    def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
+        """
+        Returns the text in the file.
+        """
+        with open(self, encoding=encoding, **kwargs) as f:
+            return f.read()
+
+    def read_bytes(self) -> builtins.bytes:
+        """
+        Returns the bytes in the file.
+        """
+        with open(self, mode='rb') as f:
+            return f.read()
+
+    def write_bytes(self, bytes: str, append: bool = False) -> None:
+        """
+        Writes the given `bytes` to the file.
+
+        :param append:
+            If ``True`` given `bytes` are added at the end of the file.
+        """
+        if append:
+            mode = 'ab'
+        else:
+            mode = 'wb'
+        with open(self, mode=mode) as f:
+            f.write(bytes)
+
+    def exists(self) -> bool:
+        """
+        Returns ``True`` if the path exist.
+        """
+        return os.path.exists(self)
+
+    def lexists(self) -> bool:
+        """
+        Returns ``True`` if the path exists unless it is a broken symbolic
+        link.
+        """
+        return os.path.lexists(self)
+
+    def makedirs(self, mode: int = 0o777, exist_ok: bool = False) -> None:
+        """
+        Recursively create directories.
+        """
+        os.makedirs(self, mode, exist_ok=exist_ok)
+
+    def joinpath(self, *args: Any) -> path:
+        """
+        Joins the path with the argument given and returns the result.
+        """
+        return self.__class__(os.path.join(self, *map(self.__class__, args)))
+
+    def listdir(self) -> list[str]:
+        return os.listdir(self)
+
+    __div__ = __truediv__ = joinpath
+
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}({super().__repr__()})'

py2docfx/venv/1/Lib/site-packages/sphinx/testing/restructuredtext.py

@@ -0,0 +1,27 @@
+from os import path
+
+from docutils import nodes
+from docutils.core import publish_doctree
+
+from sphinx.application import Sphinx
+from sphinx.io import SphinxStandaloneReader
+from sphinx.parsers import RSTParser
+from sphinx.util.docutils import sphinx_domains
+
+
+def parse(app: Sphinx, text: str, docname: str = 'index') -> nodes.document:
+    """Parse a string as reStructuredText with Sphinx application."""
+    try:
+        app.env.temp_data['docname'] = docname
+        reader = SphinxStandaloneReader()
+        reader.setup(app)
+        parser = RSTParser()
+        parser.set_application(app)
+        with sphinx_domains(app.env):
+            return publish_doctree(text, path.join(app.srcdir, docname + '.rst'),
+                                   reader=reader,
+                                   parser=parser,
+                                   settings_overrides={'env': app.env,
+                                                       'gettext_compact': True})
+    finally:
+        app.env.temp_data.pop('docname', None)

py2docfx/venv/1/Lib/site-packages/sphinx/testing/util.py

@@ -0,0 +1,206 @@
+"""Sphinx test suite utilities"""
+from __future__ import annotations
+
+import functools
+import os
+import re
+import sys
+import warnings
+from io import StringIO
+from typing import IO, Any, Generator
+from xml.etree import ElementTree
+
+from docutils import nodes
+from docutils.nodes import Node
+from docutils.parsers.rst import directives, roles
+
+from sphinx import application, locale
+from sphinx.pycode import ModuleAnalyzer
+from sphinx.testing.path import path
+from sphinx.util.osutil import relpath
+
+__all__ = [
+    'Struct', 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding',
+]
+
+
+def assert_re_search(regex: re.Pattern, text: str, flags: int = 0) -> None:
+    if not re.search(regex, text, flags):
+        raise AssertionError(f'{regex!r} did not match {text!r}')
+
+
+def assert_not_re_search(regex: re.Pattern, text: str, flags: int = 0) -> None:
+    if re.search(regex, text, flags):
+        raise AssertionError(f'{regex!r} did match {text!r}')
+
+
+def assert_startswith(thing: str, prefix: str) -> None:
+    if not thing.startswith(prefix):
+        raise AssertionError(f'{thing!r} does not start with {prefix!r}')
+
+
+def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) -> None:
+    if cls:
+        if isinstance(cls, list):
+            assert_node(node, cls[0], xpath=xpath, **kwargs)
+            if cls[1:]:
+                if isinstance(cls[1], tuple):
+                    assert_node(node, cls[1], xpath=xpath, **kwargs)
+                else:
+                    assert isinstance(node, nodes.Element), \
+                        'The node%s does not have any children' % xpath
+                    assert len(node) == 1, \
+                        'The node%s has %d child nodes, not one' % (xpath, len(node))
+                    assert_node(node[0], cls[1:], xpath=xpath + "[0]", **kwargs)
+        elif isinstance(cls, tuple):
+            assert isinstance(node, (list, nodes.Element)), \
+                'The node%s does not have any items' % xpath
+            assert len(node) == len(cls), \
+                'The node%s has %d child nodes, not %r' % (xpath, len(node), len(cls))
+            for i, nodecls in enumerate(cls):
+                path = xpath + "[%d]" % i
+                assert_node(node[i], nodecls, xpath=path, **kwargs)
+        elif isinstance(cls, str):
+            assert node == cls, f'The node {xpath!r} is not {cls!r}: {node!r}'
+        else:
+            assert isinstance(node, cls), \
+                f'The node{xpath} is not subclass of {cls!r}: {node!r}'
+
+    if kwargs:
+        assert isinstance(node, nodes.Element), \
+            'The node%s does not have any attributes' % xpath
+
+        for key, value in kwargs.items():
+            assert key in node, \
+                f'The node{xpath} does not have {key!r} attribute: {node!r}'
+            assert node[key] == value, \
+                f'The node{xpath}[{key}] is not {value!r}: {node[key]!r}'
+
+
+def etree_parse(path: str) -> Any:
+    with warnings.catch_warnings(record=False):
+        warnings.filterwarnings("ignore", category=DeprecationWarning)
+        return ElementTree.parse(path)
+
+
+class Struct:
+    def __init__(self, **kwargs: Any) -> None:
+        self.__dict__.update(kwargs)
+
+
+class SphinxTestApp(application.Sphinx):
+    """
+    A subclass of :class:`Sphinx` that runs on the test root, with some
+    better default values for the initialization parameters.
+    """
+    _status: StringIO
+    _warning: StringIO
+
+    def __init__(
+        self,
+        buildername: str = 'html',
+        srcdir: path | None = None,
+        builddir: path | None = None,
+        freshenv: bool = False,
+        confoverrides: dict | None = None,
+        status: IO | None = None,
+        warning: IO | None = None,
+        tags: list[str] | None = None,
+        docutilsconf: str | None = None,
+        parallel: int = 0
+    ) -> None:
+
+        if docutilsconf is not None:
+            (srcdir / 'docutils.conf').write_text(docutilsconf)
+
+        if builddir is None:
+            builddir = srcdir / '_build'
+
+        confdir = srcdir
+        outdir = builddir.joinpath(buildername)
+        outdir.makedirs(exist_ok=True)
+        doctreedir = builddir.joinpath('doctrees')
+        doctreedir.makedirs(exist_ok=True)
+        if confoverrides is None:
+            confoverrides = {}
+        warningiserror = False
+
+        self._saved_path = sys.path[:]
+        self._saved_directives = directives._directives.copy()  # type: ignore
+        self._saved_roles = roles._roles.copy()  # type: ignore
+
+        self._saved_nodeclasses = {v for v in dir(nodes.GenericNodeVisitor)
+                                   if v.startswith('visit_')}
+
+        try:
+            super().__init__(srcdir, confdir, outdir, doctreedir,
+                             buildername, confoverrides, status, warning,
+                             freshenv, warningiserror, tags, parallel=parallel)
+        except Exception:
+            self.cleanup()
+            raise
+
+    def cleanup(self, doctrees: bool = False) -> None:
+        ModuleAnalyzer.cache.clear()
+        locale.translators.clear()
+        sys.path[:] = self._saved_path
+        sys.modules.pop('autodoc_fodder', None)
+        directives._directives = self._saved_directives  # type: ignore
+        roles._roles = self._saved_roles  # type: ignore
+        for method in dir(nodes.GenericNodeVisitor):
+            if method.startswith('visit_') and \
+               method not in self._saved_nodeclasses:
+                delattr(nodes.GenericNodeVisitor, 'visit_' + method[6:])
+                delattr(nodes.GenericNodeVisitor, 'depart_' + method[6:])
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__} buildername={self.builder.name!r}>'
+
+    def build(self, force_all: bool = False, filenames: list[str] | None = None) -> None:
+        self.env._pickled_doctree_cache.clear()
+        super().build(force_all, filenames)
+
+
+class SphinxTestAppWrapperForSkipBuilding:
+    """
+    This class is a wrapper for SphinxTestApp to speed up the test by skipping
+    `app.build` process if it is already built and there is even one output
+    file.
+    """
+
+    def __init__(self, app_: SphinxTestApp) -> None:
+        self.app = app_
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.app, name)
+
+    def build(self, *args: Any, **kwargs: Any) -> None:
+        if not self.app.outdir.listdir():  # type: ignore
+            # if listdir is empty, do build.
+            self.app.build(*args, **kwargs)
+            # otherwise, we can use built cache
+
+
+_unicode_literals_re = re.compile(r'u(".*?")|u(\'.*?\')')
+
+
+def find_files(root: str, suffix: str | None = None) -> Generator[str, None, None]:
+    for dirpath, _dirs, files in os.walk(root, followlinks=True):
+        dirpath = path(dirpath)
+        for f in [f for f in files if not suffix or f.endswith(suffix)]:
+            fpath = dirpath / f
+            yield relpath(fpath, root)
+
+
+def strip_escseq(text: str) -> str:
+    return re.sub('\x1b.*?m', '', text)
+
+
+def simple_decorator(f):
+    """
+    A simple decorator that does nothing, for tests to use.
+    """
+    @functools.wraps(f)
+    def wrapper(*args, **kwargs):
+        return f(*args, **kwargs)
+    return wrapper

py2docfx/venv/1/Lib/site-packages/sphinx/theming.py

@@ -0,0 +1,230 @@
+"""Theming support for HTML builders."""
+
+from __future__ import annotations
+
+import configparser
+import os
+import shutil
+import tempfile
+from os import path
+from typing import TYPE_CHECKING, Any
+from zipfile import ZipFile
+
+try:  # Python < 3.10 (backport)
+    from importlib_metadata import entry_points
+except ImportError:
+    from importlib.metadata import entry_points
+
+from sphinx import package_dir
+from sphinx.errors import ThemeError
+from sphinx.locale import __
+from sphinx.util import logging
+from sphinx.util.osutil import ensuredir
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+
+logger = logging.getLogger(__name__)
+
+NODEFAULT = object()
+THEMECONF = 'theme.conf'
+
+
+def extract_zip(filename: str, targetdir: str) -> None:
+    """Extract zip file to target directory."""
+    ensuredir(targetdir)
+
+    with ZipFile(filename) as archive:
+        for name in archive.namelist():
+            if name.endswith('/'):
+                continue
+            entry = path.join(targetdir, name)
+            ensuredir(path.dirname(entry))
+            with open(path.join(entry), 'wb') as fp:
+                fp.write(archive.read(name))
+
+
+class Theme:
+    """A Theme is a set of HTML templates and configurations.
+
+    This class supports both theme directory and theme archive (zipped theme)."""
+
+    def __init__(self, name: str, theme_path: str, factory: HTMLThemeFactory) -> None:
+        self.name = name
+        self.base = None
+        self.rootdir = None
+
+        if path.isdir(theme_path):
+            # already a directory, do nothing
+            self.rootdir = None
+            self.themedir = theme_path
+        else:
+            # extract the theme to a temp directory
+            self.rootdir = tempfile.mkdtemp('sxt')
+            self.themedir = path.join(self.rootdir, name)
+            extract_zip(theme_path, self.themedir)
+
+        self.config = configparser.RawConfigParser()
+        self.config.read(path.join(self.themedir, THEMECONF), encoding='utf-8')
+
+        try:
+            inherit = self.config.get('theme', 'inherit')
+        except configparser.NoSectionError as exc:
+            raise ThemeError(__('theme %r doesn\'t have "theme" setting') % name) from exc
+        except configparser.NoOptionError as exc:
+            raise ThemeError(__('theme %r doesn\'t have "inherit" setting') % name) from exc
+
+        if inherit != 'none':
+            try:
+                self.base = factory.create(inherit)
+            except ThemeError as exc:
+                raise ThemeError(__('no theme named %r found, inherited by %r') %
+                                 (inherit, name)) from exc
+
+    def get_theme_dirs(self) -> list[str]:
+        """Return a list of theme directories, beginning with this theme's,
+        then the base theme's, then that one's base theme's, etc.
+        """
+        if self.base is None:
+            return [self.themedir]
+        else:
+            return [self.themedir] + self.base.get_theme_dirs()
+
+    def get_config(self, section: str, name: str, default: Any = NODEFAULT) -> Any:
+        """Return the value for a theme configuration setting, searching the
+        base theme chain.
+        """
+        try:
+            return self.config.get(section, name)
+        except (configparser.NoOptionError, configparser.NoSectionError) as exc:
+            if self.base:
+                return self.base.get_config(section, name, default)
+
+            if default is NODEFAULT:
+                raise ThemeError(__('setting %s.%s occurs in none of the '
+                                    'searched theme configs') % (section, name)) from exc
+            else:
+                return default
+
+    def get_options(self, overrides: dict[str, Any] = {}) -> dict[str, Any]:
+        """Return a dictionary of theme options and their values."""
+        if self.base:
+            options = self.base.get_options()
+        else:
+            options = {}
+
+        try:
+            options.update(self.config.items('options'))
+        except configparser.NoSectionError:
+            pass
+
+        for option, value in overrides.items():
+            if option not in options:
+                logger.warning(__('unsupported theme option %r given') % option)
+            else:
+                options[option] = value
+
+        return options
+
+    def cleanup(self) -> None:
+        """Remove temporary directories."""
+        if self.rootdir:
+            try:
+                shutil.rmtree(self.rootdir)
+            except Exception:
+                pass
+        if self.base:
+            self.base.cleanup()
+
+
+def is_archived_theme(filename: str) -> bool:
+    """Check whether the specified file is an archived theme file or not."""
+    try:
+        with ZipFile(filename) as f:
+            return THEMECONF in f.namelist()
+    except Exception:
+        return False
+
+
+class HTMLThemeFactory:
+    """A factory class for HTML Themes."""
+
+    def __init__(self, app: Sphinx) -> None:
+        self.app = app
+        self.themes = app.registry.html_themes
+        self.load_builtin_themes()
+        if getattr(app.config, 'html_theme_path', None):
+            self.load_additional_themes(app.config.html_theme_path)
+
+    def load_builtin_themes(self) -> None:
+        """Load built-in themes."""
+        themes = self.find_themes(path.join(package_dir, 'themes'))
+        for name, theme in themes.items():
+            self.themes[name] = theme
+
+    def load_additional_themes(self, theme_paths: str) -> None:
+        """Load additional themes placed at specified directories."""
+        for theme_path in theme_paths:
+            abs_theme_path = path.abspath(path.join(self.app.confdir, theme_path))
+            themes = self.find_themes(abs_theme_path)
+            for name, theme in themes.items():
+                self.themes[name] = theme
+
+    def load_extra_theme(self, name: str) -> None:
+        """Try to load a theme with the specified name."""
+        if name == 'alabaster':
+            self.load_alabaster_theme()
+        else:
+            self.load_external_theme(name)
+
+    def load_alabaster_theme(self) -> None:
+        """Load alabaster theme."""
+        import alabaster
+        self.themes['alabaster'] = path.join(alabaster.get_path(), 'alabaster')
+
+    def load_external_theme(self, name: str) -> None:
+        """Try to load a theme using entry_points.
+
+        Sphinx refers to ``sphinx_themes`` entry_points.
+        """
+        # look up for new styled entry_points at first
+        theme_entry_points = entry_points(group='sphinx.html_themes')
+        try:
+            entry_point = theme_entry_points[name]
+            self.app.registry.load_extension(self.app, entry_point.module)
+            self.app.config.post_init_values()
+            return
+        except KeyError:
+            pass
+
+    def find_themes(self, theme_path: str) -> dict[str, str]:
+        """Search themes from specified directory."""
+        themes: dict[str, str] = {}
+        if not path.isdir(theme_path):
+            return themes
+
+        for entry in os.listdir(theme_path):
+            pathname = path.join(theme_path, entry)
+            if path.isfile(pathname) and entry.lower().endswith('.zip'):
+                if is_archived_theme(pathname):
+                    name = entry[:-4]
+                    themes[name] = pathname
+                else:
+                    logger.warning(__('file %r on theme path is not a valid '
+                                      'zipfile or contains no theme'), entry)
+            else:
+                if path.isfile(path.join(pathname, THEMECONF)):
+                    themes[entry] = pathname
+
+        return themes
+
+    def create(self, name: str) -> Theme:
+        """Create an instance of theme."""
+        if name not in self.themes:
+            self.load_extra_theme(name)
+
+        if name not in self.themes:
+            raise ThemeError(__('no theme named %r found (missing theme.conf?)') % name)
+
+        return Theme(name, self.themes[name], factory=self)