usse/scrape/venv/lib/python3.10/site-packages/sphinx/testing/util.py

172 lines
6.2 KiB
Python
Raw Normal View History

2023-12-22 14:26:01 +00:00
"""Sphinx test suite utilities"""
from __future__ import annotations
import contextlib
import os
import re
import sys
import warnings
from typing import IO, TYPE_CHECKING, Any
from xml.etree import ElementTree
from docutils import nodes
from docutils.parsers.rst import directives, roles
from sphinx import application, locale
from sphinx.pycode import ModuleAnalyzer
if TYPE_CHECKING:
from io import StringIO
from pathlib import Path
from docutils.nodes import Node
__all__ = 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding'
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():
if key not in node:
if (key := key.replace('_', '-')) not in node:
msg = f'The node{xpath} does not have {key!r} attribute: {node!r}'
raise AssertionError(msg)
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) # NoQA: S314 # using known data in tests
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:
assert srcdir is not None
self.docutils_conf_path = srcdir / 'docutils.conf'
if docutilsconf is not None:
self.docutils_conf_path.write_text(docutilsconf, encoding='utf8')
if builddir is None:
builddir = srcdir / '_build'
confdir = srcdir
outdir = builddir.joinpath(buildername)
outdir.mkdir(parents=True, exist_ok=True)
doctreedir = builddir.joinpath('doctrees')
doctreedir.mkdir(parents=True, exist_ok=True)
if confoverrides is None:
confoverrides = {}
warningiserror = False
self._saved_path = sys.path[:]
self._saved_directives = directives._directives.copy() # type: ignore[attr-defined]
self._saved_roles = roles._roles.copy() # type: ignore[attr-defined]
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[attr-defined]
roles._roles = self._saved_roles # type: ignore[attr-defined]
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:])
with contextlib.suppress(FileNotFoundError):
os.remove(self.docutils_conf_path)
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 os.listdir(self.app.outdir):
# if listdir is empty, do build.
self.app.build(*args, **kwargs)
# otherwise, we can use built cache
def strip_escseq(text: str) -> str:
return re.sub('\x1b.*?m', '', text)