From 62064e0bd549bc13547db4fe9420c7dfac2e2687 Mon Sep 17 00:00:00 2001 From: Emma Jane Bonestell Date: Sun, 4 Oct 2026 13:43:51 -0500 Subject: [PATCH] [docutils] Improve and complete stubs --- stubs/docutils/@tests/stubtest_allowlist.txt | 70 +- .../docutils/@tests/test_cases/check_core.py | 26 + .../@tests/test_cases/check_directives.py | 53 + .../@tests/test_cases/check_languages.py | 20 + .../docutils/@tests/test_cases/check_nodes.py | 52 + .../docutils/@tests/test_cases/check_roles.py | 45 + .../@tests/test_cases/check_transforms.py | 25 + stubs/docutils/docutils/__init__.pyi | 67 +- stubs/docutils/docutils/core.pyi | 255 ++-- stubs/docutils/docutils/examples.pyi | 12 +- stubs/docutils/docutils/frontend.pyi | 123 +- stubs/docutils/docutils/io.pyi | 52 +- .../docutils/docutils/languages/__init__.pyi | 30 +- stubs/docutils/docutils/languages/af.pyi | 3 +- stubs/docutils/docutils/languages/ar.pyi | 3 +- stubs/docutils/docutils/languages/ca.pyi | 3 +- stubs/docutils/docutils/languages/cs.pyi | 3 +- stubs/docutils/docutils/languages/da.pyi | 3 +- stubs/docutils/docutils/languages/de.pyi | 3 +- stubs/docutils/docutils/languages/en.pyi | 3 +- stubs/docutils/docutils/languages/eo.pyi | 3 +- stubs/docutils/docutils/languages/es.pyi | 11 +- stubs/docutils/docutils/languages/fa.pyi | 3 +- stubs/docutils/docutils/languages/fi.pyi | 3 +- stubs/docutils/docutils/languages/fr.pyi | 3 +- stubs/docutils/docutils/languages/gl.pyi | 3 +- stubs/docutils/docutils/languages/he.pyi | 3 +- stubs/docutils/docutils/languages/it.pyi | 3 +- stubs/docutils/docutils/languages/ja.pyi | 3 +- stubs/docutils/docutils/languages/ka.pyi | 3 +- stubs/docutils/docutils/languages/ko.pyi | 3 +- stubs/docutils/docutils/languages/lt.pyi | 3 +- stubs/docutils/docutils/languages/lv.pyi | 3 +- stubs/docutils/docutils/languages/nl.pyi | 3 +- stubs/docutils/docutils/languages/pl.pyi | 3 +- stubs/docutils/docutils/languages/pt_br.pyi | 3 +- stubs/docutils/docutils/languages/ru.pyi | 3 +- stubs/docutils/docutils/languages/sk.pyi | 3 +- stubs/docutils/docutils/languages/sv.pyi | 3 +- stubs/docutils/docutils/languages/uk.pyi | 3 +- stubs/docutils/docutils/languages/zh_cn.pyi | 5 +- stubs/docutils/docutils/languages/zh_tw.pyi | 5 +- stubs/docutils/docutils/nodes.pyi | 1180 +++++++++++++---- stubs/docutils/docutils/parsers/__init__.pyi | 10 +- .../docutils/parsers/commonmark_wrapper.pyi | 6 +- .../docutils/parsers/recommonmark_wrapper.pyi | 91 +- .../docutils/parsers/rst/__init__.pyi | 14 +- .../parsers/rst/directives/__init__.pyi | 10 +- .../parsers/rst/directives/admonitions.pyi | 9 +- .../docutils/parsers/rst/directives/body.pyi | 72 +- .../parsers/rst/directives/images.pyi | 38 +- .../docutils/parsers/rst/directives/misc.pyi | 47 +- .../docutils/parsers/rst/directives/parts.pyi | 25 +- .../parsers/rst/directives/references.pyi | 8 +- .../parsers/rst/directives/tables.pyi | 50 +- .../parsers/rst/languages/__init__.pyi | 13 +- .../docutils/parsers/rst/languages/af.pyi | 1 + .../docutils/parsers/rst/languages/ar.pyi | 1 + .../docutils/parsers/rst/languages/ca.pyi | 1 + .../docutils/parsers/rst/languages/cs.pyi | 1 + .../docutils/parsers/rst/languages/da.pyi | 1 + .../docutils/parsers/rst/languages/de.pyi | 1 + .../docutils/parsers/rst/languages/en.pyi | 1 + .../docutils/parsers/rst/languages/eo.pyi | 1 + .../docutils/parsers/rst/languages/es.pyi | 1 + .../docutils/parsers/rst/languages/fa.pyi | 1 + .../docutils/parsers/rst/languages/fi.pyi | 1 + .../docutils/parsers/rst/languages/fr.pyi | 1 + .../docutils/parsers/rst/languages/gl.pyi | 1 + .../docutils/parsers/rst/languages/he.pyi | 1 + .../docutils/parsers/rst/languages/it.pyi | 1 + .../docutils/parsers/rst/languages/ja.pyi | 1 + .../docutils/parsers/rst/languages/ka.pyi | 1 + .../docutils/parsers/rst/languages/ko.pyi | 1 + .../docutils/parsers/rst/languages/lt.pyi | 1 + .../docutils/parsers/rst/languages/lv.pyi | 1 + .../docutils/parsers/rst/languages/nl.pyi | 1 + .../docutils/parsers/rst/languages/pl.pyi | 1 + .../docutils/parsers/rst/languages/pt_br.pyi | 1 + .../docutils/parsers/rst/languages/ru.pyi | 1 + .../docutils/parsers/rst/languages/sk.pyi | 1 + .../docutils/parsers/rst/languages/sv.pyi | 1 + .../docutils/parsers/rst/languages/uk.pyi | 1 + .../docutils/parsers/rst/languages/zh_cn.pyi | 1 + .../docutils/parsers/rst/languages/zh_tw.pyi | 1 + stubs/docutils/docutils/parsers/rst/roles.pyi | 83 +- .../docutils/docutils/parsers/rst/states.pyi | 645 +++++---- .../docutils/parsers/rst/tableparser.pyi | 2 +- stubs/docutils/docutils/readers/__init__.pyi | 4 +- .../docutils/docutils/readers/standalone.pyi | 3 +- stubs/docutils/docutils/statemachine.pyi | 78 +- .../docutils/docutils/transforms/__init__.pyi | 15 +- .../docutils/transforms/frontmatter.pyi | 14 +- stubs/docutils/docutils/transforms/parts.pyi | 8 +- .../docutils/transforms/references.pyi | 19 +- .../docutils/transforms/universal.pyi | 3 +- stubs/docutils/docutils/utils/__init__.pyi | 103 +- .../docutils/utils/_roman_numerals.pyi | 4 +- .../docutils/utils/math/math2html.pyi | 721 +++++----- .../docutils/utils/math/mathml_elements.pyi | 15 +- stubs/docutils/docutils/utils/smartquotes.pyi | 4 +- stubs/docutils/docutils/writers/__init__.pyi | 123 +- .../docutils/docutils/writers/_html_base.pyi | 63 +- .../docutils/writers/docutils_xml.pyi | 6 +- .../docutils/writers/html4css1/__init__.pyi | 35 +- .../docutils/writers/latex2e/__init__.pyi | 111 +- stubs/docutils/docutils/writers/manpage.pyi | 20 +- .../docutils/writers/odf_odt/__init__.pyi | 102 +- .../writers/odf_odt/pygmentsformatter.pyi | 49 +- .../docutils/writers/pep_html/__init__.pyi | 3 +- .../docutils/writers/s5_html/__init__.pyi | 4 +- .../docutils/writers/xetex/__init__.pyi | 4 +- 112 files changed, 3153 insertions(+), 1619 deletions(-) create mode 100644 stubs/docutils/@tests/test_cases/check_core.py create mode 100644 stubs/docutils/@tests/test_cases/check_directives.py create mode 100644 stubs/docutils/@tests/test_cases/check_languages.py create mode 100644 stubs/docutils/@tests/test_cases/check_nodes.py create mode 100644 stubs/docutils/@tests/test_cases/check_roles.py create mode 100644 stubs/docutils/@tests/test_cases/check_transforms.py diff --git a/stubs/docutils/@tests/stubtest_allowlist.txt b/stubs/docutils/@tests/stubtest_allowlist.txt index e210c1e10470..d0fe12a24972 100644 --- a/stubs/docutils/@tests/stubtest_allowlist.txt +++ b/stubs/docutils/@tests/stubtest_allowlist.txt @@ -1,25 +1,61 @@ -docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__ -docutils.nodes.Element.tagname # class variable is overridden in __init__ method -docutils.nodes.NodeVisitor.depart_\w+ # Methods are discovered dynamically on commonly-used subclasses -docutils.nodes.NodeVisitor.visit_\w+ # Methods are discovered dynamically on commonly-used subclasses -docutils.nodes.NodeVisitor.__init__ # Argument "document" should be positional-only, but subclasses are not +# This class variable is overridden in __init__. +docutils.nodes.Element.tagname +# The `document` parameter should be positional-only, but there are subclasses where it is not. +docutils.nodes.NodeVisitor.__init__ -# these methods take a rawsource parameter that has been deprecated and is completely ignored, so we omit it from the stub +# This constructor technically still takes a `rawsource` parameter; +# however, it is deprecated on Text nodes. Passing 'None' prints a warning, and passing +# anything else will raise. +# It is omitted for simplicity (e.g. not requiring matching overloads in child classes). docutils.nodes.Text.__new__ -docutils.parsers.rst.directives.admonitions.BaseAdmonition.node_class # must be overridden by base classes (pseudo-abstract) -docutils.statemachine.State.nested_sm # is initialised in __init__ -docutils.statemachine.State.nested_sm_kwargs # is initialised in __init__ -docutils.statemachine.ViewList.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__ -docutils.transforms.Transform.apply # method apply is not implemented -docutils.transforms.Transform.__getattr__ -docutils.TransformSpec.unknown_reference_resolvers + +# This attribute is required to be overridden by base classes (pseudo-abstractmethod). +docutils.parsers.rst.directives.admonitions.BaseAdmonition.node_class + +# These attributes are initialized to None in the classs-body, then initialized in __init__. +# It is never None in practice. +docutils.statemachine.State.nested_sm +docutils.statemachine.State.nested_sm_kwargs + +# These attribute names contain spaces and are set using setattr from docutils.sty. docutils.writers.latex2e.PreambleCmds... contents -docutils.writers.latex2e.PreambleCmds.inline role \w+ # attribute names with spaces, set with setattr() from docutils.sty +docutils.writers.latex2e.PreambleCmds.inline role \w+ -# Files that don't exist at runtime of stubtests, raises ImportError: +# These modules have optional dependencies that likely are not available at runtime. docutils.parsers.commonmark_wrapper docutils.parsers.recommonmark_wrapper -docutils.writers.odf_odt.pygmentsformatter # import `pygments` third-party library -# `TYPE_CHECKING` variable is for internal use: +# Imports `pygments`; using types-Pygments caused ts_utils to have a recuesion error. +docutils.writers.odf_odt.pygmentsformatter + +# Docutils defines `TYPE_CHECKING` instead of importing it. docutils.*\.TYPE_CHECKING + +# stubtest infers `dict[Any, Any]` for the optional keyword arguments. +# That obviously fails to match `_OptionKwargs`. +docutils\..*\.settings_spec + +# Not generic at runtime, but it is runtime subscriptable via `__class_getitem__()`. +# Take advantage by treating it like a proper generic. +docutils.languages.LanguageImporter.__class_getitem__ + +# These are functions defined in the class bodies without `self`. +# They are only meant to be accessed via the class (e.g. in `option_spec`); +# When docutils drops 3.9 support, they should theoretically be real staticmethods. +docutils.parsers.rst.directives.images.Figure.align +docutils.parsers.rst.directives.images.Figure.figwidth_value +docutils.parsers.rst.directives.images.Image.align +docutils.parsers.rst.directives.images.Image.loading +docutils.parsers.rst.directives.parts.Contents.backlinks + +# These are aliased to `invalid_input(), with defaulted parameters, at runtime. +# Subclasses must explicitly re-enable. This causes unavoidable signature conflicts. +# The stub keeps the expected transition signatures so that subclasses may override without errors. +docutils.parsers.rst.states.SpecializedBody.(anonymous|bullet|doctest|enumerator|explicit_markup|field_marker|grid_table_top|indent|line|line_block|option_marker|simple_table_top|text) +docutils.parsers.rst.states.SpecializedText.(blank|indent|text|underline) + +# This is mutated at runtime. It is `None` at class level, and +# once `Reader.read()` is called, it is no longer None. +# `Reader.document` has no real good reason to be accessed before calling `read`, and +# annotating as "| None" is an unnecessary nuissance. +docutils.readers.standalone.Reader.document diff --git a/stubs/docutils/@tests/test_cases/check_core.py b/stubs/docutils/@tests/test_cases/check_core.py new file mode 100644 index 000000000000..4cb259adfae5 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_core.py @@ -0,0 +1,26 @@ +from __future__ import annotations + +from typing_extensions import assert_type + +from docutils.core import publish_doctree, publish_parts + +# `publish_parts()` returns writer-specific parts for the HTML and LaTeX writers. +# It should be possible to deduce key types with this knowledge. +html_parts = publish_parts("Hello", writer="html5") +assert_type(html_parts["body"], str) +assert_type(html_parts["whole"], str) +latex_parts = publish_parts("Hello", writer="latex") +assert_type(latex_parts["titledata"], str) +other_parts = publish_parts("Hello", writer="pseudoxml") +assert_type(other_parts["whole"], "str | bytes") +assert_type(other_parts.get("body"), "str | None") + +# `settings_overrides` should accept any copyable mapping. +# This should include `dict`s of narrower value types. +overrides: dict[str, int] = {"report_level": 5, "halt_level": 5} +publish_doctree("x", settings_overrides=overrides) +publish_doctree("x", settings_overrides={"report_level": 5, "input_encoding": "utf-8"}) + + +def not_a_mapping() -> None: + publish_doctree("x", settings_overrides=[("report_level", 5)]) # type: ignore[arg-type] diff --git a/stubs/docutils/@tests/test_cases/check_directives.py b/stubs/docutils/@tests/test_cases/check_directives.py new file mode 100644 index 000000000000..b6f49e817e16 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_directives.py @@ -0,0 +1,53 @@ +from __future__ import annotations + +from collections.abc import Callable, Sequence +from typing import ClassVar + +from docutils import nodes +from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst.directives.body import Rubric, Topic +from docutils.parsers.rst.directives.images import Figure +from docutils.parsers.rst.directives.tables import CSVTable + + +# `option_spec` should accept any mapping. +# This should include `dict` subclasses with narrower converters. +class DummyOptionSpec(dict[str, Callable[[str], str]]): + def __bool__(self) -> bool: + return True + + +class AnyOptions(Directive): + option_spec = DummyOptionSpec() + + +# Concrete directives have a `dict` option spec that should be extendable. +class Exercise(Topic): + option_spec: ClassVar[dict[str, Callable[[str], object]]] = {**Topic.option_spec, "difficulty": directives.nonnegative_int} + + +class MyFigure(Figure): + option_spec: ClassVar[dict[str, Callable[[str], object]]] = Figure.option_spec.copy() + option_spec["caption"] = directives.unchanged + + # Overrides should be able to return a (narrower) sequence of nodes. + def run(self) -> Sequence[nodes.Node]: + return super().run() + + +class MyRubric(Rubric): + def run(self) -> list[nodes.rubric | nodes.system_message]: + return [] + + +class MyCSVTable(CSVTable): + def run(self) -> Sequence[nodes.table | nodes.system_message]: + return super().run() + + +# A directive's own `option_spec` literal should be acceptable. +class MyDirective(Directive): + option_spec = {"class": directives.class_option, "flag": directives.flag, "count": directives.nonnegative_int} + + def run(self) -> list[nodes.Node]: + return [] diff --git a/stubs/docutils/@tests/test_cases/check_languages.py b/stubs/docutils/@tests/test_cases/check_languages.py new file mode 100644 index 000000000000..787c3f027ed4 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_languages.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +from typing import TYPE_CHECKING +from typing_extensions import assert_type + +from docutils.languages import LanguageImporter, get_language +from docutils.parsers.rst.languages import get_language as get_rst_language + +if TYPE_CHECKING: + from docutils.languages import LanguageModule + from docutils.parsers.rst.languages import RSTLanguageModule + + +assert_type(get_language("de"), "LanguageModule") + +# The rST importer has should have no fallback language. +assert_type(get_rst_language("de"), "RSTLanguageModule | None") + +# The module type should default to `LanguageModule`. +assert_type(LanguageImporter()("de"), "LanguageModule") diff --git a/stubs/docutils/@tests/test_cases/check_nodes.py b/stubs/docutils/@tests/test_cases/check_nodes.py new file mode 100644 index 000000000000..a2ee784054c8 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_nodes.py @@ -0,0 +1,52 @@ +from __future__ import annotations + +from typing import Any +from typing_extensions import assert_type + +from docutils import nodes + + +# Well-known attributes with stable types have `Literal`-keyed overloads. +# So, it should be able to deduce the types of certain keys. +def attributes(node: nodes.Element) -> None: + assert_type(node["classes"], list[str]) + assert_type(node.get("classes"), list[str]) + assert_type(node.get("backrefs"), "list[str] | None") + assert_type(node["refuri"], str) + assert_type(node.get("refuri"), "str | None") + assert_type(node.get("refuri", ""), str) + + # Arbitrary attributes are `Any`. + assert_type(node.get("highlight_args", {}), Any) + + +# Visitor methods should be overridable with any return type. +class Visitor(nodes.SparseNodeVisitor): + def visit_paragraph(self, node: nodes.paragraph) -> None: + raise nodes.SkipNode + + def visit_section(self, node: nodes.Element) -> bool: + return True + + +# A node's parent may be `None`; the root document never has one. +def parents(document: nodes.document, paragraph: nodes.paragraph) -> None: + assert_type(document.parent, None) + assert_type(paragraph.parent, "nodes.Element | None") + if paragraph.parent is not None: + paragraph.parent.remove(paragraph) + + +# Visit/depart methods do not exist on the base `NodeVisitor` at runtime. +# The methods only exist when a subclass defines them. +class DirectVisitor(nodes.NodeVisitor): + def visit_paragraph(self, node: nodes.paragraph) -> None: + # Pyright correctly flags this as not existing NodeVisitor. + super().visit_paragraph(node) # pyright: ignore[reportGeneralTypeIssues] + + +class SparseVisitor(nodes.SparseNodeVisitor): + # Pyright correctly allows this because it is concretely defined + # in SparseNodeVisitor. + def visit_paragraph(self, node: nodes.paragraph) -> None: + super().visit_paragraph(node) diff --git a/stubs/docutils/@tests/test_cases/check_roles.py b/stubs/docutils/@tests/test_cases/check_roles.py new file mode 100644 index 000000000000..e4e3f0ae7538 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_roles.py @@ -0,0 +1,45 @@ +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import Any +from typing_extensions import assert_type + +from docutils import nodes +from docutils.parsers.rst import roles +from docutils.parsers.rst.states import Inliner + +# Docutils calls Role functions with five positional arguments, so the names do not matter. +# `options` and `content` are passed as keyword-only by `CustomRole`, so they must have defaults. + + +def role_with_defaults( + name: str, + rawtext: str, + text: str, + lineno: int, + inliner: Inliner, + options: Mapping[str, Any] | None = None, + content: Sequence[str] | None = None, +) -> tuple[list[nodes.Node], list[nodes.system_message]]: + return [], [] + + +def role_with_dict_defaults( + typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict[str, Any] = {}, content: list[str] = [] +) -> tuple[list[nodes.reference], list[nodes.system_message]]: + return [], [] + + +def role_without_defaults( + name: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict[str, Any], content: list[str] +) -> tuple[list[nodes.Node], list[nodes.system_message]]: + return [], [] + + +roles.register_local_role("a", role_with_defaults) +roles.register_local_role("b", role_with_dict_defaults) +roles.register_local_role("c", role_without_defaults) # type: ignore[arg-type] +roles.register_canonical_role("d", roles.GenericRole("d", nodes.emphasis)) + +# `normalize_options()` should preserve the value type of the options. +assert_type(roles.normalize_options({"class": ["a"]}), dict[str, list[str]]) diff --git a/stubs/docutils/@tests/test_cases/check_transforms.py b/stubs/docutils/@tests/test_cases/check_transforms.py new file mode 100644 index 000000000000..0ad9e635fc24 --- /dev/null +++ b/stubs/docutils/@tests/test_cases/check_transforms.py @@ -0,0 +1,25 @@ +from __future__ import annotations + +from typing import Any + +from docutils.transforms import Transform + +# `apply()` overrides should be accepted with and without kwargs, +# True keyword arguments (and positional) should error. + + +class DocutilsStyle(Transform): + def apply(self) -> None: ... + + +class SphinxStyle(Transform): + def apply(self, **kwargs: Any) -> None: ... + + +class RequiredKeyword(Transform): + def apply(self, *, level: int) -> None: ... # type: ignore[override] + + +def apply(transform: Transform) -> None: + transform.apply() + transform.apply(level=1) # type: ignore[call-arg] diff --git a/stubs/docutils/docutils/__init__.pyi b/stubs/docutils/docutils/__init__.pyi index 9845ec945daa..4f1fc596556a 100644 --- a/stubs/docutils/docutils/__init__.pyi +++ b/stubs/docutils/docutils/__init__.pyi @@ -1,24 +1,35 @@ -from typing import Any, ClassVar, Final, NamedTuple, type_check_only +from collections.abc import Callable, Sequence +from typing import Any, ClassVar, Final, Literal, NamedTuple, Protocol, TypeAlias, TypedDict, type_check_only from typing_extensions import Self +from docutils.frontend import _OptionValidator +from docutils.nodes import Element from docutils.transforms import Transform __docformat__: Final = "reStructuredText" __version__: Final[str] +_ReleaseLevels: TypeAlias = Literal["alpha", "beta", "candidate", "final"] + @type_check_only class _VersionInfo(NamedTuple): major: int minor: int micro: int - releaselevel: str + releaselevel: _ReleaseLevels serial: int release: bool class VersionInfo(_VersionInfo): __slots__ = () def __new__( - cls, major: int = 0, minor: int = 0, micro: int = 0, releaselevel: str = "final", serial: int = 0, release: bool = True + cls, + major: int = 0, + minor: int = 0, + micro: int = 0, + releaselevel: _ReleaseLevels = "final", + serial: int = 0, + release: bool = True, ) -> Self: ... __version_info__: Final[VersionInfo] @@ -27,20 +38,56 @@ __version_details__: Final[str] class ApplicationError(Exception): ... class DataError(ApplicationError): ... +# Docutil's frontend options. +# +# The keywords are :const:`optparse.Option.ATTRS` and docutils' +# extensions "validator" and "overrides". +@type_check_only +class _OptionKwargs(TypedDict, total=False): + action: str + type: str + dest: str + default: object + nargs: int + const: object + choices: Sequence[str] + callback: Callable[..., object] + callback_args: tuple[object, ...] + callback_kwargs: dict[str, object] + help: str + metavar: str + validator: _OptionValidator + overrides: str + +# Option tuple holding: (help text, option strings, keyword arguments). +_OptionTuple: TypeAlias = tuple[str, list[str], _OptionKwargs] +# A flat sequence of (group title, group description, options) tuples. +_SettingsSpecTuple: TypeAlias = tuple[str | Sequence[_OptionTuple] | None, ...] + class SettingsSpec: - settings_spec: ClassVar[tuple[Any, ...]] # Mixed tuple structure; uses Any for flexibility in nested option definitions - settings_defaults: ClassVar[dict[Any, Any] | None] - settings_default_overrides: ClassVar[dict[Any, Any] | None] - relative_path_settings: ClassVar[tuple[Any, ...]] + settings_spec: ClassVar[_SettingsSpecTuple] + # Setting values are heterogeneous, see: + # . + settings_defaults: ClassVar[dict[str, Any] | None] + settings_default_overrides: ClassVar[dict[str, Any] | None] + relative_path_settings: ClassVar[tuple[str, ...]] config_section: ClassVar[str | None] config_section_dependencies: ClassVar[tuple[str, ...] | None] +@type_check_only +class _UnknownReferenceResolver(Protocol): + priority: int + def __call__(self, node: Element, /) -> bool: ... + class TransformSpec: def get_transforms(self) -> list[type[Transform]]: ... - default_transforms: ClassVar[tuple[Any, ...]] - unknown_reference_resolvers: ClassVar[list[Any]] + # Deprecated, use/override `get_transforms()` instead. + # This will be removed in Docutils 2.0. + default_transforms: ClassVar[tuple[type[Transform], ...]] + # Deprecated, will be removed in Docutils 1.0. + unknown_reference_resolvers: Sequence[_UnknownReferenceResolver] class Component(SettingsSpec, TransformSpec): - component_type: ClassVar[str | None] + component_type: ClassVar[Literal["reader", "parser", "writer", "input", "output"] | None] supported: ClassVar[tuple[str, ...]] def supports(self, format: str) -> bool: ... diff --git a/stubs/docutils/docutils/core.pyi b/stubs/docutils/docutils/core.pyi index 00e9b290ca0b..1a44a5685276 100644 --- a/stubs/docutils/docutils/core.pyi +++ b/stubs/docutils/docutils/core.pyi @@ -1,5 +1,5 @@ -from _typeshed import Incomplete, StrPath -from typing import IO, Final +from _typeshed import StrPath, SupportsKeysAndGetItem +from typing import IO, Any, Final, Literal, Protocol, TypeAlias, overload, type_check_only from typing_extensions import deprecated from docutils import SettingsSpec, nodes @@ -8,32 +8,52 @@ from docutils.io import Input, Output from docutils.parsers import Parser from docutils.readers import Reader from docutils.utils import SystemMessage -from docutils.writers import Writer, _WriterParts +from docutils.writers import Writer, _html_base, _HTMLWriterParts, _LaTeXWriterParts, _WriterParts, latex2e __docformat__: Final = "reStructuredText" +# Components may be given as instances, by name, or by alias. +_ReaderArg: TypeAlias = Reader[Any] | str | None +_ParserArg: TypeAlias = Parser | str | None +_WriterArg: TypeAlias = Writer[Any] | str | None +_HTMLWriterName: TypeAlias = Literal[ + "html", "html4", "xhtml10", "html4css1", "html5", "xhtml", "html5_polyglot", "s5", "s5_html", "pep_html" +] +_LaTeXWriterName: TypeAlias = Literal["latex", "latex2e", "xetex", "xelatex", "luatex", "lualatex"] + +# A mapping of setting names to values which is copied with `.copy()` and unpacked with `**`. +# This would typically be a `dict`. +# +# See: . +@type_check_only +class _SettingsOverrides(SupportsKeysAndGetItem[str, object], Protocol): + def copy(self) -> SupportsKeysAndGetItem[str, object]: ... + +_FileSource: TypeAlias = IO[str] | IO[bytes] +_FileDestination: TypeAlias = IO[str] | IO[bytes] + class Publisher: document: nodes.document | None - reader: Reader[Incomplete] - parser: Parser - writer: Writer[Incomplete] - source: Input[Incomplete] - source_class: type[Input[Incomplete]] + reader: Reader[Any] + parser: Parser | None + writer: Writer[Any] + source: Input[Any] | None + source_class: type[Input[Any]] destination: Output | None destination_class: type[Output] - settings: dict[str, Incomplete] + settings: Values | None def __init__( self, - reader: Reader[Incomplete] | None = None, - parser: Parser | None = None, - writer: Writer[Incomplete] | None = None, - source: Input[Incomplete] | None = None, - source_class: type[Input[Incomplete]] = ..., + reader: _ReaderArg = None, + parser: _ParserArg = None, + writer: _WriterArg = None, + source: Input[Any] | None = None, + source_class: type[Input[Any]] = ..., destination: Output | None = None, destination_class: type[Output] = ..., - settings: dict[str, Incomplete] | None = None, + settings: Values | None = None, ) -> None: ... - def set_reader(self, reader: str, parser: Parser | None = None, parser_name: str | None = None) -> None: ... + def set_reader(self, reader: str, parser: Parser | str | None = None, parser_name: str | None = None) -> None: ... def set_writer(self, writer_name: str) -> None: ... @deprecated("The `Publisher.set_components()` will be removed in Docutils 2.0.") def set_components(self, reader_name: str, parser_name: str, writer_name: str) -> None: ... @@ -43,32 +63,34 @@ class Publisher: description: str | None = None, settings_spec: SettingsSpec | None = None, config_section: str | None = None, - **defaults, - ): ... - def process_programmatic_settings(self, settings_spec, settings_overrides, config_section) -> None: ... + **defaults: object, + ) -> Values: ... + def process_programmatic_settings( + self, settings_spec: SettingsSpec | None, settings_overrides: _SettingsOverrides | None, config_section: str | None + ) -> None: ... def process_command_line( self, argv: list[str] | None = None, - usage=None, + usage: str | None = None, description: str | None = None, - settings_spec=None, - config_section=None, - **defaults, + settings_spec: SettingsSpec | None = None, + config_section: str | None = None, + **defaults: object, ) -> None: ... def set_io(self, source_path: StrPath | None = None, destination_path: StrPath | None = None) -> None: ... - def set_source(self, source: str | None = None, source_path: StrPath | None = None) -> None: ... - def set_destination(self, destination=None, destination_path: StrPath | None = None) -> None: ... + def set_source(self, source: object = None, source_path: StrPath | None = None) -> None: ... + def set_destination(self, destination: _FileDestination | None = None, destination_path: StrPath | None = None) -> None: ... def apply_transforms(self) -> None: ... def publish( self, argv: list[str] | None = None, usage: str | None = None, description: str | None = None, - settings_spec=None, - settings_overrides=None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, - ): ... + ) -> str | bytes | None: ... def debugging_dumps(self) -> None: ... def prompt(self) -> None: ... def report_Exception(self, error: BaseException) -> None: ... @@ -79,132 +101,175 @@ default_usage: Final[str] default_description: Final[str] def publish_cmdline( - reader: Reader[Incomplete] | None = None, + reader: _ReaderArg = None, reader_name: str | None = None, - parser: Parser | None = None, + parser: _ParserArg = None, parser_name: str | None = None, - writer: Writer[Incomplete] | None = None, + writer: _WriterArg = None, writer_name: str | None = None, - settings=None, - settings_spec=None, - settings_overrides=None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = True, argv: list[str] | None = None, - usage: str = "%prog [options] [ []]", + usage: str = ..., description: str = ..., -): ... +) -> str | bytes | None: ... def publish_file( - source=None, + source: _FileSource | None = None, source_path: StrPath | None = None, - destination=None, + destination: _FileDestination | None = None, destination_path: StrPath | None = None, - reader=None, + reader: _ReaderArg = None, reader_name: str | None = None, - parser=None, + parser: _ParserArg = None, parser_name: str | None = None, - writer=None, + writer: _WriterArg = None, writer_name: str | None = None, - settings=None, - settings_spec=None, - settings_overrides=None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, -): ... +) -> str | bytes: ... + +# Returns `bytes` unless the "output_encoding" setting is "unicode". This is not type encodable. def publish_string( - source, + source: str | bytes, source_path: StrPath | None = None, destination_path: StrPath | None = None, - reader=None, + reader: _ReaderArg = None, reader_name: str | None = None, - parser=None, + parser: _ParserArg = None, parser_name: str | None = None, - writer=None, + writer: _WriterArg = None, writer_name: str | None = None, - settings=None, - settings_spec=None, - settings_overrides=None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, -): ... +) -> str | bytes: ... + +@overload +def publish_parts( # type: ignore[overload-overlap] + source: str | bytes | nodes.document | IO[str] | IO[bytes], # depends on `source_class` + source_path: StrPath | None = None, + source_class: type[Input[Any]] = ..., + destination_path: StrPath | None = None, + reader: _ReaderArg = None, + reader_name: str | None = None, + parser: _ParserArg = None, + parser_name: str | None = None, + *, + writer: _HTMLWriterName | _html_base.Writer, + writer_name: str | None = None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, + config_section: str | None = None, + enable_exit_status: bool = False, +) -> _HTMLWriterParts: ... +@overload +def publish_parts( # type: ignore[overload-overlap] + source: str | bytes | nodes.document | IO[str] | IO[bytes], # depends on `source_class` + source_path: StrPath | None = None, + source_class: type[Input[Any]] = ..., + destination_path: StrPath | None = None, + reader: _ReaderArg = None, + reader_name: str | None = None, + parser: _ParserArg = None, + parser_name: str | None = None, + *, + writer: _LaTeXWriterName | latex2e.Writer, + writer_name: str | None = None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, + config_section: str | None = None, + enable_exit_status: bool = False, +) -> _LaTeXWriterParts: ... +@overload def publish_parts( - source, + source: str | bytes | nodes.document | IO[str] | IO[bytes], # depends on `source_class` source_path: StrPath | None = None, - source_class: type[Input[Incomplete]] = ..., + source_class: type[Input[Any]] = ..., destination_path: StrPath | None = None, - reader=None, + reader: _ReaderArg = None, reader_name: str | None = None, - parser=None, + parser: _ParserArg = None, parser_name: str | None = None, - writer=None, + writer: _WriterArg = None, writer_name: str | None = None, - settings=None, - settings_spec=None, - settings_overrides: dict[str, Incomplete] | None = None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, ) -> _WriterParts: ... + def publish_doctree( source: str | bytes | IO[str] | IO[bytes] | None, source_path: StrPath | None = None, - source_class: type[Input[Incomplete]] = ..., - reader: Reader[Incomplete] | str | None = None, + source_class: type[Input[Any]] = ..., + reader: _ReaderArg = None, reader_name: str | None = None, - parser: Parser | str | None = None, + parser: _ParserArg = None, parser_name: str | None = None, settings: Values | None = None, - settings_spec: SettingsSpec | type[SettingsSpec] | None = None, - settings_overrides: dict[str, Incomplete] | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, ) -> nodes.document: ... def publish_from_doctree( - document, + document: nodes.document, destination_path: StrPath | None = None, - writer=None, + writer: _WriterArg = None, writer_name: str | None = None, - settings=None, - settings_spec=None, - settings_overrides=None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = False, -): ... -@deprecated("The `publish_cmdline_to_binary()` is deprecated by `publish_cmdline()` and will be removed in Docutils 0.24.") +) -> str | bytes: ... +@deprecated("The `publish_cmdline_to_binary()` is deprecated by `publish_cmdline()` and will be removed in Docutils 0.24.") def publish_cmdline_to_binary( - reader=None, + reader: _ReaderArg = None, reader_name: str = "standalone", - parser=None, + parser: _ParserArg = None, parser_name: str = "restructuredtext", - writer=None, + writer: _WriterArg = None, writer_name: str = "pseudoxml", - settings=None, - settings_spec=None, - settings_overrides=None, + settings: Values | None = None, + settings_spec: SettingsSpec | None = None, + settings_overrides: _SettingsOverrides | None = None, config_section: str | None = None, enable_exit_status: bool = True, argv: list[str] | None = None, - usage: str = "%prog [options] [ []]", + usage: str = ..., description: str = ..., - destination=None, + destination: _FileDestination | None = None, destination_class: type[Output] = ..., -): ... +) -> str | bytes | None: ... def publish_programmatically( - source_class: type[Input[Incomplete]], - source, + source_class: type[Input[Any]], + source: object, source_path: StrPath | None, destination_class: type[Output], - destination, + destination: _FileDestination | None, destination_path: StrPath | None, - reader, - reader_name: str, - parser, - parser_name: str, - writer, - writer_name: str, - settings, - settings_spec, - settings_overrides, - config_section: str, + reader: _ReaderArg, + reader_name: str | None, + parser: _ParserArg, + parser_name: str | None, + writer: _WriterArg, + writer_name: str | None, + settings: Values | None, + settings_spec: SettingsSpec | None, + settings_overrides: _SettingsOverrides | None, + config_section: str | None, enable_exit_status: bool, ) -> tuple[str | bytes | None, Publisher]: ... def rst2something(writer: str, documenttype: str, doc_path: str = "") -> None: ... diff --git a/stubs/docutils/docutils/examples.pyi b/stubs/docutils/docutils/examples.pyi index 3973316b9666..c71a44e1624f 100644 --- a/stubs/docutils/docutils/examples.pyi +++ b/stubs/docutils/docutils/examples.pyi @@ -1,9 +1,9 @@ -from _typeshed import Incomplete, StrPath +from _typeshed import StrPath from typing import Literal, TypeAlias, overload -from docutils.core import Publisher +from docutils.core import Publisher, _SettingsOverrides from docutils.nodes import document -from docutils.writers import _WriterParts +from docutils.writers import _HTMLWriterParts _HTMLHeaderLevel: TypeAlias = Literal[1, 2, 3, 4, 5, 6] @@ -14,7 +14,7 @@ def html_parts( input_encoding: str = "unicode", doctitle: bool = True, initial_header_level: _HTMLHeaderLevel = 1, -) -> _WriterParts: ... +) -> _HTMLWriterParts: ... @overload def html_body( @@ -41,5 +41,5 @@ def internals( source: str, source_path: StrPath | None = None, input_encoding: str = "unicode", - settings_overrides: dict[str, Incomplete] | None = None, -) -> tuple[document | None, Publisher]: ... + settings_overrides: _SettingsOverrides | None = None, +) -> tuple[document, Publisher]: ... diff --git a/stubs/docutils/docutils/frontend.pyi b/stubs/docutils/docutils/frontend.pyi index 88aabf86b2e6..e2fc1eb0db73 100644 --- a/stubs/docutils/docutils/frontend.pyi +++ b/stubs/docutils/docutils/frontend.pyi @@ -1,11 +1,11 @@ import optparse -from _typeshed import Incomplete, StrPath -from collections.abc import Iterable, Mapping, Sequence +from _typeshed import StrPath, SupportsWrite +from collections.abc import Iterable, Mapping, MutableMapping, Sequence from configparser import RawConfigParser from typing import Any, ClassVar, Final, Literal, Protocol, overload, type_check_only -from typing_extensions import deprecated +from typing_extensions import Unpack, deprecated -from docutils import SettingsSpec +from docutils import SettingsSpec, _OptionKwargs, _OptionTuple, _SettingsSpecTuple from docutils.utils import DependencyList __docformat__: Final = "reStructuredText" @@ -20,19 +20,21 @@ class _OptionValidator(Protocol): /, config_parser: ConfigParser | None = None, config_section: str | None = None, - ) -> Any: ... + ) -> object: ... -@deprecated("Deprecated and will be removed with the switch to from optparse to argparse.") -def store_multiple(option: optparse.Option, opt: str, value, parser: OptionParser, *args: str, **kwargs) -> None: ... -@deprecated("Deprecated and will be removed with the switch to from optparse to argparse.") -def read_config_file(option: optparse.Option, opt: str, value, parser: OptionParser) -> None: ... +@deprecated("Deprecated and will be removed with the switch from optparse to argparse in Docutils 2.0.") +def store_multiple( + option: optparse.Option, opt: str, value: object, parser: OptionParser, *args: str, **kwargs: object +) -> None: ... +@deprecated("Deprecated and will be removed with the switch from optparse to argparse in Docutils 2.0.") +def read_config_file(option: optparse.Option, opt: str, value: str, parser: OptionParser) -> None: ... def validate_encoding( setting: str, value: str | None = None, option_parser: OptionParser | None = None, config_parser: ConfigParser | None = None, config_section: str | None = None, -) -> str: ... +) -> str | None: ... # `None` for the deprecated empty value def validate_encoding_error_handler( setting: str, value: str | None = None, @@ -124,31 +126,92 @@ def validate_smartquotes_locales( config_parser: ConfigParser | None = None, config_section: str | None = None, ) -> list[tuple[str, Sequence[str]]]: ... -def make_paths_absolute( - pathdict: dict[str, list[StrPath] | StrPath], keys: tuple[str], base_path: StrPath | None = None -) -> None: ... +def make_paths_absolute(pathdict: MutableMapping[str, Any], keys: Iterable[str], base_path: StrPath | None = None) -> None: ... @deprecated("The `frontend.make_one_path_absolute` will be removed in Docutils 2.0 or later.") def make_one_path_absolute(base_path: StrPath, path: StrPath) -> str: ... -def filter_settings_spec(settings_spec, *exclude, **replace) -> tuple[Any, ...]: ... +def filter_settings_spec(settings_spec: _SettingsSpecTuple, *exclude: str, **replace: _OptionTuple) -> _SettingsSpecTuple: ... -@deprecated("The `frontend.Values` class will be removed in Docutils 2.0 or later.") +# Storage for setting values; one attribute per setting. +# The attributes below are the settings of the core `OptionParser` (always present), +# and of the reStructuredText parser (present when it is used). +# Settings of other components are available via `optparse.Values.__getattr__()`. class Values(optparse.Values): + # Settings from `OptionParser.settings_spec` and `OptionParser.settings_defaults` + _config_files: list[str] + _destination: StrPath | None + _disable_config: bool | None + _source: StrPath | None + auto_id_prefix: str + config: str | None + datestamp: str | None + debug: bool | None + dump_internals: bool | None + dump_pseudo_xml: bool | None + dump_settings: bool | None + dump_transforms: bool | None + error_encoding: str + error_encoding_error_handler: str + exit_status_level: int + expose_internals: list[str] | None + footnote_backlinks: bool + generator: bool | None + halt_level: int + id_prefix: str + input_encoding: str | None + input_encoding_error_handler: str + language_code: str + output_encoding: str + output_encoding_error_handler: str + output_path: StrPath | None record_dependencies: DependencyList - def __init__(self, defaults: dict[str, Any] | None = None) -> None: ... - def update(self, other_dict: Values | Mapping[str, Incomplete], option_parser: OptionParser) -> None: ... + report_level: int + root_prefix: str + sectnum_xform: bool + source_link: bool | None + source_url: str | None + strict_visitor: bool | None + strip_classes: list[str] | None + strip_comments: bool | None + strip_elements_with_classes: list[str] | None + title: str | None + toc_backlinks: Literal["entry", "top", False] + traceback: bool | None + warning_stream: str | SupportsWrite[str] | None + # Settings for the reStructuredText parser (`docutils.parsers.rst.Parser.settings_spec`) + character_level_inline_markup: bool + file_insertion_enabled: bool + legacy_ids: bool + line_length_limit: int + pep_base_url: str + pep_file_url_template: str + pep_references: bool | None + raw_enabled: bool + rfc_base_url: str + rfc_references: bool | None + # Any string starting with "alt" (as in "alternative") are meaningful. + # `apply()` catches AttributeError and sets it to False. + smart_quotes: bool | str + smartquotes_locales: list[tuple[str, Sequence[str]]] | None + syntax_highlight: Literal["long", "short", "none"] + tab_width: int + trim_footnote_reference_space: bool | None + validate: bool | None + + @deprecated("The `frontend.Values` class will be removed in Docutils 2.0 or later.") + def __init__(self, defaults: Mapping[str, object] | None = None) -> None: ... + def update(self, other_dict: Values | Mapping[str, object], option_parser: OptionParser) -> None: ... def copy(self) -> Values: ... - def setdefault(self, name: str, default): ... + # Returns the current or new value of an arbitrary setting. + def setdefault(self, name: str, default: object) -> Any: ... -@deprecated("The `frontend.Option` class will be removed in Docutils 2.0 or later.") class Option(optparse.Option): ATTRS: list[str] validator: _OptionValidator overrides: str | None - def __init__(self, *args: str | None, **kwargs) -> None: ... -@deprecated( - "The `frontend.OptionParser` class will be replaced by a subclass of `argparse.ArgumentParser` in Docutils 2.0 or later." -) + @deprecated("The `frontend.Option` class will be removed in Docutils 2.0 or later.") + def __init__(self, *args: str | None, **kwargs: Unpack[_OptionKwargs]) -> None: ... + class OptionParser(optparse.OptionParser, SettingsSpec): standard_config_files: ClassVar[list[str]] threshold_choices: ClassVar[tuple[str, ...]] @@ -164,19 +227,25 @@ class OptionParser(optparse.OptionParser, SettingsSpec): relative_path_settings: ClassVar[tuple[str, ...]] version: str components: tuple[SettingsSpec, ...] + + @deprecated( + "The `frontend.OptionParser` class will be replaced by a subclass of `argparse.ArgumentParser` in Docutils 2.0 or later." + ) def __init__( self, components: Iterable[SettingsSpec | type[SettingsSpec]] = (), - defaults: Mapping[str, Any] | None = None, + defaults: Mapping[str, object] | None = None, read_config_files: bool | None = False, - *args, - **kwargs, + *args: Any, # passed on to `optparse.OptionParser.__init__()` + **kwargs: Any, ) -> None: ... def populate_from_components(self, components: Iterable[SettingsSpec]) -> None: ... @classmethod def get_standard_config_files(cls) -> Sequence[StrPath]: ... def get_standard_config_settings(self) -> Values: ... - def get_config_file_settings(self, config_file: str) -> dict[str, Incomplete]: ... + # `Any` for values of arbitrary settings + def get_config_file_settings(self, config_file: str) -> dict[str, Any]: ... + # Docutils itself commits this violation; not fixable in a stub. def check_values(self, values: Values, args: list[str]) -> Values: ... # type: ignore[override] def check_args(self, args: list[str]) -> tuple[str | None, str | None]: ... def get_default_values(self) -> Values: ... diff --git a/stubs/docutils/docutils/io.pyi b/stubs/docutils/docutils/io.pyi index 41cec25e1fd4..b455a260b0ce 100644 --- a/stubs/docutils/docutils/io.pyi +++ b/stubs/docutils/docutils/io.pyi @@ -1,5 +1,4 @@ from _typeshed import ( - Incomplete, OpenBinaryModeReading, OpenBinaryModeWriting, OpenTextModeReading, @@ -9,7 +8,7 @@ from _typeshed import ( Unused, ) from re import Pattern -from typing import IO, Any, ClassVar, Final, Generic, Literal, TextIO, TypeVar +from typing import IO, ClassVar, Final, Generic, Literal, TextIO, TypeVar, overload from typing_extensions import deprecated from docutils import TransformSpec, nodes @@ -23,8 +22,9 @@ def check_encoding(stream: TextIO, encoding: str) -> bool | None: ... def error_string(err: BaseException) -> str: ... _S = TypeVar("_S") +_R = TypeVar("_R", default=str) -class Input(TransformSpec, Generic[_S]): +class Input(TransformSpec, Generic[_S, _R]): component_type: ClassVar[str] default_source_path: ClassVar[str | None] encoding: str | None @@ -39,10 +39,11 @@ class Input(TransformSpec, Generic[_S]): encoding: str | None = "utf-8", error_handler: str = "strict", ) -> None: ... - def read(self) -> str: ... + def read(self) -> _R: ... def decode(self, data: str | bytes | bytearray) -> str: ... coding_slug: ClassVar[Pattern[bytes]] byte_order_marks: ClassVar[tuple[tuple[bytes, str], ...]] + @deprecated("Deprecated and will be removed in Docutils 1.0.") def determine_encoding_from_data(self, data: str | bytes | bytearray) -> str | None: ... def isatty(self) -> bool: ... @@ -52,17 +53,23 @@ class Output(TransformSpec): default_destination_path: ClassVar[str | None] encoding: str | None error_handler: str - destination: Incomplete + # A file-like object (`FileOutput`), the output data (`StringOutput`), or `None`. + destination: IO[str] | IO[bytes] | str | bytes | None destination_path: StrPath | None def __init__( self, - destination=None, + destination: IO[str] | IO[bytes] | str | bytes | None = None, destination_path: StrPath | None = None, encoding: str | None = None, error_handler: str | None = "strict", ) -> None: ... - def write(self, data: str) -> Any: ... # returns bytes or str - def encode(self, data: str) -> Any: ... # returns bytes or str + def write(self, data: str | bytes) -> str | bytes | None: ... + + # `str` is encoded to `bytes` unless the output encoding is "unicode". + @overload + def encode(self, data: bytes) -> bytes: ... + @overload + def encode(self, data: str) -> str | bytes: ... class ErrorOutput: destination: SupportsWrite[str] | SupportsWrite[bytes] | Literal[False] @@ -84,7 +91,7 @@ class FileInput(Input[IO[str]]): autoclose: bool def __init__( self, - source=None, + source: IO[str] | None = None, source_path: StrPath | None = None, encoding: str | None = "utf-8", error_handler: str | None = "strict", @@ -100,9 +107,10 @@ class FileOutput(Output): mode: ClassVar[OpenTextModeWriting | OpenBinaryModeWriting] opened: bool autoclose: bool + destination: IO[str] | IO[bytes] | None def __init__( self, - destination=None, + destination: IO[str] | IO[bytes] | None = None, destination_path: StrPath | None = None, encoding: str | None = None, error_handler: str | None = "strict", @@ -114,8 +122,18 @@ class FileOutput(Output): def write(self, data: str | bytes) -> str | bytes: ... def close(self) -> None: ... -@deprecated("The `BinaryFileOutput` is deprecated by `FileOutput` and will be removed in Docutils 0.24.") -class BinaryFileOutput(FileOutput): ... +class BinaryFileOutput(FileOutput): + @deprecated("The `BinaryFileOutput` is deprecated by `FileOutput` and will be removed in Docutils 0.24.") + def __init__( + self, + destination: IO[str] | IO[bytes] | None = None, + destination_path: StrPath | None = None, + encoding: str | None = None, + error_handler: str | None = "strict", + autoclose: bool = True, + handle_io_errors: None = None, + mode: OpenTextModeWriting | OpenBinaryModeWriting | None = None, + ) -> None: ... class StringInput(Input[str]): default_source_path: ClassVar[str] @@ -123,17 +141,19 @@ class StringInput(Input[str]): class StringOutput(Output): default_destination_path: ClassVar[str] - destination: str | bytes # only defined after call to write() + # Only defined after a call to write(). + destination: str | bytes def write(self, data: str | bytes) -> str | bytes: ... -class NullInput(Input[Any]): +class NullInput(Input[None, str]): default_source_path: ClassVar[str] def read(self) -> str: ... class NullOutput(Output): default_destination_path: ClassVar[str] + destination: None def write(self, data: Unused) -> None: ... -class DocTreeInput(Input[nodes.document]): +class DocTreeInput(Input[nodes.document, nodes.document]): default_source_path: ClassVar[str] - def read(self): ... + def read(self) -> nodes.document: ... diff --git a/stubs/docutils/docutils/languages/__init__.pyi b/stubs/docutils/docutils/languages/__init__.pyi index 415e42286a17..3cf3dffa64ff 100644 --- a/stubs/docutils/docutils/languages/__init__.pyi +++ b/stubs/docutils/docutils/languages/__init__.pyi @@ -1,25 +1,31 @@ -from typing import ClassVar, Final, Protocol, type_check_only -from typing_extensions import Self +from types import ModuleType +from typing import ClassVar, Final, Generic, Protocol, type_check_only +from typing_extensions import TypeVar from docutils.utils import Reporter __docformat__: Final = "reStructuredText" @type_check_only -class _LanguageModule(Protocol): +class LanguageModule(Protocol): + __name__: str labels: dict[str, str] + bibliographic_fields: dict[str, str] author_separators: list[str] - bibliographic_fields: list[str] -class LanguageImporter: +_ModuleT = TypeVar("_ModuleT", default=LanguageModule) +# The result of `__call__()`: the module type, or `_ModuleT | None` for importers without a fallback language. +_ResultT = TypeVar("_ResultT", default=_ModuleT) + +# Not actually generic at runtime, but it does support subscription via `__class_getitem__`. +class LanguageImporter(Generic[_ModuleT, _ResultT]): packages: ClassVar[tuple[str, ...]] warn_msg: ClassVar[str] - fallback: ClassVar[str] - cache: dict[str, _LanguageModule] + fallback: ClassVar[str | None] + cache: dict[str, _ModuleT] def __init__(self) -> None: ... - def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _LanguageModule: ... - def check_content(self, module: _LanguageModule) -> None: ... - def __call__(self, language_code: str, reporter: Reporter | None = None) -> _LanguageModule: ... - def __class_getitem__(cls, name) -> type[Self]: ... + def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _ModuleT | None: ... + def check_content(self, module: _ModuleT | ModuleType) -> None: ... + def __call__(self, language_code: str, reporter: Reporter | None = None) -> _ResultT: ... -get_language: LanguageImporter +get_language: LanguageImporter[LanguageModule] diff --git a/stubs/docutils/docutils/languages/af.pyi b/stubs/docutils/docutils/languages/af.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/af.pyi +++ b/stubs/docutils/docutils/languages/af.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ar.pyi b/stubs/docutils/docutils/languages/ar.pyi index ea6236c81970..1523a42daa07 100644 --- a/stubs/docutils/docutils/languages/ar.pyi +++ b/stubs/docutils/docutils/languages/ar.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal["؛", "،"]] +author_separators: list[str | Literal["؛", "،"]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ca.pyi b/stubs/docutils/docutils/languages/ca.pyi index 1bc1c23e214b..1523a42daa07 100644 --- a/stubs/docutils/docutils/languages/ca.pyi +++ b/stubs/docutils/docutils/languages/ca.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal["؛", "،"]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/cs.pyi b/stubs/docutils/docutils/languages/cs.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/cs.pyi +++ b/stubs/docutils/docutils/languages/cs.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/da.pyi b/stubs/docutils/docutils/languages/da.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/da.pyi +++ b/stubs/docutils/docutils/languages/da.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/de.pyi b/stubs/docutils/docutils/languages/de.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/de.pyi +++ b/stubs/docutils/docutils/languages/de.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/en.pyi b/stubs/docutils/docutils/languages/en.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/en.pyi +++ b/stubs/docutils/docutils/languages/en.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/eo.pyi b/stubs/docutils/docutils/languages/eo.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/eo.pyi +++ b/stubs/docutils/docutils/languages/eo.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/es.pyi b/stubs/docutils/docutils/languages/es.pyi index 67f306e26583..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/es.pyi +++ b/stubs/docutils/docutils/languages/es.pyi @@ -1,6 +1,7 @@ -from _typeshed import Incomplete +from typing import Final, Literal -__docformat__: str -labels: Incomplete -bibliographic_fields: Incomplete -author_separators: Incomplete +__docformat__: Final = "reStructuredText" + +labels: dict[str, str] +bibliographic_fields: dict[str, str] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/fa.pyi b/stubs/docutils/docutils/languages/fa.pyi index ea6236c81970..1523a42daa07 100644 --- a/stubs/docutils/docutils/languages/fa.pyi +++ b/stubs/docutils/docutils/languages/fa.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal["؛", "،"]] +author_separators: list[str | Literal["؛", "،"]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/fi.pyi b/stubs/docutils/docutils/languages/fi.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/fi.pyi +++ b/stubs/docutils/docutils/languages/fi.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/fr.pyi b/stubs/docutils/docutils/languages/fr.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/fr.pyi +++ b/stubs/docutils/docutils/languages/fr.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/gl.pyi b/stubs/docutils/docutils/languages/gl.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/gl.pyi +++ b/stubs/docutils/docutils/languages/gl.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/he.pyi b/stubs/docutils/docutils/languages/he.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/he.pyi +++ b/stubs/docutils/docutils/languages/he.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/it.pyi b/stubs/docutils/docutils/languages/it.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/it.pyi +++ b/stubs/docutils/docutils/languages/it.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ja.pyi b/stubs/docutils/docutils/languages/ja.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/ja.pyi +++ b/stubs/docutils/docutils/languages/ja.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ka.pyi b/stubs/docutils/docutils/languages/ka.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/ka.pyi +++ b/stubs/docutils/docutils/languages/ka.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ko.pyi b/stubs/docutils/docutils/languages/ko.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/ko.pyi +++ b/stubs/docutils/docutils/languages/ko.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/lt.pyi b/stubs/docutils/docutils/languages/lt.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/lt.pyi +++ b/stubs/docutils/docutils/languages/lt.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/lv.pyi b/stubs/docutils/docutils/languages/lv.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/lv.pyi +++ b/stubs/docutils/docutils/languages/lv.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/nl.pyi b/stubs/docutils/docutils/languages/nl.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/nl.pyi +++ b/stubs/docutils/docutils/languages/nl.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/pl.pyi b/stubs/docutils/docutils/languages/pl.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/pl.pyi +++ b/stubs/docutils/docutils/languages/pl.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/pt_br.pyi b/stubs/docutils/docutils/languages/pt_br.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/pt_br.pyi +++ b/stubs/docutils/docutils/languages/pt_br.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/ru.pyi b/stubs/docutils/docutils/languages/ru.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/ru.pyi +++ b/stubs/docutils/docutils/languages/ru.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/sk.pyi b/stubs/docutils/docutils/languages/sk.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/sk.pyi +++ b/stubs/docutils/docutils/languages/sk.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/sv.pyi b/stubs/docutils/docutils/languages/sv.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/sv.pyi +++ b/stubs/docutils/docutils/languages/sv.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/uk.pyi b/stubs/docutils/docutils/languages/uk.pyi index 1bc1c23e214b..7de24863a44c 100644 --- a/stubs/docutils/docutils/languages/uk.pyi +++ b/stubs/docutils/docutils/languages/uk.pyi @@ -1,6 +1,7 @@ from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[Literal[";", ","]] +author_separators: list[str | Literal[";", ","]] # noqa: Y051 diff --git a/stubs/docutils/docutils/languages/zh_cn.pyi b/stubs/docutils/docutils/languages/zh_cn.pyi index 251a17cfe865..f615f2a549f8 100644 --- a/stubs/docutils/docutils/languages/zh_cn.pyi +++ b/stubs/docutils/docutils/languages/zh_cn.pyi @@ -1,6 +1,7 @@ -from typing import Final +from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[str] +author_separators: list[str | Literal[";", ",", "；", "，", "、"]] # noqa: RUF001, Y051 diff --git a/stubs/docutils/docutils/languages/zh_tw.pyi b/stubs/docutils/docutils/languages/zh_tw.pyi index 251a17cfe865..f615f2a549f8 100644 --- a/stubs/docutils/docutils/languages/zh_tw.pyi +++ b/stubs/docutils/docutils/languages/zh_tw.pyi @@ -1,6 +1,7 @@ -from typing import Final +from typing import Final, Literal __docformat__: Final = "reStructuredText" + labels: dict[str, str] bibliographic_fields: dict[str, str] -author_separators: list[str] +author_separators: list[str | Literal[";", ",", "；", "，", "、"]] # noqa: RUF001, Y051 diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 56b49e584f2b..087597e2b028 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -1,6 +1,6 @@ import sys import xml.dom.minidom -from _typeshed import Incomplete, StrPath +from _typeshed import StrPath from abc import abstractmethod from collections import Counter from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence @@ -12,6 +12,16 @@ from docutils.transforms import Transform, Transformer from docutils.utils import Reporter _N = TypeVar("_N", bound=Node) +# TypeVar is used for well-known element attributes with a fixed value type, +# see: . + +# Other attributes (like those that docutils stores with inconsistent types like "auto" or "anonymous") are typed as `Any`. + +# Attributes that are always initialised as lists of strings on every `Element`: +_BasicListAttribute: TypeAlias = Literal["ids", "classes", "names", "dupnames"] +_ListAttribute: TypeAlias = Literal[_BasicListAttribute, "backrefs"] +_StrAttribute: TypeAlias = Literal["refuri", "refid", "refname", "uri", "alt", "format", "xml:space", "title"] +_IntAttribute: TypeAlias = Literal["level", "morecols", "morerows", "cols", "start", "scale", "line"] _ElementLikeType: TypeAlias = type[Element | Text | Body | Bibliographic | Inline] _ContentModelCategory: TypeAlias = _ElementLikeType | tuple[_ElementLikeType, ...] _ContentModelQuantifier: TypeAlias = Literal[".", "?", "+", "*"] @@ -27,12 +37,14 @@ __docformat__: Final = "reStructuredText" # Functional Node Base Classes class Node: - # children is initialized by the subclasses + # `children` is initialized in subclasses. children: Sequence[Node] - # TODO: `parent` is actually `Element | None``, but `None`` only happens rarely, - # i.e. for synthetic nodes (or `document`, where it is overridden). - # See https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#the-any-trick - parent: Element | Any + # `parent` is None` for: + # the root `document`; + # nodes that were never inserted into a tree; + # copies (`copy()`/`deepcopy()`). + # Removing a node does not reset its parent (does not make it None). + parent: Element | None source: str | None line: int | None @@ -45,9 +57,9 @@ class Node: def asdom( self, dom: _DomModule | None = None ) -> xml.dom.minidom.Document | xml.dom.minidom.Element | xml.dom.minidom.Text: ... - # While docutils documents the Node class to be abstract it does not - # actually use the ABCMeta metaclass. We still set @abstractmethod here - # (although it's not used in the docutils implementation) because it + # While docutils' documentation says the Node class is "abstract", it does not actually use the ABCMeta metaclass. + # Setting @abstractmethod here will make type-checkers reject subclasses that leave these required methods unimplemented. + # This is correct regardless of the actual implementation. # makes Mypy reject Node() with "Cannot instantiate abstract class". @abstractmethod def copy(self) -> Self: ... @@ -123,24 +135,21 @@ class Node: def validate(self, recursive: bool = True) -> None: ... def validate_position(self) -> None: ... -# Left out -# - def ensure_str (deprecated) -# - def unescape (canonical import from docutils.utils) def unescape(text: str, restore_backslashes: bool = False, respect_whitespace: bool = False) -> str: ... class Text(Node, str): tagname: ClassVar[str] children: tuple[()] - # we omit the rawsource parameter because it has been deprecated and is ignored + # Omit the rawsource parameter because it is deprecated and ignored. def __new__(cls, data: str) -> Self: ... def shortrepr(self, maxlen: int = 18) -> str: ... def copy(self) -> Self: ... def deepcopy(self) -> Self: ... def pformat(self, indent: str = " ", level: int = 0) -> str: ... def astext(self) -> str: ... - def rstrip(self, chars: str | None = None) -> str: ... - def lstrip(self, chars: str | None = None) -> str: ... + def rstrip(self, chars: str | None = None) -> Self: ... + def lstrip(self, chars: str | None = None) -> Self: ... _T = TypeVar("_T") @@ -157,7 +166,7 @@ class Element(Node): attributes: dict[str, Any] children: list[Node] rawsource: str - def __init__(self, rawsource: str = "", *children: Node, **attributes: Any) -> None: ... + def __init__(self, rawsource: str = "", *children: Node, **attributes: object) -> None: ... def shortrepr(self) -> str: ... def starttag(self, quoteattr: Callable[[str], str] | None = None) -> str: ... def endtag(self) -> str: ... @@ -165,6 +174,12 @@ class Element(Node): def __len__(self) -> int: ... def __contains__(self, key: str | Node) -> bool: ... + @overload + def __getitem__(self, key: _ListAttribute) -> list[str]: ... + @overload + def __getitem__(self, key: _StrAttribute) -> str: ... + @overload + def __getitem__(self, key: _IntAttribute) -> int: ... @overload def __getitem__(self, key: str) -> Any: ... @overload @@ -173,7 +188,7 @@ class Element(Node): def __getitem__(self, key: slice) -> list[Node]: ... @overload - def __setitem__(self, key: str, item: Any) -> None: ... + def __setitem__(self, key: str, item: object) -> None: ... @overload def __setitem__(self, key: int, item: Node) -> None: ... @overload @@ -187,10 +202,24 @@ class Element(Node): def non_default_attributes(self) -> dict[str, Any]: ... def attlist(self) -> list[tuple[str, Any]]: ... + @overload + def get(self, key: _BasicListAttribute, failobj: object = None) -> list[str]: ... + @overload + def get(self, key: Literal["backrefs"]) -> list[str] | None: ... + @overload + def get(self, key: Literal["backrefs"], failobj: _T) -> list[str] | _T: ... + @overload + def get(self, key: _StrAttribute) -> str | None: ... + @overload + def get(self, key: _StrAttribute, failobj: _T) -> str | _T: ... + @overload + def get(self, key: _IntAttribute) -> int | None: ... + @overload + def get(self, key: _IntAttribute, failobj: _T) -> int | _T: ... @overload def get(self, key: str) -> Any: ... @overload - def get(self, key: str, failobj: _T) -> _T: ... + def get(self, key: str, failobj: object) -> Any: ... def hasattr(self, attr: str) -> bool: ... def delattr(self, attr: str) -> None: ... @@ -211,31 +240,31 @@ class Element(Node): def previous_sibling(self) -> Node | None: ... def section_hierarchy(self) -> list[section]: ... def is_not_default(self, key: str) -> bool: ... - def update_basic_atts(self, dict_: Mapping[str, Any] | Node) -> None: ... - def append_attr_list(self, attr: str, values: Iterable[Any]) -> None: ... - def coerce_append_attr_list(self, attr: str, value) -> None: ... - def replace_attr(self, attr: str, value: Any, force: bool = True) -> None: ... - def copy_attr_convert(self, attr: str, value: Any, replace: bool = True) -> None: ... - def copy_attr_coerce(self, attr: str, value: Any, replace: bool) -> None: ... - def copy_attr_concatenate(self, attr: str, value: Any, replace: bool) -> None: ... - def copy_attr_consistent(self, attr: str, value: Any, replace: bool) -> None: ... + def update_basic_atts(self, dict_: Mapping[str, object] | Node) -> None: ... + def append_attr_list(self, attr: str, values: Iterable[object]) -> None: ... + def coerce_append_attr_list(self, attr: str, value: object) -> None: ... + def replace_attr(self, attr: str, value: object, force: bool = True) -> None: ... + def copy_attr_convert(self, attr: str, value: object, replace: bool = True) -> None: ... + def copy_attr_coerce(self, attr: str, value: object, replace: bool) -> None: ... + def copy_attr_concatenate(self, attr: str, value: object, replace: bool) -> None: ... + def copy_attr_consistent(self, attr: str, value: object, replace: bool) -> None: ... def update_all_atts( self, - dict_: Mapping[str, Any] | Node, - update_fun: Callable[[Element, str, Any, bool], object] = ..., + dict_: Mapping[str, object] | Node, + update_fun: Callable[[Element, str, Any, bool], object] = ..., # an unbound `Element.copy_attr_*` method replace: bool = True, and_source: bool = False, ) -> None: ... def update_all_atts_consistantly( - self, dict_: Mapping[str, Any] | Node, replace: bool = True, and_source: bool = False + self, dict_: Mapping[str, object] | Node, replace: bool = True, and_source: bool = False ) -> None: ... def update_all_atts_concatenating( - self, dict_: dict[str, Any] | Node, replace: bool = True, and_source: bool = False + self, dict_: Mapping[str, object] | Node, replace: bool = True, and_source: bool = False ) -> None: ... def update_all_atts_coercion( - self, dict_: Mapping[str, Any] | Node, replace: bool = True, and_source: bool = False + self, dict_: Mapping[str, object] | Node, replace: bool = True, and_source: bool = False ) -> None: ... - def update_all_atts_convert(self, dict_: Mapping[str, Any] | Node, and_source: bool = False) -> None: ... + def update_all_atts_convert(self, dict_: Mapping[str, object] | Node, and_source: bool = False) -> None: ... def clear(self) -> None: ... def replace(self, old: Node, new: Node | Sequence[Node]) -> None: ... def replace_self(self, new: Node | Sequence[Node]) -> None: ... @@ -254,16 +283,15 @@ class Element(Node): @classmethod def is_not_known_attribute(cls, attr: str) -> bool: ... def validate_attributes(self) -> None: ... - def validate_content( - self, model: _ContentModelTuple | None = None, elements: Sequence[Incomplete] | None = None - ) -> list[Incomplete]: ... + def validate_content(self, model: _ContentModelTuple | None = None, elements: Sequence[Node] | None = None) -> list[Node]: ... # '__iter__' is added as workaround, since mypy doesn't support classes that are iterable via '__getitem__' # see https://github.com/python/typeshed/pull/10099#issuecomment-1528789395 + @type_check_only def __iter__(self) -> Iterator[Node]: ... class TextElement(Element): - def __init__(self, rawsource: str = "", text: str = "", *children: Node, **attributes) -> None: ... + def __init__(self, rawsource: str = "", text: str = "", *children: Node, **attributes: object) -> None: ... class FixedTextElement(TextElement): ... class PureTextElement(TextElement): ... @@ -271,7 +299,7 @@ class PureTextElement(TextElement): ... # Mixins class Resolvable: - resolved: int + resolved: bool class BackLinkable: list_attributes: ClassVar[Sequence[str]] @@ -285,7 +313,7 @@ class Titular: ... class PreBibliographic: ... class Bibliographic: ... -class Decorative(PreBibliographic): +class Decorative: content_model: ClassVar[_ContentModelTuple] class Structural: ... @@ -298,7 +326,7 @@ class Admonition(Body): content_model: ClassVar[_ContentModelTuple] class Special(Body): ... -class Invisible(PreBibliographic): ... +class Invisible(Special, PreBibliographic): ... class Part: ... class Inline: ... class Referential(Resolvable): ... @@ -314,7 +342,8 @@ class Labeled: ... _Document: TypeAlias = document _Decoration: TypeAlias = decoration -class document(Root, Structural, Element): +class document(Root, Element): + parent: None # the root of the tree current_source: str | None current_line: int | None settings: Values @@ -342,11 +371,11 @@ class document(Root, Structural, Element): parse_messages: list[system_message] transform_messages: list[system_message] transformer: Transformer - include_log: list[tuple[StrPath, tuple[Incomplete, ...]]] + include_log: list[tuple[StrPath, tuple[int | None, int | None, str | None, str | None]]] decoration: decoration | None document: Self - def __init__(self, settings: Values, reporter: Reporter, *args: Node, **kwargs: Any) -> None: ... - def asdom(self, dom: Any | None = None) -> Any: ... + def __init__(self, settings: Values, reporter: Reporter, *args: Node, **kwargs: object) -> None: ... + def asdom(self, dom: _DomModule | None = None) -> xml.dom.minidom.Document: ... def set_id(self, node: Element, msgnode: Element | None = None, suggested_prefix: str = "") -> str: ... def create_id(self, node: Element, suggested_prefix: str = "") -> str: ... @deprecated("`nodes.document.set_name_id_map()` will be removed in Docutils 1.0.") @@ -373,23 +402,23 @@ class document(Root, Structural, Element): def note_pending(self, pending: pending, priority: int | None = None) -> None: ... def note_parse_message(self, message: system_message) -> None: ... def note_transform_message(self, message: system_message) -> None: ... - def note_source(self, source: str, offset: int) -> None: ... + def note_source(self, source: StrPath | None, offset: int | None) -> None: ... def copy(self) -> Self: ... def get_decoration(self) -> _Decoration: ... # Title Elements -class title(Titular, PreBibliographic, TextElement): ... -class subtitle(Titular, PreBibliographic, TextElement): ... -class rubric(Titular, TextElement): ... +class title(Titular, PreBibliographic, SubStructural, TextElement): ... +class subtitle(Titular, PreBibliographic, SubStructural, TextElement): ... +class rubric(Titular, General, TextElement): ... # Meta-Data Element -class meta(PreBibliographic, Element): ... +class meta(PreBibliographic, SubStructural, Element): ... # Bibliographic Elements -class docinfo(Bibliographic, Element): ... +class docinfo(SubStructural, Element): ... class author(Bibliographic, TextElement): ... class authors(Bibliographic, Element): ... class organization(Bibliographic, TextElement): ... @@ -403,7 +432,7 @@ class copyright(Bibliographic, TextElement): ... # Decorative Elements -class decoration(Decorative, Element): +class decoration(PreBibliographic, SubStructural, Element): def get_header(self) -> header: ... def get_footer(self) -> footer: ... @@ -416,7 +445,7 @@ class section(Structural, Element): ... class topic(Structural, Element): ... class sidebar(Structural, Element): ... -class transition(Structural, Element): +class transition(SubStructural, Element): ignored_siblings: ClassVar[tuple[type[Element], ...]] # Body Elements @@ -434,19 +463,19 @@ class term(Part, TextElement): ... class classifier(Part, TextElement): ... class definition(Part, Element): ... class field_list(Sequential, Element): ... -class field(Part, Element): ... +class field(Part, Bibliographic, Element): ... class field_name(Part, TextElement): ... class field_body(Part, Element): ... class option(Part, Element): ... -class option_argument(Part, TextElement): ... +class option_argument(Part, PureTextElement): ... class option_group(Part, Element): ... class option_list(Sequential, Element): ... class option_list_item(Part, Element): ... -class option_string(Part, TextElement): ... +class option_string(Part, PureTextElement): ... class description(Part, Element): ... class literal_block(General, FixedTextElement): ... class doctest_block(General, FixedTextElement): ... -class math_block(General, FixedTextElement): ... +class math_block(General, FixedTextElement, PureTextElement): ... class line_block(General, Element): ... class line(Part, TextElement): @@ -464,12 +493,12 @@ class tip(Admonition, Element): ... class hint(Admonition, Element): ... class warning(Admonition, Element): ... class admonition(Admonition, Element): ... -class comment(Special, Invisible, FixedTextElement): ... -class substitution_definition(Special, Invisible, TextElement): ... -class target(Special, Invisible, Inline, TextElement, Targetable): ... +class comment(Invisible, FixedTextElement, PureTextElement): ... +class substitution_definition(Invisible, TextElement): ... +class target(Invisible, Inline, TextElement, Targetable): ... class footnote(General, BackLinkable, Element, Labeled, Targetable): ... class citation(General, BackLinkable, Element, Labeled, Targetable): ... -class label(Part, TextElement): ... +class label(Part, PureTextElement): ... class figure(General, Element): ... class caption(Part, TextElement): ... class legend(Part, Element): ... @@ -477,7 +506,7 @@ class table(General, Element): ... class tgroup(Part, Element): ... class colspec(Part, Element): - def propwidth(self) -> float: ... + def propwidth(self) -> int | float: ... class thead(Part, Element): ... class tbody(Part, Element): ... @@ -485,22 +514,22 @@ class row(Part, Element): ... class entry(Part, Element): ... class system_message(Special, BackLinkable, PreBibliographic, Element): - def __init__(self, message: str | None = None, *children: Node, **attributes) -> None: ... + def __init__(self, message: str | None = None, *children: Node, **attributes: object) -> None: ... def astext(self) -> str: ... -class pending(Special, Invisible, Element): +class pending(Invisible, Element): transform: type[Transform] details: Mapping[str, Any] def __init__( self, transform: type[Transform], - details: Mapping[str, Any] | None = None, + details: Mapping[str, object] | None = None, rawsource: str = "", *children: Node, - **attributes, + **attributes: object, ) -> None: ... -class raw(Special, Inline, PreBibliographic, FixedTextElement): ... +class raw(Special, Inline, PreBibliographic, FixedTextElement, PureTextElement): ... # Inline Elements @@ -508,15 +537,15 @@ class emphasis(Inline, TextElement): ... class strong(Inline, TextElement): ... class literal(Inline, TextElement): ... class reference(General, Inline, Referential, TextElement): ... -class footnote_reference(Inline, Referential, TextElement): ... -class citation_reference(Inline, Referential, TextElement): ... +class footnote_reference(Inline, Referential, PureTextElement): ... +class citation_reference(Inline, Referential, PureTextElement): ... class substitution_reference(Inline, TextElement): ... class title_reference(Inline, TextElement): ... class abbreviation(Inline, TextElement): ... class acronym(Inline, TextElement): ... class superscript(Inline, TextElement): ... class subscript(Inline, TextElement): ... -class math(Inline, TextElement): ... +class math(Inline, PureTextElement): ... class image(General, Inline, Element): ... class inline(Inline, TextElement): ... class problematic(Inline, TextElement): ... @@ -530,219 +559,814 @@ class NodeVisitor: optional: ClassVar[tuple[str, ...]] document: _Document def __init__(self, document: _Document) -> None: ... - def dispatch_visit(self, node: Node) -> Any: ... - def dispatch_departure(self, node: Node) -> Any: ... - def unknown_visit(self, node: Node) -> Any: ... - def unknown_departure(self, node: Node) -> Any: ... - - # These methods only exist on the subclasses `GenericNodeVisitor` and `SparseNodeVisitor` at runtime. - # If subclassing `NodeVisitor` directly, `visit_*` methods must be implemented for nodes and children that will be called - # with `Node.walk()` and `Node.walkabout()`. - # `depart_*` methods must also be implemented for nodes and children that will be called with `Node.walkabout()`. - def visit_Text(self, node: Text) -> Any: ... - def visit_abbreviation(self, node: abbreviation) -> Any: ... - def visit_acronym(self, node: acronym) -> Any: ... - def visit_address(self, node: address) -> Any: ... - def visit_admonition(self, node: admonition) -> Any: ... - def visit_attention(self, node: attention) -> Any: ... - def visit_attribution(self, node: attribution) -> Any: ... - def visit_author(self, node: author) -> Any: ... - def visit_authors(self, node: authors) -> Any: ... - def visit_block_quote(self, node: block_quote) -> Any: ... - def visit_bullet_list(self, node: bullet_list) -> Any: ... - def visit_caption(self, node: caption) -> Any: ... - def visit_caution(self, node: caution) -> Any: ... - def visit_citation(self, node: citation) -> Any: ... - def visit_citation_reference(self, node: citation_reference) -> Any: ... - def visit_classifier(self, node: classifier) -> Any: ... - def visit_colspec(self, node: colspec) -> Any: ... - def visit_comment(self, node: comment) -> Any: ... - def visit_compound(self, node: compound) -> Any: ... - def visit_contact(self, node: contact) -> Any: ... - def visit_container(self, node: container) -> Any: ... - def visit_copyright(self, node: copyright) -> Any: ... - def visit_danger(self, node: danger) -> Any: ... - def visit_date(self, node: date) -> Any: ... - def visit_decoration(self, node: decoration) -> Any: ... - def visit_definition(self, node: definition) -> Any: ... - def visit_definition_list(self, node: definition_list) -> Any: ... - def visit_definition_list_item(self, node: definition_list_item) -> Any: ... - def visit_description(self, node: description) -> Any: ... - def visit_docinfo(self, node: docinfo) -> Any: ... - def visit_doctest_block(self, node: doctest_block) -> Any: ... - def visit_document(self, node: _Document) -> Any: ... - def visit_emphasis(self, node: emphasis) -> Any: ... - def visit_entry(self, node: entry) -> Any: ... - def visit_enumerated_list(self, node: enumerated_list) -> Any: ... - def visit_error(self, node: error) -> Any: ... - def visit_field(self, node: field) -> Any: ... - def visit_field_body(self, node: field_body) -> Any: ... - def visit_field_list(self, node: field_list) -> Any: ... - def visit_field_name(self, node: field_name) -> Any: ... - def visit_figure(self, node: figure) -> Any: ... - def visit_footer(self, node: footer) -> Any: ... - def visit_footnote(self, node: footnote) -> Any: ... - def visit_footnote_reference(self, node: footnote_reference) -> Any: ... - def visit_generated(self, node: generated) -> Any: ... - def visit_header(self, node: header) -> Any: ... - def visit_hint(self, node: hint) -> Any: ... - def visit_image(self, node: image) -> Any: ... - def visit_important(self, node: important) -> Any: ... - def visit_inline(self, node: inline) -> Any: ... - def visit_label(self, node: label) -> Any: ... - def visit_legend(self, node: legend) -> Any: ... - def visit_line(self, node: line) -> Any: ... - def visit_line_block(self, node: line_block) -> Any: ... - def visit_list_item(self, node: list_item) -> Any: ... - def visit_literal(self, node: literal) -> Any: ... - def visit_literal_block(self, node: literal_block) -> Any: ... - def visit_math(self, node: math) -> Any: ... - def visit_math_block(self, node: math_block) -> Any: ... - def visit_meta(self, node: meta) -> Any: ... - def visit_note(self, node: note) -> Any: ... - def visit_option(self, node: option) -> Any: ... - def visit_option_argument(self, node: option_argument) -> Any: ... - def visit_option_group(self, node: option_group) -> Any: ... - def visit_option_list(self, node: option_list) -> Any: ... - def visit_option_list_item(self, node: option_list_item) -> Any: ... - def visit_option_string(self, node: option_string) -> Any: ... - def visit_organization(self, node: organization) -> Any: ... - def visit_paragraph(self, node: paragraph) -> Any: ... - def visit_pending(self, node: pending) -> Any: ... - def visit_problematic(self, node: problematic) -> Any: ... - def visit_raw(self, node: raw) -> Any: ... - def visit_reference(self, node: reference) -> Any: ... - def visit_revision(self, node: revision) -> Any: ... - def visit_row(self, node: row) -> Any: ... - def visit_rubric(self, node: rubric) -> Any: ... - def visit_section(self, node: section) -> Any: ... - def visit_sidebar(self, node: sidebar) -> Any: ... - def visit_status(self, node: status) -> Any: ... - def visit_strong(self, node: strong) -> Any: ... - def visit_subscript(self, node: subscript) -> Any: ... - def visit_substitution_definition(self, node: substitution_definition) -> Any: ... - def visit_substitution_reference(self, node: substitution_reference) -> Any: ... - def visit_subtitle(self, node: subtitle) -> Any: ... - def visit_superscript(self, node: superscript) -> Any: ... - def visit_system_message(self, node: system_message) -> Any: ... - def visit_table(self, node: table) -> Any: ... - def visit_target(self, node: target) -> Any: ... - def visit_tbody(self, node: tbody) -> Any: ... - def visit_term(self, node: term) -> Any: ... - def visit_tgroup(self, node: tgroup) -> Any: ... - def visit_thead(self, node: thead) -> Any: ... - def visit_tip(self, node: tip) -> Any: ... - def visit_title(self, node: title) -> Any: ... - def visit_title_reference(self, node: title_reference) -> Any: ... - def visit_topic(self, node: topic) -> Any: ... - def visit_transition(self, node: transition) -> Any: ... - def visit_version(self, node: version) -> Any: ... - def visit_warning(self, node: warning) -> Any: ... - def depart_Text(self, node: Text) -> Any: ... - def depart_abbreviation(self, node: abbreviation) -> Any: ... - def depart_acronym(self, node: acronym) -> Any: ... - def depart_address(self, node: address) -> Any: ... - def depart_admonition(self, node: admonition) -> Any: ... - def depart_attention(self, node: attention) -> Any: ... - def depart_attribution(self, node: attribution) -> Any: ... - def depart_author(self, node: author) -> Any: ... - def depart_authors(self, node: authors) -> Any: ... - def depart_block_quote(self, node: block_quote) -> Any: ... - def depart_bullet_list(self, node: bullet_list) -> Any: ... - def depart_caption(self, node: caption) -> Any: ... - def depart_caution(self, node: caution) -> Any: ... - def depart_citation(self, node: citation) -> Any: ... - def depart_citation_reference(self, node: citation_reference) -> Any: ... - def depart_classifier(self, node: classifier) -> Any: ... - def depart_colspec(self, node: colspec) -> Any: ... - def depart_comment(self, node: comment) -> Any: ... - def depart_compound(self, node: compound) -> Any: ... - def depart_contact(self, node: contact) -> Any: ... - def depart_container(self, node: container) -> Any: ... - def depart_copyright(self, node: copyright) -> Any: ... - def depart_danger(self, node: danger) -> Any: ... - def depart_date(self, node: date) -> Any: ... - def depart_decoration(self, node: decoration) -> Any: ... - def depart_definition(self, node: definition) -> Any: ... - def depart_definition_list(self, node: definition_list) -> Any: ... - def depart_definition_list_item(self, node: definition_list_item) -> Any: ... - def depart_description(self, node: description) -> Any: ... - def depart_docinfo(self, node: docinfo) -> Any: ... - def depart_doctest_block(self, node: doctest_block) -> Any: ... - def depart_document(self, node: _Document) -> Any: ... - def depart_emphasis(self, node: emphasis) -> Any: ... - def depart_entry(self, node: entry) -> Any: ... - def depart_enumerated_list(self, node: enumerated_list) -> Any: ... - def depart_error(self, node: error) -> Any: ... - def depart_field(self, node: field) -> Any: ... - def depart_field_body(self, node: field_body) -> Any: ... - def depart_field_list(self, node: field_list) -> Any: ... - def depart_field_name(self, node: field_name) -> Any: ... - def depart_figure(self, node: figure) -> Any: ... - def depart_footer(self, node: footer) -> Any: ... - def depart_footnote(self, node: footnote) -> Any: ... - def depart_footnote_reference(self, node: footnote_reference) -> Any: ... - def depart_generated(self, node: generated) -> Any: ... - def depart_header(self, node: header) -> Any: ... - def depart_hint(self, node: hint) -> Any: ... - def depart_image(self, node: image) -> Any: ... - def depart_important(self, node: important) -> Any: ... - def depart_inline(self, node: inline) -> Any: ... - def depart_label(self, node: label) -> Any: ... - def depart_legend(self, node: legend) -> Any: ... - def depart_line(self, node: line) -> Any: ... - def depart_line_block(self, node: line_block) -> Any: ... - def depart_list_item(self, node: list_item) -> Any: ... - def depart_literal(self, node: literal) -> Any: ... - def depart_literal_block(self, node: literal_block) -> Any: ... - def depart_math(self, node: math) -> Any: ... - def depart_math_block(self, node: math_block) -> Any: ... - def depart_meta(self, node: meta) -> Any: ... - def depart_note(self, node: note) -> Any: ... - def depart_option(self, node: option) -> Any: ... - def depart_option_argument(self, node: option_argument) -> Any: ... - def depart_option_group(self, node: option_group) -> Any: ... - def depart_option_list(self, node: option_list) -> Any: ... - def depart_option_list_item(self, node: option_list_item) -> Any: ... - def depart_option_string(self, node: option_string) -> Any: ... - def depart_organization(self, node: organization) -> Any: ... - def depart_paragraph(self, node: paragraph) -> Any: ... - def depart_pending(self, node: pending) -> Any: ... - def depart_problematic(self, node: problematic) -> Any: ... - def depart_raw(self, node: raw) -> Any: ... - def depart_reference(self, node: reference) -> Any: ... - def depart_revision(self, node: revision) -> Any: ... - def depart_row(self, node: row) -> Any: ... - def depart_rubric(self, node: rubric) -> Any: ... - def depart_section(self, node: section) -> Any: ... - def depart_sidebar(self, node: sidebar) -> Any: ... - def depart_status(self, node: status) -> Any: ... - def depart_strong(self, node: strong) -> Any: ... - def depart_subscript(self, node: subscript) -> Any: ... - def depart_substitution_definition(self, node: substitution_definition) -> Any: ... - def depart_substitution_reference(self, node: substitution_reference) -> Any: ... - def depart_subtitle(self, node: subtitle) -> Any: ... - def depart_superscript(self, node: superscript) -> Any: ... - def depart_system_message(self, node: system_message) -> Any: ... - def depart_table(self, node: table) -> Any: ... - def depart_target(self, node: target) -> Any: ... - def depart_tbody(self, node: tbody) -> Any: ... - def depart_term(self, node: term) -> Any: ... - def depart_tgroup(self, node: tgroup) -> Any: ... - def depart_thead(self, node: thead) -> Any: ... - def depart_tip(self, node: tip) -> Any: ... - def depart_title(self, node: title) -> Any: ... - def depart_title_reference(self, node: title_reference) -> Any: ... - def depart_topic(self, node: topic) -> Any: ... - def depart_transition(self, node: transition) -> Any: ... - def depart_version(self, node: version) -> Any: ... - def depart_warning(self, node: warning) -> Any: ... - -class SparseNodeVisitor(NodeVisitor): ... + def dispatch_visit(self, node: Node) -> object | None: ... + def dispatch_departure(self, node: Node) -> object | None: ... + def unknown_visit(self, node: Node) -> object | None: ... + def unknown_departure(self, node: Node) -> object | None: ... + + # These methods don't exist on `NodeVisitor` at runtime (only on `GenericNodeVisitor` and + # `SparseNodeVisitor`); they declare which methods subclasses can define, and their node types. + # When subclassing `NodeVisitor` directly, `visit_*` methods must be implemented for all nodes + # visited with `Node.walk()` and `Node.walkabout()`, and `depart_*` methods for all nodes + # visited with `Node.walkabout()`. + @type_check_only + def visit_Text(self, node: Text) -> object | None: ... + @type_check_only + def visit_abbreviation(self, node: abbreviation) -> object | None: ... + @type_check_only + def visit_acronym(self, node: acronym) -> object | None: ... + @type_check_only + def visit_address(self, node: address) -> object | None: ... + @type_check_only + def visit_admonition(self, node: admonition) -> object | None: ... + @type_check_only + def visit_attention(self, node: attention) -> object | None: ... + @type_check_only + def visit_attribution(self, node: attribution) -> object | None: ... + @type_check_only + def visit_author(self, node: author) -> object | None: ... + @type_check_only + def visit_authors(self, node: authors) -> object | None: ... + @type_check_only + def visit_block_quote(self, node: block_quote) -> object | None: ... + @type_check_only + def visit_bullet_list(self, node: bullet_list) -> object | None: ... + @type_check_only + def visit_caption(self, node: caption) -> object | None: ... + @type_check_only + def visit_caution(self, node: caution) -> object | None: ... + @type_check_only + def visit_citation(self, node: citation) -> object | None: ... + @type_check_only + def visit_citation_reference(self, node: citation_reference) -> object | None: ... + @type_check_only + def visit_classifier(self, node: classifier) -> object | None: ... + @type_check_only + def visit_colspec(self, node: colspec) -> object | None: ... + @type_check_only + def visit_comment(self, node: comment) -> object | None: ... + @type_check_only + def visit_compound(self, node: compound) -> object | None: ... + @type_check_only + def visit_contact(self, node: contact) -> object | None: ... + @type_check_only + def visit_container(self, node: container) -> object | None: ... + @type_check_only + def visit_copyright(self, node: copyright) -> object | None: ... + @type_check_only + def visit_danger(self, node: danger) -> object | None: ... + @type_check_only + def visit_date(self, node: date) -> object | None: ... + @type_check_only + def visit_decoration(self, node: decoration) -> object | None: ... + @type_check_only + def visit_definition(self, node: definition) -> object | None: ... + @type_check_only + def visit_definition_list(self, node: definition_list) -> object | None: ... + @type_check_only + def visit_definition_list_item(self, node: definition_list_item) -> object | None: ... + @type_check_only + def visit_description(self, node: description) -> object | None: ... + @type_check_only + def visit_docinfo(self, node: docinfo) -> object | None: ... + @type_check_only + def visit_doctest_block(self, node: doctest_block) -> object | None: ... + @type_check_only + def visit_document(self, node: _Document) -> object | None: ... + @type_check_only + def visit_emphasis(self, node: emphasis) -> object | None: ... + @type_check_only + def visit_entry(self, node: entry) -> object | None: ... + @type_check_only + def visit_enumerated_list(self, node: enumerated_list) -> object | None: ... + @type_check_only + def visit_error(self, node: error) -> object | None: ... + @type_check_only + def visit_field(self, node: field) -> object | None: ... + @type_check_only + def visit_field_body(self, node: field_body) -> object | None: ... + @type_check_only + def visit_field_list(self, node: field_list) -> object | None: ... + @type_check_only + def visit_field_name(self, node: field_name) -> object | None: ... + @type_check_only + def visit_figure(self, node: figure) -> object | None: ... + @type_check_only + def visit_footer(self, node: footer) -> object | None: ... + @type_check_only + def visit_footnote(self, node: footnote) -> object | None: ... + @type_check_only + def visit_footnote_reference(self, node: footnote_reference) -> object | None: ... + @type_check_only + def visit_generated(self, node: generated) -> object | None: ... + @type_check_only + def visit_header(self, node: header) -> object | None: ... + @type_check_only + def visit_hint(self, node: hint) -> object | None: ... + @type_check_only + def visit_image(self, node: image) -> object | None: ... + @type_check_only + def visit_important(self, node: important) -> object | None: ... + @type_check_only + def visit_inline(self, node: inline) -> object | None: ... + @type_check_only + def visit_label(self, node: label) -> object | None: ... + @type_check_only + def visit_legend(self, node: legend) -> object | None: ... + @type_check_only + def visit_line(self, node: line) -> object | None: ... + @type_check_only + def visit_line_block(self, node: line_block) -> object | None: ... + @type_check_only + def visit_list_item(self, node: list_item) -> object | None: ... + @type_check_only + def visit_literal(self, node: literal) -> object | None: ... + @type_check_only + def visit_literal_block(self, node: literal_block) -> object | None: ... + @type_check_only + def visit_math(self, node: math) -> object | None: ... + @type_check_only + def visit_math_block(self, node: math_block) -> object | None: ... + @type_check_only + def visit_meta(self, node: meta) -> object | None: ... + @type_check_only + def visit_note(self, node: note) -> object | None: ... + @type_check_only + def visit_option(self, node: option) -> object | None: ... + @type_check_only + def visit_option_argument(self, node: option_argument) -> object | None: ... + @type_check_only + def visit_option_group(self, node: option_group) -> object | None: ... + @type_check_only + def visit_option_list(self, node: option_list) -> object | None: ... + @type_check_only + def visit_option_list_item(self, node: option_list_item) -> object | None: ... + @type_check_only + def visit_option_string(self, node: option_string) -> object | None: ... + @type_check_only + def visit_organization(self, node: organization) -> object | None: ... + @type_check_only + def visit_paragraph(self, node: paragraph) -> object | None: ... + @type_check_only + def visit_pending(self, node: pending) -> object | None: ... + @type_check_only + def visit_problematic(self, node: problematic) -> object | None: ... + @type_check_only + def visit_raw(self, node: raw) -> object | None: ... + @type_check_only + def visit_reference(self, node: reference) -> object | None: ... + @type_check_only + def visit_revision(self, node: revision) -> object | None: ... + @type_check_only + def visit_row(self, node: row) -> object | None: ... + @type_check_only + def visit_rubric(self, node: rubric) -> object | None: ... + @type_check_only + def visit_section(self, node: section) -> object | None: ... + @type_check_only + def visit_sidebar(self, node: sidebar) -> object | None: ... + @type_check_only + def visit_status(self, node: status) -> object | None: ... + @type_check_only + def visit_strong(self, node: strong) -> object | None: ... + @type_check_only + def visit_subscript(self, node: subscript) -> object | None: ... + @type_check_only + def visit_substitution_definition(self, node: substitution_definition) -> object | None: ... + @type_check_only + def visit_substitution_reference(self, node: substitution_reference) -> object | None: ... + @type_check_only + def visit_subtitle(self, node: subtitle) -> object | None: ... + @type_check_only + def visit_superscript(self, node: superscript) -> object | None: ... + @type_check_only + def visit_system_message(self, node: system_message) -> object | None: ... + @type_check_only + def visit_table(self, node: table) -> object | None: ... + @type_check_only + def visit_target(self, node: target) -> object | None: ... + @type_check_only + def visit_tbody(self, node: tbody) -> object | None: ... + @type_check_only + def visit_term(self, node: term) -> object | None: ... + @type_check_only + def visit_tgroup(self, node: tgroup) -> object | None: ... + @type_check_only + def visit_thead(self, node: thead) -> object | None: ... + @type_check_only + def visit_tip(self, node: tip) -> object | None: ... + @type_check_only + def visit_title(self, node: title) -> object | None: ... + @type_check_only + def visit_title_reference(self, node: title_reference) -> object | None: ... + @type_check_only + def visit_topic(self, node: topic) -> object | None: ... + @type_check_only + def visit_transition(self, node: transition) -> object | None: ... + @type_check_only + def visit_version(self, node: version) -> object | None: ... + @type_check_only + def visit_warning(self, node: warning) -> object | None: ... + @type_check_only + def depart_Text(self, node: Text) -> object | None: ... + @type_check_only + def depart_abbreviation(self, node: abbreviation) -> object | None: ... + @type_check_only + def depart_acronym(self, node: acronym) -> object | None: ... + @type_check_only + def depart_address(self, node: address) -> object | None: ... + @type_check_only + def depart_admonition(self, node: admonition) -> object | None: ... + @type_check_only + def depart_attention(self, node: attention) -> object | None: ... + @type_check_only + def depart_attribution(self, node: attribution) -> object | None: ... + @type_check_only + def depart_author(self, node: author) -> object | None: ... + @type_check_only + def depart_authors(self, node: authors) -> object | None: ... + @type_check_only + def depart_block_quote(self, node: block_quote) -> object | None: ... + @type_check_only + def depart_bullet_list(self, node: bullet_list) -> object | None: ... + @type_check_only + def depart_caption(self, node: caption) -> object | None: ... + @type_check_only + def depart_caution(self, node: caution) -> object | None: ... + @type_check_only + def depart_citation(self, node: citation) -> object | None: ... + @type_check_only + def depart_citation_reference(self, node: citation_reference) -> object | None: ... + @type_check_only + def depart_classifier(self, node: classifier) -> object | None: ... + @type_check_only + def depart_colspec(self, node: colspec) -> object | None: ... + @type_check_only + def depart_comment(self, node: comment) -> object | None: ... + @type_check_only + def depart_compound(self, node: compound) -> object | None: ... + @type_check_only + def depart_contact(self, node: contact) -> object | None: ... + @type_check_only + def depart_container(self, node: container) -> object | None: ... + @type_check_only + def depart_copyright(self, node: copyright) -> object | None: ... + @type_check_only + def depart_danger(self, node: danger) -> object | None: ... + @type_check_only + def depart_date(self, node: date) -> object | None: ... + @type_check_only + def depart_decoration(self, node: decoration) -> object | None: ... + @type_check_only + def depart_definition(self, node: definition) -> object | None: ... + @type_check_only + def depart_definition_list(self, node: definition_list) -> object | None: ... + @type_check_only + def depart_definition_list_item(self, node: definition_list_item) -> object | None: ... + @type_check_only + def depart_description(self, node: description) -> object | None: ... + @type_check_only + def depart_docinfo(self, node: docinfo) -> object | None: ... + @type_check_only + def depart_doctest_block(self, node: doctest_block) -> object | None: ... + @type_check_only + def depart_document(self, node: _Document) -> object | None: ... + @type_check_only + def depart_emphasis(self, node: emphasis) -> object | None: ... + @type_check_only + def depart_entry(self, node: entry) -> object | None: ... + @type_check_only + def depart_enumerated_list(self, node: enumerated_list) -> object | None: ... + @type_check_only + def depart_error(self, node: error) -> object | None: ... + @type_check_only + def depart_field(self, node: field) -> object | None: ... + @type_check_only + def depart_field_body(self, node: field_body) -> object | None: ... + @type_check_only + def depart_field_list(self, node: field_list) -> object | None: ... + @type_check_only + def depart_field_name(self, node: field_name) -> object | None: ... + @type_check_only + def depart_figure(self, node: figure) -> object | None: ... + @type_check_only + def depart_footer(self, node: footer) -> object | None: ... + @type_check_only + def depart_footnote(self, node: footnote) -> object | None: ... + @type_check_only + def depart_footnote_reference(self, node: footnote_reference) -> object | None: ... + @type_check_only + def depart_generated(self, node: generated) -> object | None: ... + @type_check_only + def depart_header(self, node: header) -> object | None: ... + @type_check_only + def depart_hint(self, node: hint) -> object | None: ... + @type_check_only + def depart_image(self, node: image) -> object | None: ... + @type_check_only + def depart_important(self, node: important) -> object | None: ... + @type_check_only + def depart_inline(self, node: inline) -> object | None: ... + @type_check_only + def depart_label(self, node: label) -> object | None: ... + @type_check_only + def depart_legend(self, node: legend) -> object | None: ... + @type_check_only + def depart_line(self, node: line) -> object | None: ... + @type_check_only + def depart_line_block(self, node: line_block) -> object | None: ... + @type_check_only + def depart_list_item(self, node: list_item) -> object | None: ... + @type_check_only + def depart_literal(self, node: literal) -> object | None: ... + @type_check_only + def depart_literal_block(self, node: literal_block) -> object | None: ... + @type_check_only + def depart_math(self, node: math) -> object | None: ... + @type_check_only + def depart_math_block(self, node: math_block) -> object | None: ... + @type_check_only + def depart_meta(self, node: meta) -> object | None: ... + @type_check_only + def depart_note(self, node: note) -> object | None: ... + @type_check_only + def depart_option(self, node: option) -> object | None: ... + @type_check_only + def depart_option_argument(self, node: option_argument) -> object | None: ... + @type_check_only + def depart_option_group(self, node: option_group) -> object | None: ... + @type_check_only + def depart_option_list(self, node: option_list) -> object | None: ... + @type_check_only + def depart_option_list_item(self, node: option_list_item) -> object | None: ... + @type_check_only + def depart_option_string(self, node: option_string) -> object | None: ... + @type_check_only + def depart_organization(self, node: organization) -> object | None: ... + @type_check_only + def depart_paragraph(self, node: paragraph) -> object | None: ... + @type_check_only + def depart_pending(self, node: pending) -> object | None: ... + @type_check_only + def depart_problematic(self, node: problematic) -> object | None: ... + @type_check_only + def depart_raw(self, node: raw) -> object | None: ... + @type_check_only + def depart_reference(self, node: reference) -> object | None: ... + @type_check_only + def depart_revision(self, node: revision) -> object | None: ... + @type_check_only + def depart_row(self, node: row) -> object | None: ... + @type_check_only + def depart_rubric(self, node: rubric) -> object | None: ... + @type_check_only + def depart_section(self, node: section) -> object | None: ... + @type_check_only + def depart_sidebar(self, node: sidebar) -> object | None: ... + @type_check_only + def depart_status(self, node: status) -> object | None: ... + @type_check_only + def depart_strong(self, node: strong) -> object | None: ... + @type_check_only + def depart_subscript(self, node: subscript) -> object | None: ... + @type_check_only + def depart_substitution_definition(self, node: substitution_definition) -> object | None: ... + @type_check_only + def depart_substitution_reference(self, node: substitution_reference) -> object | None: ... + @type_check_only + def depart_subtitle(self, node: subtitle) -> object | None: ... + @type_check_only + def depart_superscript(self, node: superscript) -> object | None: ... + @type_check_only + def depart_system_message(self, node: system_message) -> object | None: ... + @type_check_only + def depart_table(self, node: table) -> object | None: ... + @type_check_only + def depart_target(self, node: target) -> object | None: ... + @type_check_only + def depart_tbody(self, node: tbody) -> object | None: ... + @type_check_only + def depart_term(self, node: term) -> object | None: ... + @type_check_only + def depart_tgroup(self, node: tgroup) -> object | None: ... + @type_check_only + def depart_thead(self, node: thead) -> object | None: ... + @type_check_only + def depart_tip(self, node: tip) -> object | None: ... + @type_check_only + def depart_title(self, node: title) -> object | None: ... + @type_check_only + def depart_title_reference(self, node: title_reference) -> object | None: ... + @type_check_only + def depart_topic(self, node: topic) -> object | None: ... + @type_check_only + def depart_transition(self, node: transition) -> object | None: ... + @type_check_only + def depart_version(self, node: version) -> object | None: ... + @type_check_only + def depart_warning(self, node: warning) -> object | None: ... + +class SparseNodeVisitor(NodeVisitor): + def visit_Text(self, node: Text) -> object | None: ... + def visit_abbreviation(self, node: abbreviation) -> object | None: ... + def visit_acronym(self, node: acronym) -> object | None: ... + def visit_address(self, node: address) -> object | None: ... + def visit_admonition(self, node: admonition) -> object | None: ... + def visit_attention(self, node: attention) -> object | None: ... + def visit_attribution(self, node: attribution) -> object | None: ... + def visit_author(self, node: author) -> object | None: ... + def visit_authors(self, node: authors) -> object | None: ... + def visit_block_quote(self, node: block_quote) -> object | None: ... + def visit_bullet_list(self, node: bullet_list) -> object | None: ... + def visit_caption(self, node: caption) -> object | None: ... + def visit_caution(self, node: caution) -> object | None: ... + def visit_citation(self, node: citation) -> object | None: ... + def visit_citation_reference(self, node: citation_reference) -> object | None: ... + def visit_classifier(self, node: classifier) -> object | None: ... + def visit_colspec(self, node: colspec) -> object | None: ... + def visit_comment(self, node: comment) -> object | None: ... + def visit_compound(self, node: compound) -> object | None: ... + def visit_contact(self, node: contact) -> object | None: ... + def visit_container(self, node: container) -> object | None: ... + def visit_copyright(self, node: copyright) -> object | None: ... + def visit_danger(self, node: danger) -> object | None: ... + def visit_date(self, node: date) -> object | None: ... + def visit_decoration(self, node: decoration) -> object | None: ... + def visit_definition(self, node: definition) -> object | None: ... + def visit_definition_list(self, node: definition_list) -> object | None: ... + def visit_definition_list_item(self, node: definition_list_item) -> object | None: ... + def visit_description(self, node: description) -> object | None: ... + def visit_docinfo(self, node: docinfo) -> object | None: ... + def visit_doctest_block(self, node: doctest_block) -> object | None: ... + def visit_document(self, node: _Document) -> object | None: ... + def visit_emphasis(self, node: emphasis) -> object | None: ... + def visit_entry(self, node: entry) -> object | None: ... + def visit_enumerated_list(self, node: enumerated_list) -> object | None: ... + def visit_error(self, node: error) -> object | None: ... + def visit_field(self, node: field) -> object | None: ... + def visit_field_body(self, node: field_body) -> object | None: ... + def visit_field_list(self, node: field_list) -> object | None: ... + def visit_field_name(self, node: field_name) -> object | None: ... + def visit_figure(self, node: figure) -> object | None: ... + def visit_footer(self, node: footer) -> object | None: ... + def visit_footnote(self, node: footnote) -> object | None: ... + def visit_footnote_reference(self, node: footnote_reference) -> object | None: ... + def visit_generated(self, node: generated) -> object | None: ... + def visit_header(self, node: header) -> object | None: ... + def visit_hint(self, node: hint) -> object | None: ... + def visit_image(self, node: image) -> object | None: ... + def visit_important(self, node: important) -> object | None: ... + def visit_inline(self, node: inline) -> object | None: ... + def visit_label(self, node: label) -> object | None: ... + def visit_legend(self, node: legend) -> object | None: ... + def visit_line(self, node: line) -> object | None: ... + def visit_line_block(self, node: line_block) -> object | None: ... + def visit_list_item(self, node: list_item) -> object | None: ... + def visit_literal(self, node: literal) -> object | None: ... + def visit_literal_block(self, node: literal_block) -> object | None: ... + def visit_math(self, node: math) -> object | None: ... + def visit_math_block(self, node: math_block) -> object | None: ... + def visit_meta(self, node: meta) -> object | None: ... + def visit_note(self, node: note) -> object | None: ... + def visit_option(self, node: option) -> object | None: ... + def visit_option_argument(self, node: option_argument) -> object | None: ... + def visit_option_group(self, node: option_group) -> object | None: ... + def visit_option_list(self, node: option_list) -> object | None: ... + def visit_option_list_item(self, node: option_list_item) -> object | None: ... + def visit_option_string(self, node: option_string) -> object | None: ... + def visit_organization(self, node: organization) -> object | None: ... + def visit_paragraph(self, node: paragraph) -> object | None: ... + def visit_pending(self, node: pending) -> object | None: ... + def visit_problematic(self, node: problematic) -> object | None: ... + def visit_raw(self, node: raw) -> object | None: ... + def visit_reference(self, node: reference) -> object | None: ... + def visit_revision(self, node: revision) -> object | None: ... + def visit_row(self, node: row) -> object | None: ... + def visit_rubric(self, node: rubric) -> object | None: ... + def visit_section(self, node: section) -> object | None: ... + def visit_sidebar(self, node: sidebar) -> object | None: ... + def visit_status(self, node: status) -> object | None: ... + def visit_strong(self, node: strong) -> object | None: ... + def visit_subscript(self, node: subscript) -> object | None: ... + def visit_substitution_definition(self, node: substitution_definition) -> object | None: ... + def visit_substitution_reference(self, node: substitution_reference) -> object | None: ... + def visit_subtitle(self, node: subtitle) -> object | None: ... + def visit_superscript(self, node: superscript) -> object | None: ... + def visit_system_message(self, node: system_message) -> object | None: ... + def visit_table(self, node: table) -> object | None: ... + def visit_target(self, node: target) -> object | None: ... + def visit_tbody(self, node: tbody) -> object | None: ... + def visit_term(self, node: term) -> object | None: ... + def visit_tgroup(self, node: tgroup) -> object | None: ... + def visit_thead(self, node: thead) -> object | None: ... + def visit_tip(self, node: tip) -> object | None: ... + def visit_title(self, node: title) -> object | None: ... + def visit_title_reference(self, node: title_reference) -> object | None: ... + def visit_topic(self, node: topic) -> object | None: ... + def visit_transition(self, node: transition) -> object | None: ... + def visit_version(self, node: version) -> object | None: ... + def visit_warning(self, node: warning) -> object | None: ... + def depart_Text(self, node: Text) -> object | None: ... + def depart_abbreviation(self, node: abbreviation) -> object | None: ... + def depart_acronym(self, node: acronym) -> object | None: ... + def depart_address(self, node: address) -> object | None: ... + def depart_admonition(self, node: admonition) -> object | None: ... + def depart_attention(self, node: attention) -> object | None: ... + def depart_attribution(self, node: attribution) -> object | None: ... + def depart_author(self, node: author) -> object | None: ... + def depart_authors(self, node: authors) -> object | None: ... + def depart_block_quote(self, node: block_quote) -> object | None: ... + def depart_bullet_list(self, node: bullet_list) -> object | None: ... + def depart_caption(self, node: caption) -> object | None: ... + def depart_caution(self, node: caution) -> object | None: ... + def depart_citation(self, node: citation) -> object | None: ... + def depart_citation_reference(self, node: citation_reference) -> object | None: ... + def depart_classifier(self, node: classifier) -> object | None: ... + def depart_colspec(self, node: colspec) -> object | None: ... + def depart_comment(self, node: comment) -> object | None: ... + def depart_compound(self, node: compound) -> object | None: ... + def depart_contact(self, node: contact) -> object | None: ... + def depart_container(self, node: container) -> object | None: ... + def depart_copyright(self, node: copyright) -> object | None: ... + def depart_danger(self, node: danger) -> object | None: ... + def depart_date(self, node: date) -> object | None: ... + def depart_decoration(self, node: decoration) -> object | None: ... + def depart_definition(self, node: definition) -> object | None: ... + def depart_definition_list(self, node: definition_list) -> object | None: ... + def depart_definition_list_item(self, node: definition_list_item) -> object | None: ... + def depart_description(self, node: description) -> object | None: ... + def depart_docinfo(self, node: docinfo) -> object | None: ... + def depart_doctest_block(self, node: doctest_block) -> object | None: ... + def depart_document(self, node: _Document) -> object | None: ... + def depart_emphasis(self, node: emphasis) -> object | None: ... + def depart_entry(self, node: entry) -> object | None: ... + def depart_enumerated_list(self, node: enumerated_list) -> object | None: ... + def depart_error(self, node: error) -> object | None: ... + def depart_field(self, node: field) -> object | None: ... + def depart_field_body(self, node: field_body) -> object | None: ... + def depart_field_list(self, node: field_list) -> object | None: ... + def depart_field_name(self, node: field_name) -> object | None: ... + def depart_figure(self, node: figure) -> object | None: ... + def depart_footer(self, node: footer) -> object | None: ... + def depart_footnote(self, node: footnote) -> object | None: ... + def depart_footnote_reference(self, node: footnote_reference) -> object | None: ... + def depart_generated(self, node: generated) -> object | None: ... + def depart_header(self, node: header) -> object | None: ... + def depart_hint(self, node: hint) -> object | None: ... + def depart_image(self, node: image) -> object | None: ... + def depart_important(self, node: important) -> object | None: ... + def depart_inline(self, node: inline) -> object | None: ... + def depart_label(self, node: label) -> object | None: ... + def depart_legend(self, node: legend) -> object | None: ... + def depart_line(self, node: line) -> object | None: ... + def depart_line_block(self, node: line_block) -> object | None: ... + def depart_list_item(self, node: list_item) -> object | None: ... + def depart_literal(self, node: literal) -> object | None: ... + def depart_literal_block(self, node: literal_block) -> object | None: ... + def depart_math(self, node: math) -> object | None: ... + def depart_math_block(self, node: math_block) -> object | None: ... + def depart_meta(self, node: meta) -> object | None: ... + def depart_note(self, node: note) -> object | None: ... + def depart_option(self, node: option) -> object | None: ... + def depart_option_argument(self, node: option_argument) -> object | None: ... + def depart_option_group(self, node: option_group) -> object | None: ... + def depart_option_list(self, node: option_list) -> object | None: ... + def depart_option_list_item(self, node: option_list_item) -> object | None: ... + def depart_option_string(self, node: option_string) -> object | None: ... + def depart_organization(self, node: organization) -> object | None: ... + def depart_paragraph(self, node: paragraph) -> object | None: ... + def depart_pending(self, node: pending) -> object | None: ... + def depart_problematic(self, node: problematic) -> object | None: ... + def depart_raw(self, node: raw) -> object | None: ... + def depart_reference(self, node: reference) -> object | None: ... + def depart_revision(self, node: revision) -> object | None: ... + def depart_row(self, node: row) -> object | None: ... + def depart_rubric(self, node: rubric) -> object | None: ... + def depart_section(self, node: section) -> object | None: ... + def depart_sidebar(self, node: sidebar) -> object | None: ... + def depart_status(self, node: status) -> object | None: ... + def depart_strong(self, node: strong) -> object | None: ... + def depart_subscript(self, node: subscript) -> object | None: ... + def depart_substitution_definition(self, node: substitution_definition) -> object | None: ... + def depart_substitution_reference(self, node: substitution_reference) -> object | None: ... + def depart_subtitle(self, node: subtitle) -> object | None: ... + def depart_superscript(self, node: superscript) -> object | None: ... + def depart_system_message(self, node: system_message) -> object | None: ... + def depart_table(self, node: table) -> object | None: ... + def depart_target(self, node: target) -> object | None: ... + def depart_tbody(self, node: tbody) -> object | None: ... + def depart_term(self, node: term) -> object | None: ... + def depart_tgroup(self, node: tgroup) -> object | None: ... + def depart_thead(self, node: thead) -> object | None: ... + def depart_tip(self, node: tip) -> object | None: ... + def depart_title(self, node: title) -> object | None: ... + def depart_title_reference(self, node: title_reference) -> object | None: ... + def depart_topic(self, node: topic) -> object | None: ... + def depart_transition(self, node: transition) -> object | None: ... + def depart_version(self, node: version) -> object | None: ... + def depart_warning(self, node: warning) -> object | None: ... class GenericNodeVisitor(NodeVisitor): def default_visit(self, node: Node) -> None: ... def default_departure(self, node: Node) -> None: ... + def visit_Text(self, node: Text) -> object | None: ... + def visit_abbreviation(self, node: abbreviation) -> object | None: ... + def visit_acronym(self, node: acronym) -> object | None: ... + def visit_address(self, node: address) -> object | None: ... + def visit_admonition(self, node: admonition) -> object | None: ... + def visit_attention(self, node: attention) -> object | None: ... + def visit_attribution(self, node: attribution) -> object | None: ... + def visit_author(self, node: author) -> object | None: ... + def visit_authors(self, node: authors) -> object | None: ... + def visit_block_quote(self, node: block_quote) -> object | None: ... + def visit_bullet_list(self, node: bullet_list) -> object | None: ... + def visit_caption(self, node: caption) -> object | None: ... + def visit_caution(self, node: caution) -> object | None: ... + def visit_citation(self, node: citation) -> object | None: ... + def visit_citation_reference(self, node: citation_reference) -> object | None: ... + def visit_classifier(self, node: classifier) -> object | None: ... + def visit_colspec(self, node: colspec) -> object | None: ... + def visit_comment(self, node: comment) -> object | None: ... + def visit_compound(self, node: compound) -> object | None: ... + def visit_contact(self, node: contact) -> object | None: ... + def visit_container(self, node: container) -> object | None: ... + def visit_copyright(self, node: copyright) -> object | None: ... + def visit_danger(self, node: danger) -> object | None: ... + def visit_date(self, node: date) -> object | None: ... + def visit_decoration(self, node: decoration) -> object | None: ... + def visit_definition(self, node: definition) -> object | None: ... + def visit_definition_list(self, node: definition_list) -> object | None: ... + def visit_definition_list_item(self, node: definition_list_item) -> object | None: ... + def visit_description(self, node: description) -> object | None: ... + def visit_docinfo(self, node: docinfo) -> object | None: ... + def visit_doctest_block(self, node: doctest_block) -> object | None: ... + def visit_document(self, node: _Document) -> object | None: ... + def visit_emphasis(self, node: emphasis) -> object | None: ... + def visit_entry(self, node: entry) -> object | None: ... + def visit_enumerated_list(self, node: enumerated_list) -> object | None: ... + def visit_error(self, node: error) -> object | None: ... + def visit_field(self, node: field) -> object | None: ... + def visit_field_body(self, node: field_body) -> object | None: ... + def visit_field_list(self, node: field_list) -> object | None: ... + def visit_field_name(self, node: field_name) -> object | None: ... + def visit_figure(self, node: figure) -> object | None: ... + def visit_footer(self, node: footer) -> object | None: ... + def visit_footnote(self, node: footnote) -> object | None: ... + def visit_footnote_reference(self, node: footnote_reference) -> object | None: ... + def visit_generated(self, node: generated) -> object | None: ... + def visit_header(self, node: header) -> object | None: ... + def visit_hint(self, node: hint) -> object | None: ... + def visit_image(self, node: image) -> object | None: ... + def visit_important(self, node: important) -> object | None: ... + def visit_inline(self, node: inline) -> object | None: ... + def visit_label(self, node: label) -> object | None: ... + def visit_legend(self, node: legend) -> object | None: ... + def visit_line(self, node: line) -> object | None: ... + def visit_line_block(self, node: line_block) -> object | None: ... + def visit_list_item(self, node: list_item) -> object | None: ... + def visit_literal(self, node: literal) -> object | None: ... + def visit_literal_block(self, node: literal_block) -> object | None: ... + def visit_math(self, node: math) -> object | None: ... + def visit_math_block(self, node: math_block) -> object | None: ... + def visit_meta(self, node: meta) -> object | None: ... + def visit_note(self, node: note) -> object | None: ... + def visit_option(self, node: option) -> object | None: ... + def visit_option_argument(self, node: option_argument) -> object | None: ... + def visit_option_group(self, node: option_group) -> object | None: ... + def visit_option_list(self, node: option_list) -> object | None: ... + def visit_option_list_item(self, node: option_list_item) -> object | None: ... + def visit_option_string(self, node: option_string) -> object | None: ... + def visit_organization(self, node: organization) -> object | None: ... + def visit_paragraph(self, node: paragraph) -> object | None: ... + def visit_pending(self, node: pending) -> object | None: ... + def visit_problematic(self, node: problematic) -> object | None: ... + def visit_raw(self, node: raw) -> object | None: ... + def visit_reference(self, node: reference) -> object | None: ... + def visit_revision(self, node: revision) -> object | None: ... + def visit_row(self, node: row) -> object | None: ... + def visit_rubric(self, node: rubric) -> object | None: ... + def visit_section(self, node: section) -> object | None: ... + def visit_sidebar(self, node: sidebar) -> object | None: ... + def visit_status(self, node: status) -> object | None: ... + def visit_strong(self, node: strong) -> object | None: ... + def visit_subscript(self, node: subscript) -> object | None: ... + def visit_substitution_definition(self, node: substitution_definition) -> object | None: ... + def visit_substitution_reference(self, node: substitution_reference) -> object | None: ... + def visit_subtitle(self, node: subtitle) -> object | None: ... + def visit_superscript(self, node: superscript) -> object | None: ... + def visit_system_message(self, node: system_message) -> object | None: ... + def visit_table(self, node: table) -> object | None: ... + def visit_target(self, node: target) -> object | None: ... + def visit_tbody(self, node: tbody) -> object | None: ... + def visit_term(self, node: term) -> object | None: ... + def visit_tgroup(self, node: tgroup) -> object | None: ... + def visit_thead(self, node: thead) -> object | None: ... + def visit_tip(self, node: tip) -> object | None: ... + def visit_title(self, node: title) -> object | None: ... + def visit_title_reference(self, node: title_reference) -> object | None: ... + def visit_topic(self, node: topic) -> object | None: ... + def visit_transition(self, node: transition) -> object | None: ... + def visit_version(self, node: version) -> object | None: ... + def visit_warning(self, node: warning) -> object | None: ... + def depart_Text(self, node: Text) -> object | None: ... + def depart_abbreviation(self, node: abbreviation) -> object | None: ... + def depart_acronym(self, node: acronym) -> object | None: ... + def depart_address(self, node: address) -> object | None: ... + def depart_admonition(self, node: admonition) -> object | None: ... + def depart_attention(self, node: attention) -> object | None: ... + def depart_attribution(self, node: attribution) -> object | None: ... + def depart_author(self, node: author) -> object | None: ... + def depart_authors(self, node: authors) -> object | None: ... + def depart_block_quote(self, node: block_quote) -> object | None: ... + def depart_bullet_list(self, node: bullet_list) -> object | None: ... + def depart_caption(self, node: caption) -> object | None: ... + def depart_caution(self, node: caution) -> object | None: ... + def depart_citation(self, node: citation) -> object | None: ... + def depart_citation_reference(self, node: citation_reference) -> object | None: ... + def depart_classifier(self, node: classifier) -> object | None: ... + def depart_colspec(self, node: colspec) -> object | None: ... + def depart_comment(self, node: comment) -> object | None: ... + def depart_compound(self, node: compound) -> object | None: ... + def depart_contact(self, node: contact) -> object | None: ... + def depart_container(self, node: container) -> object | None: ... + def depart_copyright(self, node: copyright) -> object | None: ... + def depart_danger(self, node: danger) -> object | None: ... + def depart_date(self, node: date) -> object | None: ... + def depart_decoration(self, node: decoration) -> object | None: ... + def depart_definition(self, node: definition) -> object | None: ... + def depart_definition_list(self, node: definition_list) -> object | None: ... + def depart_definition_list_item(self, node: definition_list_item) -> object | None: ... + def depart_description(self, node: description) -> object | None: ... + def depart_docinfo(self, node: docinfo) -> object | None: ... + def depart_doctest_block(self, node: doctest_block) -> object | None: ... + def depart_document(self, node: _Document) -> object | None: ... + def depart_emphasis(self, node: emphasis) -> object | None: ... + def depart_entry(self, node: entry) -> object | None: ... + def depart_enumerated_list(self, node: enumerated_list) -> object | None: ... + def depart_error(self, node: error) -> object | None: ... + def depart_field(self, node: field) -> object | None: ... + def depart_field_body(self, node: field_body) -> object | None: ... + def depart_field_list(self, node: field_list) -> object | None: ... + def depart_field_name(self, node: field_name) -> object | None: ... + def depart_figure(self, node: figure) -> object | None: ... + def depart_footer(self, node: footer) -> object | None: ... + def depart_footnote(self, node: footnote) -> object | None: ... + def depart_footnote_reference(self, node: footnote_reference) -> object | None: ... + def depart_generated(self, node: generated) -> object | None: ... + def depart_header(self, node: header) -> object | None: ... + def depart_hint(self, node: hint) -> object | None: ... + def depart_image(self, node: image) -> object | None: ... + def depart_important(self, node: important) -> object | None: ... + def depart_inline(self, node: inline) -> object | None: ... + def depart_label(self, node: label) -> object | None: ... + def depart_legend(self, node: legend) -> object | None: ... + def depart_line(self, node: line) -> object | None: ... + def depart_line_block(self, node: line_block) -> object | None: ... + def depart_list_item(self, node: list_item) -> object | None: ... + def depart_literal(self, node: literal) -> object | None: ... + def depart_literal_block(self, node: literal_block) -> object | None: ... + def depart_math(self, node: math) -> object | None: ... + def depart_math_block(self, node: math_block) -> object | None: ... + def depart_meta(self, node: meta) -> object | None: ... + def depart_note(self, node: note) -> object | None: ... + def depart_option(self, node: option) -> object | None: ... + def depart_option_argument(self, node: option_argument) -> object | None: ... + def depart_option_group(self, node: option_group) -> object | None: ... + def depart_option_list(self, node: option_list) -> object | None: ... + def depart_option_list_item(self, node: option_list_item) -> object | None: ... + def depart_option_string(self, node: option_string) -> object | None: ... + def depart_organization(self, node: organization) -> object | None: ... + def depart_paragraph(self, node: paragraph) -> object | None: ... + def depart_pending(self, node: pending) -> object | None: ... + def depart_problematic(self, node: problematic) -> object | None: ... + def depart_raw(self, node: raw) -> object | None: ... + def depart_reference(self, node: reference) -> object | None: ... + def depart_revision(self, node: revision) -> object | None: ... + def depart_row(self, node: row) -> object | None: ... + def depart_rubric(self, node: rubric) -> object | None: ... + def depart_section(self, node: section) -> object | None: ... + def depart_sidebar(self, node: sidebar) -> object | None: ... + def depart_status(self, node: status) -> object | None: ... + def depart_strong(self, node: strong) -> object | None: ... + def depart_subscript(self, node: subscript) -> object | None: ... + def depart_substitution_definition(self, node: substitution_definition) -> object | None: ... + def depart_substitution_reference(self, node: substitution_reference) -> object | None: ... + def depart_subtitle(self, node: subtitle) -> object | None: ... + def depart_superscript(self, node: superscript) -> object | None: ... + def depart_system_message(self, node: system_message) -> object | None: ... + def depart_table(self, node: table) -> object | None: ... + def depart_target(self, node: target) -> object | None: ... + def depart_tbody(self, node: tbody) -> object | None: ... + def depart_term(self, node: term) -> object | None: ... + def depart_tgroup(self, node: tgroup) -> object | None: ... + def depart_thead(self, node: thead) -> object | None: ... + def depart_tip(self, node: tip) -> object | None: ... + def depart_title(self, node: title) -> object | None: ... + def depart_title_reference(self, node: title_reference) -> object | None: ... + def depart_topic(self, node: topic) -> object | None: ... + def depart_transition(self, node: transition) -> object | None: ... + def depart_version(self, node: version) -> object | None: ... + def depart_warning(self, node: warning) -> object | None: ... class TreeCopyVisitor(GenericNodeVisitor): parent_stack: list[Node] @@ -778,4 +1402,4 @@ def validate_NMTOKENS(value: str | list[str]) -> list[str]: ... def validate_refname_list(value: str | list[str]) -> list[str]: ... def validate_yesorno(value: str | int | bool) -> bool: ... -ATTRIBUTE_VALIDATORS: dict[str, Callable[[str], Any]] +ATTRIBUTE_VALIDATORS: dict[str, Callable[[str], object]] diff --git a/stubs/docutils/docutils/parsers/__init__.pyi b/stubs/docutils/docutils/parsers/__init__.pyi index d15966c81088..572c4d6ad146 100644 --- a/stubs/docutils/docutils/parsers/__init__.pyi +++ b/stubs/docutils/docutils/parsers/__init__.pyi @@ -1,4 +1,4 @@ -from typing import ClassVar, Final +from typing import ClassVar, Final, Literal from docutils import Component from docutils.nodes import _Document @@ -6,10 +6,12 @@ from docutils.nodes import _Document __docformat__: Final = "reStructuredText" class Parser(Component): - component_type: ClassVar[str] + component_type: ClassVar[Literal["parser"]] config_section: ClassVar[str] - inputstring: str # defined after call to setup_parse() - document: _Document # defined after call to setup_parse() + # `input_string` is defined after calling `setup_parse()`. + inputstring: str + # `document` is defined after calling `setup_parse()`. + document: _Document def parse(self, inputstring: str, document: _Document) -> None: ... def setup_parse(self, inputstring: str, document: _Document) -> None: ... def finish_parse(self) -> None: ... diff --git a/stubs/docutils/docutils/parsers/commonmark_wrapper.pyi b/stubs/docutils/docutils/parsers/commonmark_wrapper.pyi index a9b7a2c2956e..e1af5f8fc2bc 100644 --- a/stubs/docutils/docutils/parsers/commonmark_wrapper.pyi +++ b/stubs/docutils/docutils/parsers/commonmark_wrapper.pyi @@ -5,5 +5,9 @@ from docutils import parsers _ParserName: TypeAlias = Literal["pycmark", "myst", "recommonmark"] commonmark_parser_names: tuple[_ParserName, ...] -Parser: type[parsers.Parser] # if Parser is None or parser_name is empty string, user cannot import current module +# If Parser is None or `parser_name` is an empty string, this module will fail to import. +Parser: type[parsers.Parser] parser_name: _ParserName +# `name` is likely an unintentionally exposed variable. +# It is the loop induction variable `parser_name` is assigned from, and they should be equal. +name = parser_name diff --git a/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi b/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi index 3f12ce9e59f7..e05a9c4fa800 100644 --- a/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi +++ b/stubs/docutils/docutils/parsers/recommonmark_wrapper.pyi @@ -1,10 +1,13 @@ +from collections.abc import Sequence from types import ModuleType -from typing import ClassVar +from typing import Any, ClassVar, Final, Protocol, type_check_only from typing_extensions import deprecated -from docutils import nodes +from docutils import nodes, parsers from docutils.transforms import Transform +__docformat__: Final = "reStructuredText" + @deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.") class pending_xref(nodes.Inline, nodes.Element): ... @@ -13,43 +16,65 @@ sphinx: ModuleType @deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.") def is_literal(node: nodes.Node) -> bool: ... +# The parts of `commonmark.node.Node` used by `recommonmark` (neither package ships type hints). +@type_check_only +class _MarkdownNode(Protocol): + t: str + parent: _MarkdownNode | None + first_child: _MarkdownNode | None + last_child: _MarkdownNode | None + sourcepos: Sequence[Sequence[int]] | None + literal: str | None + list_data: dict[str, Any] # heterogeneous list properties ("type", "start", "delimiter", ...) + info: str | None + destination: str | None + title: str | None + level: int | None + is_fenced: bool + def is_container(self) -> bool: ... + +# `recommonmark.parser.CommonMarkParser` @deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.") -class _CommonMarkParser: - default_config: ClassVar[dict[str, None]] +class CommonMarkParser(parsers.Parser): + translate_section_name: ClassVar[None] + default_config: ClassVar[dict[str, object]] + config: dict[str, object] + current_node: nodes.Element def __init__(self) -> None: ... - def convert_ast(self, ast): ... - def default_visit(self, mdnode): ... - def default_depart(self, mdnode): ... - def visit_heading(self, mdnode): ... - def depart_heading(self, _): ... - def visit_text(self, mdnode): ... - def visit_softbreak(self, _): ... - def visit_linebreak(self, _): ... - def visit_paragraph(self, mdnode): ... - def visit_emph(self, _): ... - def visit_strong(self, _): ... - def visit_code(self, mdnode): ... - def visit_link(self, mdnode): ... - def depart_link(self, mdnode): ... - def visit_image(self, mdnode): ... - def visit_list(self, mdnode): ... - def visit_item(self, mdnode): ... - def visit_code_block(self, mdnode): ... - def visit_block_quote(self, mdnode): ... - def visit_html(self, mdnode): ... - def visit_html_inline(self, mdnode): ... - def visit_html_block(self, mdnode): ... - def visit_thematic_break(self, _): ... - def setup_sections(self): ... - def add_section(self, section, level): ... - def is_section_level(self, level, section): ... + def convert_ast(self, ast: _MarkdownNode) -> None: ... + def default_visit(self, mdnode: _MarkdownNode) -> None: ... + def default_depart(self, mdnode: _MarkdownNode) -> None: ... + def visit_heading(self, mdnode: _MarkdownNode) -> None: ... + def depart_heading(self, _: _MarkdownNode) -> None: ... + def visit_text(self, mdnode: _MarkdownNode) -> None: ... + def visit_softbreak(self, _: _MarkdownNode) -> None: ... + def visit_linebreak(self, _: _MarkdownNode) -> None: ... + def visit_paragraph(self, mdnode: _MarkdownNode) -> None: ... + def visit_emph(self, _: _MarkdownNode) -> None: ... + def visit_strong(self, _: _MarkdownNode) -> None: ... + def visit_code(self, mdnode: _MarkdownNode) -> None: ... + def visit_link(self, mdnode: _MarkdownNode) -> None: ... + def depart_link(self, mdnode: _MarkdownNode) -> None: ... + def visit_image(self, mdnode: _MarkdownNode) -> None: ... + def visit_list(self, mdnode: _MarkdownNode) -> None: ... + def visit_item(self, mdnode: _MarkdownNode) -> None: ... + def visit_code_block(self, mdnode: _MarkdownNode) -> None: ... + def visit_block_quote(self, mdnode: _MarkdownNode) -> None: ... + def visit_html(self, mdnode: _MarkdownNode) -> None: ... + def visit_html_inline(self, mdnode: _MarkdownNode) -> None: ... + def visit_html_block(self, mdnode: _MarkdownNode) -> None: ... + def visit_thematic_break(self, _: _MarkdownNode) -> None: ... + def setup_sections(self) -> None: ... + def add_section(self, section: nodes.section, level: int) -> None: ... + def is_section_level(self, level: int, section: nodes.section) -> bool: ... @deprecated("The `recommonmark` package is unmaintained and deprecated; will be removed in Docutils 1.0.") -class Parser(_CommonMarkParser): +class Parser(CommonMarkParser): supported: ClassVar[tuple[str, ...]] config_section: ClassVar[str] config_section_dependencies: ClassVar[tuple[str, ...]] def get_transforms(self) -> list[type[Transform]]: ... def parse(self, inputstring: str, document: nodes.document) -> None: ... - def visit_document(self, node) -> None: ... - def visit_text(self, mdnode) -> None: ... + def finish_parse(self) -> None: ... + def visit_document(self, node: _MarkdownNode) -> None: ... + def visit_text(self, mdnode: _MarkdownNode) -> None: ... diff --git a/stubs/docutils/docutils/parsers/rst/__init__.pyi b/stubs/docutils/docutils/parsers/rst/__init__.pyi index 2ec7af62d1e1..a0fb46f2a73a 100644 --- a/stubs/docutils/docutils/parsers/rst/__init__.pyi +++ b/stubs/docutils/docutils/parsers/rst/__init__.pyi @@ -1,5 +1,4 @@ -from _typeshed import Incomplete -from collections.abc import Callable, Sequence +from collections.abc import Callable, Mapping, Sequence from typing import Any, ClassVar, Final, Literal, TypeAlias from docutils import nodes, parsers @@ -29,11 +28,12 @@ class Directive: required_arguments: ClassVar[int] optional_arguments: ClassVar[int] final_argument_whitespace: ClassVar[bool] - option_spec: ClassVar[dict[str, Callable[[str], Incomplete]] | None] + # Despite the concrete `Directives` class using a `dict`, it is only read from, so a Mapping is the effective API surface. + option_spec: ClassVar[Mapping[str, Callable[[str], object]] | None] has_content: ClassVar[bool] name: str arguments: list[str] - options: dict[str, Incomplete] + options: dict[str, Any] content: StringList lineno: int content_offset: int @@ -45,7 +45,7 @@ class Directive: self, name: str, arguments: list[str], - options: dict[str, Incomplete], + options: Mapping[str, object], content: StringList, lineno: int, content_offset: int, @@ -53,6 +53,8 @@ class Directive: state: RSTState, state_machine: RSTStateMachine, ) -> None: ... + # This must return a `list` at runtime; the alternative would be the less helpful "list[Any]". + # `Sequence` allows covariant overrides like `list[nodes.table]`. def run(self) -> Sequence[nodes.Node]: ... def directive_error(self, level: int, message: str) -> DirectiveError: ... def debug(self, message: str) -> DirectiveError: ... @@ -64,7 +66,7 @@ class Directive: def add_name(self, node: nodes.Node) -> None: ... _DirectiveFn: TypeAlias = Callable[ - [str, list[str], dict[str, Any], StringList, int, int, str, RSTState, RSTStateMachine], Directive + [str, list[str], dict[str, Any], StringList, int, int, str, RSTState, RSTStateMachine], Sequence[nodes.Node] ] def convert_directive_function(directive_fn: _DirectiveFn) -> type[Directive]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi b/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi index 501bb87ddaf9..39dd2eae0999 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/__init__.pyi @@ -1,17 +1,19 @@ from collections.abc import Callable, Container, Iterable, Sequence from re import Pattern -from typing import Final, Literal +from typing import Final, Literal, TypeVar -from docutils.languages import _LanguageModule from docutils.nodes import document, system_message from docutils.parsers import Parser from docutils.parsers.rst import Directive +from docutils.parsers.rst.languages import RSTLanguageModule __docformat__: Final = "reStructuredText" +_T = TypeVar("_T") + def register_directive(name: str, directive: type[Directive]) -> None: ... def directive( - directive_name: str, language_module: _LanguageModule, document: document + directive_name: str, language_module: RSTLanguageModule | None, document: document ) -> tuple[type[Directive] | None, list[system_message]]: ... def flag(argument: str | None) -> None: ... def unchanged_required(argument: str) -> str: ... @@ -39,5 +41,5 @@ def positive_int_list(argument: str) -> list[int]: ... def encoding(argument: str) -> str: ... def choice(argument: str, values: Sequence[str]) -> str: ... def format_values(values: Sequence[object]) -> str: ... -def value_or(values: Container[str], other: Callable[[str], str]) -> Callable[[str], str]: ... +def value_or(values: Container[str], other: Callable[[str], _T]) -> Callable[[str], str | _T]: ... def parser_name(argument: str | None) -> type[Parser] | None: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/admonitions.pyi b/stubs/docutils/docutils/parsers/rst/directives/admonitions.pyi index 58c4e5debc63..236abe35db5c 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/admonitions.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/admonitions.pyi @@ -1,4 +1,5 @@ -from typing import Final +from collections.abc import Callable, Sequence +from typing import ClassVar, Final from docutils import nodes from docutils.parsers.rst import Directive @@ -6,7 +7,11 @@ from docutils.parsers.rst import Directive __docformat__: Final = "reStructuredText" class BaseAdmonition(Directive): - node_class: type[nodes.Admonition] # Subclasses must set this to the appropriate admonition node class. + option_spec: ClassVar[dict[str, Callable[[str], object]]] + # `None` at runtime; subclasses must set this to the appropriate admonition node class. + # The contract specifies all subclasses must override such that it is not None. + node_class: type[nodes.Admonition] + def run(self) -> Sequence[nodes.Node]: ... class Admonition(BaseAdmonition): node_class: type[nodes.admonition] diff --git a/stubs/docutils/docutils/parsers/rst/directives/body.pyi b/stubs/docutils/docutils/parsers/rst/directives/body.pyi index 345309e71599..3630fb488957 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/body.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/body.pyi @@ -1,73 +1,61 @@ -from collections.abc import Callable -from typing import ClassVar, Final, TypeAlias +from collections.abc import Callable, Sequence +from typing import ClassVar, Final from docutils import nodes from docutils.parsers.rst import Directive __docformat__: Final = "reStructuredText" -_DirectiveFn: TypeAlias = Callable[[str], str | list[str]] - class BasePseudoSection(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - node_class: ClassVar[type[nodes.Node] | None] + option_spec: ClassVar[dict[str, Callable[[str], object]]] + # `None` at runtime; subclasses must set this to the appropriate node class. + # The contract specifies all subclasses must override such that it is not None. + node_class: ClassVar[type[nodes.Element] | None] invalid_parents: ClassVar[ - tuple[ - type[nodes.SubStructural], - type[nodes.Bibliographic], - type[nodes.Decorative], - type[nodes.Body], - type[nodes.Part], - type[nodes.topic], - ] + tuple[type[nodes.Element | nodes.SubStructural | nodes.Bibliographic | nodes.Decorative | nodes.Body | nodes.Part], ...] ] - def run(self): ... + def run(self) -> Sequence[nodes.Node]: ... class Topic(BasePseudoSection): - node_class: ClassVar[type[nodes.Node]] + node_class: ClassVar[type[nodes.topic]] class Sidebar(BasePseudoSection): - node_class: ClassVar[type[nodes.Node]] - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + node_class: ClassVar[type[nodes.sidebar]] + def run(self) -> Sequence[nodes.Node]: ... class LineBlock(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class ParsedLiteral(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class CodeBlock(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class MathBlock(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class Rubric(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class BlockQuote(Directive): classes: ClassVar[list[str]] - def run(self): ... - -class Epigraph(BlockQuote): - classes: ClassVar[list[str]] + def run(self) -> Sequence[nodes.Node]: ... -class Highlights(BlockQuote): - classes: ClassVar[list[str]] - -class PullQuote(BlockQuote): - classes: ClassVar[list[str]] +class Epigraph(BlockQuote): ... +class Highlights(BlockQuote): ... +class PullQuote(BlockQuote): ... class Compound(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... class Container(Directive): - option_spec: ClassVar[dict[str, _DirectiveFn]] - def run(self): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/images.pyi b/stubs/docutils/docutils/parsers/rst/directives/images.pyi index cd9654c65b4c..39e573fb04f5 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/images.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/images.pyi @@ -1,18 +1,36 @@ -from _typeshed import Incomplete -from typing import Final +from collections.abc import Callable, Sequence +from typing import ClassVar, Final +from docutils import nodes from docutils.parsers.rst import Directive __docformat__: Final = "reStructuredText" +# The staticmethods are technically not "@staticmethod"s. +# They, are, however, implemented without a self parameter. +# This is because docutils still supports 3.9; staticmethods did +# not support __call__ until 3.10. + +# When docutils 2 is released (and 3.9 support is dropped), +# these should become truly staticmethods upstream, and the test +# suppressions corresponding to these may be removed. + class Image(Directive): - align_h_values: Incomplete - align_v_values: Incomplete - align_values: Incomplete - loading_values: Incomplete - def align(argument): ... - def loading(argument): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + align_h_values: ClassVar[tuple[str, ...]] + align_v_values: ClassVar[tuple[str, ...]] + align_values: ClassVar[tuple[str, ...]] + loading_values: ClassVar[tuple[str, ...]] + @staticmethod + def align(argument: str) -> str: ... + @staticmethod + def loading(argument: str) -> str: ... + def run(self) -> Sequence[nodes.Node]: ... class Figure(Image): - def align(argument): ... - def figwidth_value(argument): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + @staticmethod + def align(argument: str) -> str: ... + @staticmethod + def figwidth_value(argument: str) -> str: ... + def run(self) -> Sequence[nodes.Node]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/misc.pyi b/stubs/docutils/docutils/parsers/rst/directives/misc.pyi index 46b89b555d45..221ffb983225 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/misc.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/misc.pyi @@ -1,4 +1,5 @@ from _typeshed import StrPath +from collections.abc import Callable, Sequence from pathlib import Path from re import Match, Pattern from typing import ClassVar, Final @@ -12,35 +13,53 @@ __docformat__: Final = "reStructuredText" def adapt_path(path: str, source: StrPath = "", root_prefix: StrPath = "") -> str: ... class Include(Directive): - standard_include_path: Path + option_spec: ClassVar[dict[str, Callable[[str], object]]] + standard_include_path: ClassVar[Path] + def run(self) -> Sequence[nodes.Node]: ... def read_file(self, path: StrPath) -> str: ... def as_literal_block(self, text: str) -> list[nodes.literal_block]: ... def as_code_block(self, text: str) -> list[nodes.literal_block]: ... - def custom_parse(self, text: str) -> list[nodes.Node]: ... + def custom_parse(self, text: str) -> Sequence[nodes.Node]: ... def insert_into_input_lines(self, text: str) -> None: ... -class Raw(Directive): ... -class Replace(Directive): ... +class Raw(Directive): + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... + +class Replace(Directive): + def run(self) -> Sequence[nodes.Node]: ... class Unicode(Directive): - comment_pattern: Pattern[str] + option_spec: ClassVar[dict[str, Callable[[str], object]]] + comment_pattern: ClassVar[Pattern[str]] + def run(self) -> Sequence[nodes.Node]: ... -class Class(Directive): ... +class Class(Directive): + def run(self) -> Sequence[nodes.Node]: ... class Role(Directive): - argument_pattern: Pattern[str] + argument_pattern: ClassVar[Pattern[str]] + def run(self) -> Sequence[nodes.Node]: ... + +class DefaultRole(Directive): + def run(self) -> Sequence[nodes.Node]: ... -class DefaultRole(Directive): ... -class Title(Directive): ... +class Title(Directive): + def run(self) -> Sequence[nodes.Node]: ... class MetaBody(SpecializedBody): - def field_marker( # type: ignore[override] + def field_marker( self, match: Match[str], context: list[str], next_state: str | None ) -> tuple[list[str], str | None, list[str]]: ... - def parsemeta(self, match: Match[str]): ... + def parsemeta(self, match: Match[str]) -> tuple[nodes.meta | nodes.system_message, bool]: ... class Meta(Directive): - SMkwargs: ClassVar[dict[str, tuple[MetaBody]]] + SMkwargs: ClassVar[dict[str, tuple[type[MetaBody]]]] + def run(self) -> Sequence[nodes.Node]: ... + +class Date(Directive): + def run(self) -> Sequence[nodes.Node]: ... -class Date(Directive): ... -class TestDirective(Directive): ... +class TestDirective(Directive): + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/parts.pyi b/stubs/docutils/docutils/parsers/rst/directives/parts.pyi index c69296038b5b..2576f03fd216 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/parts.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/parts.pyi @@ -1,14 +1,25 @@ -from collections.abc import Sequence -from typing import Final +from collections.abc import Callable, Sequence +from typing import ClassVar, Final, Literal +from docutils import nodes from docutils.parsers.rst import Directive __docformat__: Final = "reStructuredText" class Contents(Directive): - backlinks_values: Sequence[str] - def backlinks(arg): ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + backlinks_values: ClassVar[tuple[str, ...]] + # See the comment in the adjacent file `images.pyi` for why this is a staticmethod. + @staticmethod + def backlinks(arg: str) -> Literal["top", "entry"] | None: ... + def run(self) -> Sequence[nodes.Node]: ... -class Sectnum(Directive): ... -class Header(Directive): ... -class Footer(Directive): ... +class Sectnum(Directive): + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... + +class Header(Directive): + def run(self) -> Sequence[nodes.Node]: ... + +class Footer(Directive): + def run(self) -> Sequence[nodes.Node]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/references.pyi b/stubs/docutils/docutils/parsers/rst/directives/references.pyi index 412af33927d8..8b10701d6247 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/references.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/references.pyi @@ -1,7 +1,11 @@ -from typing import Final +from collections.abc import Callable, Sequence +from typing import ClassVar, Final +from docutils import nodes from docutils.parsers.rst import Directive __docformat__: Final = "reStructuredText" -class TargetNotes(Directive): ... +class TargetNotes(Directive): + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def run(self) -> Sequence[nodes.Node]: ... diff --git a/stubs/docutils/docutils/parsers/rst/directives/tables.pyi b/stubs/docutils/docutils/parsers/rst/directives/tables.pyi index 3bc3e4d3b430..1e8810e93c35 100644 --- a/stubs/docutils/docutils/parsers/rst/directives/tables.pyi +++ b/stubs/docutils/docutils/parsers/rst/directives/tables.pyi @@ -1,30 +1,37 @@ import csv -from _typeshed import Incomplete -from collections.abc import Callable, Sequence -from typing import ClassVar, Final +from collections.abc import Callable, Iterable, Mapping, Sequence +from typing import ClassVar, Final, Literal, TypeAlias from typing_extensions import deprecated from docutils import nodes from docutils.parsers.rst import Directive +from docutils.statemachine import StringList __docformat__: Final = "reStructuredText" -def align(argument): ... +# A table cell as expected by `docutils.parsers.rst.states.RSTState.build_table()` is a tuple representing: +# (morerows, morecols, offset, cell content) +_Cell: TypeAlias = tuple[int, int, int, StringList | list[str]] +_Row: TypeAlias = list[_Cell] + +def align(argument: str) -> str: ... class Table(Directive): - option_spec: ClassVar[dict[str, Callable[[str], str | list[str]]]] - def make_title(self): ... - def check_table_dimensions(self, rows, header_rows, stub_columns) -> None: ... - def set_table_width(self, table_node) -> None: ... + option_spec: ClassVar[dict[str, Callable[[str], object]]] + def make_title(self) -> tuple[nodes.title | None, list[nodes.system_message]]: ... + def check_table_dimensions(self, rows: Sequence[object], header_rows: int, stub_columns: int) -> None: ... + def set_table_width(self, table_node: nodes.table) -> None: ... @property - def widths(self): ... - def get_column_widths(self, n_cols): ... - def extend_short_rows_with_empty_cells(self, columns, parts) -> None: ... + def widths(self) -> list[int] | Literal["auto", "grid", ""]: ... + def get_column_widths(self, n_cols: int) -> list[int]: ... + def extend_short_rows_with_empty_cells(self, columns: int, parts: Iterable[list[_Row]]) -> None: ... class RSTTable(Table): def run(self) -> Sequence[nodes.table | nodes.system_message]: ... class CSVTable(Table): + option_spec: ClassVar[dict[str, Callable[[str], object]]] + class DocutilsDialect(csv.Dialect): delimiter: str quotechar: str @@ -32,9 +39,8 @@ class CSVTable(Table): skipinitialspace: bool strict: bool lineterminator: str - quoting: Incomplete - escapechar: Incomplete - def __init__(self, options) -> None: ... + escapechar: str | None + def __init__(self, options: Mapping[str, object]) -> None: ... @deprecated("Deprecated and will be removed in Docutils 1.0.") class HeaderDialect(csv.Dialect): @@ -45,15 +51,19 @@ class CSVTable(Table): skipinitialspace: bool strict: bool lineterminator: str - quoting: Incomplete def __init__(self) -> None: ... - def process_header_option(self): ... + def process_header_option(self) -> tuple[list[_Row], int]: ... def run(self) -> Sequence[nodes.table | nodes.system_message]: ... - def get_csv_data(self): ... - def parse_csv_data_into_rows(self, csv_data, dialect, source): ... + def get_csv_data(self) -> tuple[StringList | list[str], str]: ... + def parse_csv_data_into_rows( + self, csv_data: Iterable[str], dialect: csv.Dialect | type[csv.Dialect], source: str + ) -> tuple[list[_Row], int]: ... class ListTable(Table): + option_spec: ClassVar[dict[str, Callable[[str], object]]] def run(self) -> Sequence[nodes.table | nodes.system_message]: ... - def check_list_content(self, node): ... - def build_table_from_list(self, table_data, col_widths, header_rows, stub_columns) -> nodes.table: ... + def check_list_content(self, node: nodes.Element) -> tuple[int, list[int]]: ... + def build_table_from_list( + self, table_data: Sequence[Sequence[Sequence[nodes.Node]]], col_widths: Sequence[int], header_rows: int, stub_columns: int + ) -> nodes.table: ... diff --git a/stubs/docutils/docutils/parsers/rst/languages/__init__.pyi b/stubs/docutils/docutils/parsers/rst/languages/__init__.pyi index e38d495da4b6..8f5ebc142cca 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/__init__.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/__init__.pyi @@ -1,20 +1,17 @@ from typing import ClassVar, Final, Protocol, type_check_only from docutils.languages import LanguageImporter -from docutils.utils import Reporter __docformat__: Final = "reStructuredText" @type_check_only -class _RstLanguageModule(Protocol): +class RSTLanguageModule(Protocol): + __name__: str directives: dict[str, str] roles: dict[str, str] -class RstLanguageImporter(LanguageImporter): - cache: dict[str, _RstLanguageModule] # type: ignore[assignment] - fallback: ClassVar[None] # type: ignore[assignment] - def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _RstLanguageModule: ... # type: ignore[override] - def check_content(self, module: _RstLanguageModule) -> None: ... # type: ignore[override] - def __call__(self, language_code: str, reporter: Reporter | None = None) -> _RstLanguageModule: ... # type: ignore[override] +# There is no fallback, so `None` is returned for unknown languages. +class RstLanguageImporter(LanguageImporter[RSTLanguageModule, RSTLanguageModule | None]): + fallback: ClassVar[None] get_language: RstLanguageImporter diff --git a/stubs/docutils/docutils/parsers/rst/languages/af.pyi b/stubs/docutils/docutils/parsers/rst/languages/af.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/af.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/af.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ar.pyi b/stubs/docutils/docutils/parsers/rst/languages/ar.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ar.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ar.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ca.pyi b/stubs/docutils/docutils/parsers/rst/languages/ca.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ca.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ca.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/cs.pyi b/stubs/docutils/docutils/parsers/rst/languages/cs.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/cs.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/cs.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/da.pyi b/stubs/docutils/docutils/parsers/rst/languages/da.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/da.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/da.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/de.pyi b/stubs/docutils/docutils/parsers/rst/languages/de.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/de.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/de.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/en.pyi b/stubs/docutils/docutils/parsers/rst/languages/en.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/en.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/en.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/eo.pyi b/stubs/docutils/docutils/parsers/rst/languages/eo.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/eo.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/eo.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/es.pyi b/stubs/docutils/docutils/parsers/rst/languages/es.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/es.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/es.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/fa.pyi b/stubs/docutils/docutils/parsers/rst/languages/fa.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/fa.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/fa.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/fi.pyi b/stubs/docutils/docutils/parsers/rst/languages/fi.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/fi.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/fi.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/fr.pyi b/stubs/docutils/docutils/parsers/rst/languages/fr.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/fr.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/fr.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/gl.pyi b/stubs/docutils/docutils/parsers/rst/languages/gl.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/gl.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/gl.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/he.pyi b/stubs/docutils/docutils/parsers/rst/languages/he.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/he.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/he.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/it.pyi b/stubs/docutils/docutils/parsers/rst/languages/it.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/it.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/it.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ja.pyi b/stubs/docutils/docutils/parsers/rst/languages/ja.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ja.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ja.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ka.pyi b/stubs/docutils/docutils/parsers/rst/languages/ka.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ka.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ka.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ko.pyi b/stubs/docutils/docutils/parsers/rst/languages/ko.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ko.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ko.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/lt.pyi b/stubs/docutils/docutils/parsers/rst/languages/lt.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/lt.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/lt.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/lv.pyi b/stubs/docutils/docutils/parsers/rst/languages/lv.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/lv.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/lv.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/nl.pyi b/stubs/docutils/docutils/parsers/rst/languages/nl.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/nl.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/nl.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/pl.pyi b/stubs/docutils/docutils/parsers/rst/languages/pl.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/pl.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/pl.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/pt_br.pyi b/stubs/docutils/docutils/parsers/rst/languages/pt_br.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/pt_br.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/pt_br.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/ru.pyi b/stubs/docutils/docutils/parsers/rst/languages/ru.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/ru.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/ru.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/sk.pyi b/stubs/docutils/docutils/parsers/rst/languages/sk.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/sk.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/sk.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/sv.pyi b/stubs/docutils/docutils/parsers/rst/languages/sv.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/sv.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/sv.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/uk.pyi b/stubs/docutils/docutils/parsers/rst/languages/uk.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/uk.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/uk.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/zh_cn.pyi b/stubs/docutils/docutils/parsers/rst/languages/zh_cn.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/zh_cn.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/zh_cn.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/languages/zh_tw.pyi b/stubs/docutils/docutils/parsers/rst/languages/zh_tw.pyi index 3ea6b97b3445..f756f32ee73a 100644 --- a/stubs/docutils/docutils/parsers/rst/languages/zh_tw.pyi +++ b/stubs/docutils/docutils/parsers/rst/languages/zh_tw.pyi @@ -1,5 +1,6 @@ from typing import Final __docformat__: Final = "reStructuredText" + directives: dict[str, str] roles: dict[str, str] diff --git a/stubs/docutils/docutils/parsers/rst/roles.pyi b/stubs/docutils/docutils/parsers/rst/roles.pyi index 8c91bff07b63..f90f1ead4735 100644 --- a/stubs/docutils/docutils/parsers/rst/roles.pyi +++ b/stubs/docutils/docutils/parsers/rst/roles.pyi @@ -1,27 +1,46 @@ from collections.abc import Callable, Mapping, Sequence -from typing import Any, Final, TypeAlias +from typing import Any, Final, Protocol, TypeAlias, TypeVar, type_check_only from typing_extensions import deprecated -import docutils.parsers.rst.states -from docutils import nodes -from docutils.languages import _LanguageModule from docutils.nodes import Node, system_message +from docutils.parsers.rst.languages import RSTLanguageModule from docutils.parsers.rst.states import Inliner from docutils.utils import Reporter __docformat__: Final = "reStructuredText" DEFAULT_INTERPRETED_ROLE: Final = "title-reference" -_RoleFn: TypeAlias = Callable[ - [str, str, str, int, docutils.parsers.rst.states.Inliner, Mapping[str, Any], Sequence[str]], - tuple[Sequence[nodes.reference], Sequence[nodes.reference]], -] +_T = TypeVar("_T") +_T_co = TypeVar("_T_co", covariant=True) + +@type_check_only +class _SupportsCopy(Protocol[_T_co]): + def copy(self) -> _T_co: ... + +# Role functions are called by the `Inliner` with five positional arguments that differ between implementations. +# `CustomRole` additionally passes `options` and `content` as keyword arguments, so role functions must provide defaults for them. +@type_check_only +class _RoleFn(Protocol): + def __call__( + self, + name: str, + rawtext: str, + text: str, + lineno: int, + inliner: Inliner, + /, + options: dict[str, Any] = ..., + content: list[str] = ..., + ) -> tuple[Sequence[Node], Sequence[system_message]]: ... + +# The (optional) `options` function attribute of role functions is a mapping of option names to option conversion functions. +_RoleOptionSpec: TypeAlias = dict[str, Callable[[str], object]] -def register_canonical_role(name: str, role_fn: _RoleFn) -> None: ... -def register_local_role(name: str, role_fn: _RoleFn) -> None: ... def role( - role_name: str, language_module: _LanguageModule, lineno: int, reporter: Reporter + role_name: str, language_module: RSTLanguageModule | None, lineno: int, reporter: Reporter ) -> tuple[_RoleFn | None, list[system_message]]: ... +def register_canonical_role(name: str, role_fn: _RoleFn) -> None: ... +def register_local_role(name: str, role_fn: _RoleFn) -> None: ... def set_implicit_options(role_fn: _RoleFn) -> None: ... def register_generic_role(canonical_name: str, node_class: type[Node]) -> None: ... @@ -36,22 +55,22 @@ class GenericRole: text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... class CustomRole: name: str - base_role: _RoleFn | CustomRole - options: Mapping[str, Any] - content: Sequence[str] - supplied_options: Mapping[str, Any] - supplied_content: Sequence[str] + base_role: _RoleFn + options: _RoleOptionSpec | None + content: bool | None + supplied_options: Mapping[str, object] | None + supplied_content: Sequence[str] | None def __init__( self, role_name: str, - base_role: _RoleFn | CustomRole, - options: Mapping[str, Any] | None = None, + base_role: _RoleFn, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> None: ... def __call__( @@ -61,9 +80,9 @@ class CustomRole: text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, - ) -> tuple[list[Node], list[system_message]]: ... + ) -> tuple[Sequence[Node], Sequence[system_message]]: ... def generic_custom_role( role: str, @@ -71,7 +90,7 @@ def generic_custom_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def pep_reference_role( @@ -80,7 +99,7 @@ def pep_reference_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def rfc_reference_role( @@ -89,7 +108,7 @@ def rfc_reference_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def raw_role( @@ -98,7 +117,7 @@ def raw_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def code_role( @@ -107,7 +126,7 @@ def code_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def math_role( @@ -116,7 +135,7 @@ def math_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... def unimplemented_role( @@ -125,11 +144,13 @@ def unimplemented_role( text: str, lineno: int, inliner: Inliner, - options: Mapping[str, Any] | None = None, + options: Mapping[str, object] | None = None, content: Sequence[str] | None = None, ) -> tuple[list[Node], list[system_message]]: ... @deprecated("Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead.") -def set_classes(options: dict[str, str]) -> None: ... +def set_classes(options: dict[str, Any]) -> None: ... @deprecated("Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead.") -def normalized_role_options(options: Mapping[str, Any] | None) -> dict[str, Any]: ... -def normalize_options(options: Mapping[str, Any] | None) -> dict[str, Any]: ... +def normalized_role_options(options: _SupportsCopy[dict[str, _T]] | None) -> dict[str, _T]: ... + +# This returns a copy of `options` (e.g. a `dict`) with the "class" key renamed to "classes". +def normalize_options(options: _SupportsCopy[dict[str, _T]] | None) -> dict[str, _T]: ... diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index d148d2521222..178012e41575 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,31 +1,57 @@ -from _typeshed import Incomplete -from collections.abc import Callable, Iterable, Sequence +from collections.abc import Callable, Iterable, KeysView, Mapping, Sequence from re import Match, Pattern -from types import ModuleType, SimpleNamespace as Struct -from typing import Any, ClassVar, Final, TypeAlias +from types import SimpleNamespace as Struct +from typing import Any, ClassVar, Final, Literal, Protocol, TypeAlias, overload, type_check_only from typing_extensions import Never from docutils import ApplicationError, DataError, nodes +from docutils.frontend import Values from docutils.nodes import Node, system_message -from docutils.parsers.rst.languages import _RstLanguageModule -from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList +from docutils.parsers.rst import Directive, _DirectiveFn +from docutils.parsers.rst.languages import RSTLanguageModule +from docutils.parsers.rst.tableparser import TableParser +from docutils.statemachine import StateMachineWS, StateWS, StringList, _StateMachineKwargs from docutils.utils import Reporter __docformat__: Final = "reStructuredText" +# The context of reStructuredText states is a list of str lines. +_Context: TypeAlias = list[str] +# The tuple below represents (context, next state, results) +_TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] +# Title styles are either the underline character (`_`) or a tuple of (overline, underline). +_TitleStyle: TypeAlias = str | tuple[str, str] +# The tuple below represents (string before, new nodes, remaining string, system messages). +_InlineResult: TypeAlias = tuple[str, list[Node], str, list[system_message]] +# The tuple below represents (nodes, blank_finish). +_ConstructResult: TypeAlias = tuple[list[Node], bool] + +# The "memo" object is shared between nested state machines. +# `memo`, a `types.SimpleNamespace` at runtime. +@type_check_only +class _Memo(Protocol): + document: nodes.document + language: RSTLanguageModule | None + title_styles: list[_TitleStyle] + inliner: Inliner + # Deprecated, will be removed in Docutils 2.0. + reporter: Reporter + section_level: int + section_bubble_up_kludge: bool + class MarkupError(DataError): ... class UnknownInterpretedRoleError(DataError): ... class InterpretedRoleNotImplementedError(DataError): ... class ParserError(ApplicationError): ... class MarkupMismatch(Exception): ... -class RSTStateMachine(StateMachineWS[list[str]]): - language: _RstLanguageModule +class RSTStateMachine(StateMachineWS[_Context]): + language: RSTLanguageModule | None match_titles: bool - memo: Struct | None + memo: _Memo | None document: nodes.document reporter: Reporter - node: nodes.document | None + node: nodes.Element | None section_level_offset: int def run( # type: ignore[override] self, @@ -37,354 +63,437 @@ class RSTStateMachine(StateMachineWS[list[str]]): ) -> None: ... class NestedStateMachine(RSTStateMachine): - parent_state_machine: Incomplete | None - def __init__(self, state_classes, initial_state, debug: bool = False, parent_state_machine=None) -> None: ... + parent_state_machine: RSTStateMachine | None + memo: _Memo + def __init__( + self, + state_classes: Iterable[type[RSTState]], + initial_state: str, + debug: bool = False, + parent_state_machine: RSTStateMachine | None = None, + ) -> None: ... def run( # type: ignore[override] - self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node, match_titles: bool = True + self, + input_lines: Sequence[str] | StringList, + input_offset: int, + memo: _Memo, + node: nodes.Element, + match_titles: bool = True, ) -> list[str]: ... -class RSTState(StateWS[list[str]]): +class RSTState(StateWS[_Context]): nested_sm: type[NestedStateMachine] - nested_sm_cache: list[StateMachine[Incomplete]] - def __init__(self, state_machine, debug: bool = False) -> None: ... - memo: Incomplete + nested_sm_cache: ClassVar[list[NestedStateMachine]] + state_machine: RSTStateMachine + memo: _Memo reporter: Reporter inliner: Inliner document: nodes.document - parent: Incomplete + def __init__(self, state_machine: RSTStateMachine, debug: bool = False) -> None: ... def runtime_init(self) -> None: ... + + @property + def parent(self) -> nodes.Element | None: ... + @parent.setter + def parent(self, value: nodes.Element) -> None: ... + def goto_line(self, abs_line_offset: int) -> None: ... - def no_match(self, context: list[str], transitions): ... - def bof(self, context: list[str]): ... + def no_match(self, context: _Context, transitions: object) -> _TransitionResult: ... + def bof(self, context: _Context) -> tuple[list[str], list[str]]: ... def nested_parse( self, block: StringList, input_offset: int, node: nodes.Element | None = None, match_titles: bool = False, - state_machine_class: StateMachineWS[Incomplete] | None = None, - state_machine_kwargs: dict[Incomplete, Incomplete] | None = None, + state_machine_class: type[StateMachineWS[_Context]] | None = None, + state_machine_kwargs: _StateMachineKwargs[_Context] | None = None, ) -> int: ... def nested_list_parse( self, - block, + block: StringList, input_offset: int, - node, - initial_state, - blank_finish, - blank_finish_state=None, - extra_settings={}, + node: nodes.Element, + initial_state: str, + blank_finish: bool, + blank_finish_state: str | None = None, + extra_settings: dict[str, Any] = ..., match_titles: bool = False, - state_machine_class=None, - state_machine_kwargs=None, - ): ... - def section(self, title: str, source, style, lineno: int, messages) -> None: ... - def check_subsection(self, source, style, lineno: int): ... - def title_inconsistent(self, sourcetext: str, lineno: int): ... - def new_subsection(self, title: str, lineno: int, messages) -> None: ... - def paragraph(self, lines: Iterable[str], lineno: int): ... + state_machine_class: type[StateMachineWS[_Context]] | None = None, + state_machine_kwargs: _StateMachineKwargs[_Context] | None = None, + ) -> tuple[int, bool]: ... + def section(self, title: str, source: str, style: _TitleStyle, lineno: int, messages: list[system_message]) -> None: ... + def check_subsection(self, source: str, style: _TitleStyle, lineno: int) -> bool: ... + def title_inconsistent(self, sourcetext: str, lineno: int) -> system_message: ... + def new_subsection(self, title: str, lineno: int, messages: list[system_message]) -> None: ... + def paragraph(self, lines: Iterable[str], lineno: int) -> tuple[list[Node], Literal[0, 1]]: ... def inline_text(self, text: str, lineno: int) -> tuple[list[Node], list[system_message]]: ... - def unindent_warning(self, node_name: str): ... + def unindent_warning(self, node_name: str) -> system_message: ... + +# This is a tuple representing (group name, prefix, suffix, parts), where `parts` may again be definitions. +_BasicDefinition: TypeAlias = tuple[str, str, str, list[str]] +_DefinitionParts: TypeAlias = tuple[str, str, str, list[str | _BasicDefinition]] +_DefinitionType: TypeAlias = tuple[str, str, str, list[str | _DefinitionParts]] -def build_regexp(definition, compile_patterns: bool | None = True): ... +@overload +def build_regexp(definition: _DefinitionType, compile_patterns: Literal[True] = True) -> Pattern[str]: ... +@overload +def build_regexp(definition: _DefinitionType, compile_patterns: Literal[False]) -> str: ... +@overload +def build_regexp(definition: _DefinitionType, compile_patterns: bool) -> Pattern[str] | str: ... -_BasicDefinition: TypeAlias = tuple[str, str, str, list[Pattern[str]]] -_DefinitionParts: TypeAlias = tuple[str, str, str, list[Pattern[str] | _BasicDefinition]] -_DefinitionType: TypeAlias = tuple[str, str, str, list[Pattern[str] | _DefinitionParts]] +# `Inliner.patterns`, a `types.SimpleNamespace` at runtime. +@type_check_only +class _InlinerPatterns(Protocol): + initial: Pattern[str] + emphasis: Pattern[str] + strong: Pattern[str] + interpreted_or_phrase_ref: Pattern[str] + embedded_link: Pattern[str] + literal: Pattern[str] + target: Pattern[str] + substitution_ref: Pattern[str] + email: Pattern[str] + uri: Pattern[str] + pep: Pattern[str] + rfc: Pattern[str] class Inliner: - implicit_dispatch: list[tuple[Pattern[str], Callable[[Match[str], int], Sequence[nodes.Node]]]] + implicit_dispatch: list[tuple[Pattern[str], Callable[[Match[str], int], list[Node]]]] def __init__(self) -> None: ... start_string_prefix: str end_string_suffix: str parts: _DefinitionType - patterns: Struct - def init_customizations(self, settings: Any) -> None: ... + patterns: _InlinerPatterns + def init_customizations(self, settings: Values) -> None: ... reporter: Reporter document: nodes.document - language: ModuleType + language: RSTLanguageModule | None parent: nodes.Element - def parse( - self, text: str, lineno: int, memo: Struct, parent: nodes.Element - ) -> tuple[list[nodes.Node], list[nodes.system_message]]: ... - non_whitespace_before: str - non_whitespace_escape_before: str - non_unescaped_whitespace_escape_before: str - non_whitespace_after: str - simplename: str - uric: str - uri_end_delim: str - urilast: str - uri_end: str - emailc: str - email_pattern: str + def parse(self, text: str, lineno: int, memo: _Memo, parent: nodes.Element) -> tuple[list[Node], list[system_message]]: ... + non_whitespace_before: ClassVar[str] + non_whitespace_escape_before: ClassVar[str] + non_unescaped_whitespace_escape_before: ClassVar[str] + non_whitespace_after: ClassVar[str] + simplename: ClassVar[str] + uric: ClassVar[str] + uri_end_delim: ClassVar[str] + urilast: ClassVar[str] + uri_end: ClassVar[str] + emailc: ClassVar[str] + email_pattern: ClassVar[str] def quoted_start(self, match: Match[str]) -> bool: ... def inline_obj( self, match: Match[str], lineno: int, end_pattern: Pattern[str], - nodeclass: nodes.TextElement, + nodeclass: type[nodes.TextElement], restore_backslashes: bool = False, - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message], str]: ... - def problematic(self, text: str, rawsource: str, message: nodes.system_message) -> nodes.problematic: ... - def emphasis( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def strong(self, match: Match[str], lineno: int) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def interpreted_or_phrase_ref( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... + ) -> tuple[str, list[Node], str, list[system_message], str]: ... + def problematic(self, text: str, rawsource: str, message: system_message) -> nodes.problematic: ... + def emphasis(self, match: Match[str], lineno: int) -> _InlineResult: ... + def strong(self, match: Match[str], lineno: int) -> _InlineResult: ... + def interpreted_or_phrase_ref(self, match: Match[str], lineno: int) -> _InlineResult: ... def phrase_ref( self, before: str, after: str, rawsource: str, escaped: str, text: str | None = None - ) -> tuple[str, list[nodes.Node], str, list[nodes.Node]]: ... + ) -> tuple[str, list[Node], str, list[system_message]]: ... def adjust_uri(self, uri: str) -> str: ... - def interpreted( - self, rawsource: str, text: str, role: str, lineno: int - ) -> tuple[list[nodes.Node], list[nodes.system_message]]: ... - def literal(self, match: Match[str], lineno: int) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def inline_internal_target( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def substitution_reference( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def footnote_reference( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def reference( - self, match: Match[str], lineno: int, anonymous: bool = False - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def anonymous_reference( - self, match: Match[str], lineno: int - ) -> tuple[str, list[nodes.problematic], str, list[nodes.system_message]]: ... - def standalone_uri( - self, match: Match[str], lineno: int - ) -> list[tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]: ... - def pep_reference( - self, match: Match[str], lineno: int - ) -> list[tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]: ... - rfc_url: str = ... - def rfc_reference( - self, match: Match[str], lineno: int - ) -> list[tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]: ... - def implicit_inline(self, text: str, lineno: int) -> list[nodes.Text]: ... - dispatch: dict[str, Callable[[Match[str], int], tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]] = ... + def interpreted(self, rawsource: str, text: str, role: str, lineno: int) -> tuple[list[Node], list[system_message]]: ... + def literal(self, match: Match[str], lineno: int) -> _InlineResult: ... + def inline_internal_target(self, match: Match[str], lineno: int) -> _InlineResult: ... + def substitution_reference(self, match: Match[str], lineno: int) -> _InlineResult: ... + def footnote_reference(self, match: Match[str], lineno: int) -> _InlineResult: ... + def reference(self, match: Match[str], lineno: int, anonymous: bool = False) -> _InlineResult: ... + def anonymous_reference(self, match: Match[str], lineno: int) -> _InlineResult: ... + def standalone_uri(self, match: Match[str], lineno: int) -> list[Node]: ... + def pep_reference(self, match: Match[str], lineno: int) -> list[Node]: ... + rfc_url: ClassVar[str] + def rfc_reference(self, match: Match[str], lineno: int) -> list[Node]: ... + def implicit_inline(self, text: str, lineno: int) -> list[Node]: ... + # Mapping of start-strings to the (unbound) methods above. + dispatch: ClassVar[dict[str, Callable[[Inliner, Match[str], int], _InlineResult]]] + +# `Body.enum`, a `types.SimpleNamespace` at runtime. +@type_check_only +class _EnumeratorInfo(Protocol): + formatinfo: dict[str, Struct] + formats: KeysView[str] + sequences: list[str] + sequencepats: dict[str, str] + converters: dict[str, Callable[[str], int]] + sequenceregexps: dict[str, Pattern[str]] + +# `Body.explicit.patterns`, a `types.SimpleNamespace` at runtime. +@type_check_only +class _ExplicitPatterns(Protocol): + target: Pattern[str] + reference: Pattern[str] + substitution: Pattern[str] + +# `Body.explicit`, a `types.SimpleNamespace` at runtime. +@type_check_only +class _ExplicitInfo(Protocol): + patterns: _ExplicitPatterns + # (unbound method, pattern) + constructs: list[tuple[Callable[[Body, Match[str]], _ConstructResult], Pattern[str]]] class Body(RSTState): - double_width_pad_char: Incomplete - enum: Incomplete - grid_table_top_pat: Incomplete - simple_table_top_pat: Incomplete - simple_table_border_pat: Incomplete - pats: Incomplete - patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[tuple[str, ...]] - sequence: str + double_width_pad_char: ClassVar[str] + enum: ClassVar[_EnumeratorInfo] + # Some of these are induction variables leaked from the class body. format: str - def indent(self, match, context, next_state): ... - def block_quote(self, indented, line_offset): ... - attribution_pattern: Incomplete - def split_attribution(self, indented, line_offset): ... - def check_attribution(self, indented, attribution_start): ... - def parse_attribution(self, indented, line_offset): ... - def bullet(self, match, context, next_state): ... - def list_item(self, indent): ... - def enumerator(self, match, context, next_state): ... - def parse_enumerator(self, match, expected_sequence=None): ... - def is_enumerated_list_item(self, ordinal, sequence, format): ... - def make_enumerator(self, ordinal, sequence, format): ... - def field_marker(self, match, context, next_state): ... - def field(self, match): ... - def parse_field_marker(self, match): ... - def parse_field_body(self, indented, offset, node) -> None: ... - def option_marker(self, match, context, next_state): ... - def option_list_item(self, match): ... - def parse_option_marker(self, match): ... - def doctest(self, match, context, next_state): ... - def line_block(self, match, context, next_state): ... - def line_block_line(self, match, lineno): ... - def nest_line_block_lines(self, block) -> None: ... - def nest_line_block_segment(self, block) -> None: ... - def grid_table_top(self, match, context, next_state): ... - def simple_table_top(self, match, context, next_state): ... - def table_top(self, match, context, next_state, isolate_function, parser_class): ... - def table(self, isolate_function, parser_class): ... - def isolate_grid_table(self): ... - def isolate_simple_table(self): ... - def malformed_table(self, block, detail: str = "", offset: int = 0): ... - def build_table(self, tabledata, tableline, stub_columns: int = 0, widths=None) -> nodes.table: ... - def build_table_row(self, rowdata, tableline): ... - explicit: Incomplete - def footnote(self, match): ... - def citation(self, match): ... - def hyperlink_target(self, match): ... - def make_target(self, block, block_text, lineno, target_name): ... - def parse_target(self, block, block_text, lineno): ... - def is_reference(self, reference): ... - def add_target(self, targetname, refuri, target, lineno) -> None: ... - def substitution_def(self, match): ... - def disallowed_inside_substitution_definitions(self, node): ... - def directive(self, match, **option_presets): ... - def run_directive(self, directive, match, type_name, option_presets): ... - def parse_directive_block(self, indented, line_offset, directive, option_presets): ... - def parse_directive_options(self, option_presets, option_spec, arg_block): ... - def parse_directive_arguments(self, directive, arg_block): ... - def parse_extension_options(self, option_spec, datalines): ... - def unknown_directive(self, type_name): ... - def comment(self, match): ... - def explicit_markup(self, match, context, next_state): ... - def explicit_construct(self, match): ... - def explicit_list(self, blank_finish) -> None: ... - def anonymous(self, match: Match[str], context: list[str] | None, next_state: str): ... - def anonymous_target(self, match): ... - def line(self, match, context, next_state): ... - def text(self, match, context, next_state): ... + sequence: str + grid_table_top_pat: ClassVar[Pattern[str]] + simple_table_top_pat: ClassVar[Pattern[str]] + simple_table_border_pat: ClassVar[Pattern[str]] + pats: ClassVar[dict[str, str]] + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[Sequence[str] | Sequence[tuple[str, str]]] + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def block_quote(self, indented: StringList, line_offset: int) -> list[Node]: ... + attribution_pattern: ClassVar[Pattern[str]] + def split_attribution( + self, indented: StringList, line_offset: int + ) -> tuple[StringList, StringList | None, int | None, StringList | None, int | None]: ... + def check_attribution(self, indented: StringList, attribution_start: int) -> tuple[int | None, int | None]: ... + def parse_attribution(self, indented: StringList, line_offset: int) -> tuple[nodes.attribution, list[system_message]]: ... + def bullet(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def list_item(self, indent: int) -> tuple[nodes.list_item, bool]: ... + def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + # The returned tuple represents (format, sequence, text, ordinal). + def parse_enumerator(self, match: Match[str], expected_sequence: str | None = None) -> tuple[str, str, str, int | None]: ... + def is_enumerated_list_item(self, ordinal: int | None, sequence: str, format: str) -> Literal[1] | None: ... + def make_enumerator(self, ordinal: int, sequence: str, format: str) -> tuple[str, str] | None: ... + def field_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def field(self, match: Match[str]) -> tuple[nodes.field, bool]: ... + def parse_field_marker(self, match: Match[str]) -> str: ... + def parse_field_body(self, indented: StringList, offset: int, node: nodes.Element) -> None: ... + def option_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def option_list_item(self, match: Match[str]) -> tuple[nodes.option_list_item, bool]: ... + def parse_option_marker(self, match: Match[str]) -> list[nodes.option]: ... + def doctest(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def line_block(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def line_block_line(self, match: Match[str], lineno: int) -> tuple[nodes.line, list[system_message], bool]: ... + def nest_line_block_lines(self, block: nodes.line_block) -> None: ... + def nest_line_block_segment(self, block: nodes.line_block) -> None: ... + def grid_table_top(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def simple_table_top(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def table_top( + self, + match: Match[str], + context: _Context, + next_state: str, + isolate_function: Callable[[], tuple[StringList | list[str], list[system_message], bool]], + parser_class: type[TableParser], + ) -> _TransitionResult: ... + def table( + self, + isolate_function: Callable[[], tuple[StringList | list[str], list[system_message], bool]], + parser_class: type[TableParser], + ) -> tuple[list[Node], bool]: ... + def isolate_grid_table(self) -> tuple[StringList | list[str], list[system_message], bool]: ... + def isolate_simple_table(self) -> tuple[StringList | list[str], list[system_message], bool]: ... + def malformed_table(self, block: StringList, detail: str = "", offset: int = 0) -> list[system_message]: ... + # `tabledata` is (column widths, header rows, body rows), as returned by the table parsers. + def build_table( + self, + tabledata: tuple[list[int], list[list[Any]], list[list[Any]]], + tableline: int, + stub_columns: int = 0, + widths: list[int] | Literal["auto", "grid", ""] | None = None, + ) -> nodes.table: ... + # A row is a list of cells; a cell is `None` (spanned) or (morerows, morecols, offset, content lines). + def build_table_row( + self, rowdata: Sequence[tuple[int, int, int, StringList | list[str]] | None], tableline: int + ) -> nodes.row: ... + explicit: ClassVar[_ExplicitInfo] + def footnote(self, match: Match[str]) -> _ConstructResult: ... + def citation(self, match: Match[str]) -> _ConstructResult: ... + def hyperlink_target(self, match: Match[str]) -> _ConstructResult: ... + def make_target(self, block: Sequence[str], block_text: str, lineno: int, target_name: str | None) -> nodes.target: ... + def parse_target(self, block: Sequence[str], block_text: str, lineno: int) -> tuple[Literal["refname", "refuri"], str]: ... + def is_reference(self, reference: str) -> str | None: ... + def add_target(self, targetname: str | None, refuri: str, target: nodes.target, lineno: int) -> None: ... + def substitution_def(self, match: Match[str]) -> _ConstructResult: ... + def disallowed_inside_substitution_definitions(self, node: nodes.Node) -> str: ... + def directive(self, match: Match[str], **option_presets: object) -> _ConstructResult: ... + def run_directive( + self, directive: type[Directive] | _DirectiveFn, match: Match[str], type_name: str, option_presets: dict[str, Any] + ) -> _ConstructResult: ... + # The returned tuple represents (arguments, options, content, content_offset). + def parse_directive_block( + self, indented: StringList, line_offset: int, directive: type[Directive], option_presets: dict[str, Any] + ) -> tuple[list[str], dict[str, Any], StringList, int]: ... + def parse_directive_options( + self, + option_presets: dict[str, Any], + option_spec: Mapping[str, Callable[[str], object]], + arg_block: StringList | list[str], + ) -> tuple[dict[str, Any], StringList | list[str]]: ... + def parse_directive_arguments(self, directive: type[Directive], arg_block: StringList | list[str]) -> list[str]: ... + # Returns (1, options) on success, or (0, error message) on failure. + def parse_extension_options( + self, option_spec: Mapping[str, Callable[[str], object]], datalines: StringList + ) -> tuple[Literal[1], dict[str, Any]] | tuple[Literal[0], str]: ... + def unknown_directive(self, type_name: str) -> _ConstructResult: ... + def comment(self, match: Match[str]) -> _ConstructResult: ... + def explicit_markup(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def explicit_construct(self, match: Match[str]) -> _ConstructResult: ... + def explicit_list(self, blank_finish: bool) -> None: ... + def anonymous(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def anonymous_target(self, match: Match[str]) -> _ConstructResult: ... + def line(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class RFC2822Body(Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] # type: ignore[assignment] - def rfc2822(self, match, context, next_state): ... - def rfc2822_field(self, match): ... + initial_transitions: ClassVar[list[tuple[str, str]]] + def rfc2822(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def rfc2822_field(self, match: Match[str]) -> tuple[nodes.field, bool]: ... class SpecializedBody(Body): + # At runtime, all transition methods of this class are aliases of `invalid_input()`, which always raises. + # Subclasses must override those they wish to use. The stub keeps the regular transition signatures so that subclasses have + # the intended override signature. + # They have additionally been redeclared with @type_check_only so that supporting type_checkers may identify these as + # non-existing methods. def invalid_input( - self, match: Match[str] | None = None, context: list[str] | None = None, next_state: str | None = None + self, match: Match[str] | None = None, context: _Context | None = None, next_state: str | None = None ) -> Never: ... - indent = invalid_input # type: ignore[assignment] - bullet = invalid_input - enumerator = invalid_input - field_marker = invalid_input - option_marker = invalid_input - doctest = invalid_input - line_block = invalid_input - grid_table_top = invalid_input - simple_table_top = invalid_input - explicit_markup = invalid_input - anonymous = invalid_input # type: ignore[assignment] - line = invalid_input - text = invalid_input + @type_check_only + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def bullet(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def field_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def option_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def doctest(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def line_block(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def grid_table_top(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def simple_table_top(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def explicit_markup(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def anonymous(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def line(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class BulletList(SpecializedBody): - blank_finish: Incomplete - def bullet( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank_finish: bool + def bullet(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class DefinitionList(SpecializedBody): - def text(self, match: Match[str], context: list[str] | None, next_state: str | None) -> tuple[list[str], str, list[str]]: ... # type: ignore[override] + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class EnumeratedList(SpecializedBody): auto: int - blank_finish: Incomplete - lastordinal: Incomplete - def enumerator( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank_finish: bool + format: str + lastordinal: int + sequence: str + def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class FieldList(SpecializedBody): - blank_finish: Incomplete - def field_marker( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank_finish: bool + def field_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class OptionList(SpecializedBody): - blank_finish: Incomplete - def option_marker( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank_finish: bool + def option_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class RFC2822List(SpecializedBody, RFC2822Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] # type: ignore[assignment] - blank_finish: Incomplete - def rfc2822(self, match, context, next_state): ... - blank: Incomplete + initial_transitions: ClassVar[list[tuple[str, str]]] + blank_finish: bool + def rfc2822(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + blank = SpecializedBody.invalid_input class ExtensionOptions(FieldList): - def parse_field_body(self, indented, offset, node) -> None: ... + def parse_field_body(self, indented: StringList, offset: int, node: nodes.Element) -> None: ... class LineBlock(SpecializedBody): - blank: Incomplete - blank_finish: Incomplete - def line_block( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank = SpecializedBody.invalid_input + blank_finish: bool + def line_block(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class Explicit(SpecializedBody): - blank_finish: Incomplete - blank: Incomplete - def explicit_markup( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... - def anonymous( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + blank_finish: bool + def explicit_markup(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def anonymous(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + blank = SpecializedBody.invalid_input class SubstitutionDef(Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[str]] # type: ignore[assignment] - blank_finish: Incomplete - def embedded_directive(self, match, context, next_state) -> None: ... - def text(self, match, context, next_state) -> None: ... + initial_transitions: ClassVar[list[str]] + blank_finish: bool + def embedded_directive(self, match: Match[str], context: _Context, next_state: str) -> Never: ... + def text(self, match: Match[str], context: _Context, next_state: str) -> Never: ... class Text(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str, str]]] - def blank(self, match, context, next_state): ... - def eof(self, context): ... - def indent(self, match, context, next_state): ... - def underline(self, match, context, next_state): ... - def text(self, match, context, next_state): ... - def literal_block(self): ... - def quoted_literal_block(self): ... - def definition_list_item(self, termline): ... - classifier_delimiter: Incomplete - def term(self, lines, lineno): ... + def blank(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def eof(self, context: _Context) -> list[str]: ... + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def underline(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def literal_block(self) -> list[Node]: ... + def quoted_literal_block(self) -> list[Node]: ... + def definition_list_item(self, termline: _Context) -> tuple[nodes.definition_list_item, bool]: ... + classifier_delimiter: ClassVar[Pattern[str]] + def term(self, lines: Sequence[str], lineno: int) -> tuple[list[Node], list[system_message]]: ... class SpecializedText(Text): - def eof(self, context): ... + def eof(self, context: _Context) -> list[str]: ... + # See the comment in SpecializedBody. def invalid_input( - self, match: Match[str] | None = None, context: list[str] | None = None, next_state: str | None = None + self, match: Match[str] | None = None, context: _Context | None = None, next_state: str | None = None ) -> Never: ... - blank = invalid_input - indent = invalid_input - underline = invalid_input - text = invalid_input + @type_check_only + def blank(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def underline(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + @type_check_only + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class Definition(SpecializedText): - def eof(self, context): ... - blank_finish: Incomplete - def indent( # type: ignore[override] - self, match: Match[str] | None, context: list[str], next_state: str | None - ) -> tuple[list[str], str, list[str]]: ... + blank_finish: bool + def eof(self, context: _Context) -> list[str]: ... + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... class Line(SpecializedText): eofcheck: int - def eof(self, context: list[str]): ... - def blank(self, match: Match[str] | None, context: list[str], next_state: str | None) -> tuple[list[str], str, list[str]]: ... # type: ignore[override] - def text(self, match: Match[str], context: list[str], next_state: str | None) -> tuple[list[str], str, list[str]]: ... # type: ignore[override] - indent = text # type: ignore[assignment] - def underline( # type: ignore[override] - self, match: Match[str] | None, context: list[str], next_state: str | None - ) -> tuple[list[str], str, list[str]]: ... - def short_overline(self, context, blocktext, lineno, lines: int = 1) -> None: ... - def state_correction(self, context, lines: int = 1) -> None: ... + def eof(self, context: _Context) -> list[str]: ... + def blank(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def text(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + indent = text + def underline(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def short_overline(self, context: _Context, blocktext: str, lineno: int, lines: int = 1) -> None: ... + def state_correction(self, context: _Context, lines: int = 1) -> Never: ... class QuotedLiteralBlock(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] - messages: Incomplete - initial_lineno: Incomplete - def __init__(self, state_machine, debug: bool = False) -> None: ... - def blank(self, match, context, next_state): ... - def eof(self, context): ... - def indent(self, match: Match[str] | None, context: list[str], next_state: str | None) -> Never: ... - def initial_quoted( - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... - def quoted( - self, match: Match[str], context: list[str], next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... - def text(self, match: Match[str] | None, context: list[str] | None, next_state: str | None) -> None: ... + initial_transitions: ClassVar[tuple[str, ...]] + messages: list[system_message] + initial_lineno: int | None + def __init__(self, state_machine: RSTStateMachine, debug: bool = False) -> None: ... + def blank(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def eof(self, context: _Context) -> list[str]: ... + def indent(self, match: Match[str], context: _Context, next_state: str) -> Never: ... + def initial_quoted(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def quoted(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult: ... + def text(self, match: Match[str], context: _Context, next_state: str) -> Never: ... state_classes: tuple[type[RSTState], ...] diff --git a/stubs/docutils/docutils/parsers/rst/tableparser.pyi b/stubs/docutils/docutils/parsers/rst/tableparser.pyi index ad805b9ccd52..8820395644fc 100644 --- a/stubs/docutils/docutils/parsers/rst/tableparser.pyi +++ b/stubs/docutils/docutils/parsers/rst/tableparser.pyi @@ -12,7 +12,7 @@ __docformat__: Final = "reStructuredText" class TableMarkupError(DataError): offset: int - def __init__(self, *args, **kwargs) -> None: ... + def __init__(self, *args: object, offset: int = 0) -> None: ... class TableParser: head_body_separator_pat: ClassVar[Pattern[str] | None] diff --git a/stubs/docutils/docutils/readers/__init__.pyi b/stubs/docutils/docutils/readers/__init__.pyi index d29e4aa717d3..7482e0284f36 100644 --- a/stubs/docutils/docutils/readers/__init__.pyi +++ b/stubs/docutils/docutils/readers/__init__.pyi @@ -1,4 +1,4 @@ -from typing import Any, ClassVar, Final, Generic, TypeVar +from typing import Any, ClassVar, Final, Generic, Literal, TypeVar from docutils import Component, nodes from docutils.frontend import Values @@ -11,7 +11,7 @@ _S = TypeVar("_S") __docformat__: Final = "reStructuredText" class Reader(Component, Generic[_S]): - component_type: ClassVar[str] + component_type: ClassVar[Literal["reader"]] config_section: ClassVar[str] def get_transforms(self) -> list[type[Transform]]: ... def __init__(self, parser: Parser | None = None, parser_name: str | None = None) -> None: ... diff --git a/stubs/docutils/docutils/readers/standalone.pyi b/stubs/docutils/docutils/readers/standalone.pyi index 6e7319e2c5d1..285bf2835908 100644 --- a/stubs/docutils/docutils/readers/standalone.pyi +++ b/stubs/docutils/docutils/readers/standalone.pyi @@ -1,11 +1,10 @@ from typing import ClassVar, Final, TypeVar -from docutils import nodes, readers +from docutils import readers __docformat__: Final = "reStructuredText" _S = TypeVar("_S", bound=str | bytes) class Reader(readers.Reader[_S]): - document: nodes.document | None # type: ignore[assignment] config_section_dependencies: ClassVar[tuple[str, ...]] diff --git a/stubs/docutils/docutils/statemachine.pyi b/stubs/docutils/docutils/statemachine.pyi index 96b5f38a7461..0c3f9b56b57d 100644 --- a/stubs/docutils/docutils/statemachine.pyi +++ b/stubs/docutils/docutils/statemachine.pyi @@ -1,17 +1,27 @@ import sys -from collections.abc import Callable, Generator, Iterable, Iterator, Sequence +from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence from re import Match, Pattern -from typing import Any, ClassVar, Final, Generic, SupportsIndex, TypeAlias, TypeVar, overload +from typing import ClassVar, Final, Generic, SupportsIndex, TypeAlias, TypedDict, TypeVar, overload, type_check_only from typing_extensions import Self _T = TypeVar("_T") _Context = TypeVar("_Context") _TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] _TransitionMethod: TypeAlias = Callable[[Match[str], _Context, str], _TransitionResult[_Context]] -_Observer: TypeAlias = Callable[[StateMachine[_Context]], None] +_Transition: TypeAlias = tuple[Pattern[str], _TransitionMethod[_Context], str] +# Observers are called with the source and line number of the current line. +_Observer: TypeAlias = Callable[[str | None, int | None], object] __docformat__: Final = "restructuredtext" +# Keyword arguments for `StateMachine.__init__()`. +# These are used to create nested state machines. +@type_check_only +class _StateMachineKwargs(TypedDict, Generic[_Context], total=False): + state_classes: Iterable[type[State[_Context]]] + initial_state: str + debug: bool + class StateMachine(Generic[_Context]): input_lines: StringList | None input_offset: int @@ -21,7 +31,7 @@ class StateMachine(Generic[_Context]): initial_state: str current_state: str states: dict[str, State[_Context]] - observers: list[_Observer[_Context]] + observers: list[_Observer] def __init__(self, state_classes: Iterable[type[State[_Context]]], initial_state: str, debug: bool = False) -> None: ... def unlink(self) -> None: ... def run( @@ -39,10 +49,11 @@ class StateMachine(Generic[_Context]): def at_bof(self) -> bool: ... def previous_line(self, n: int = 1) -> str | None: ... def goto_line(self, line_offset: int) -> str | None: ... - def get_source(self, line_offset: int) -> str: ... + def get_source(self, line_offset: int) -> str | None: ... def abs_line_offset(self) -> int: ... def abs_line_number(self) -> int: ... - def get_source_and_line(self, lineno: int | None = None) -> tuple[str, int] | tuple[None, None]: ... + # The source is `None` for lines of a `StringList` created without source information. + def get_source_and_line(self, lineno: int | None = None) -> tuple[str | None, int | None]: ... def insert_input(self, input_lines: list[str] | StringList, source: str) -> None: ... def get_text_block(self, flush_left: bool = False) -> StringList: ... def check_line( @@ -52,36 +63,34 @@ class StateMachine(Generic[_Context]): def add_states(self, state_classes: Iterable[type[State[_Context]]]) -> None: ... def runtime_init(self) -> None: ... def error(self) -> None: ... - def attach_observer(self, observer: _Observer[_Context]) -> None: ... - def detach_observer(self, observer: _Observer[_Context]) -> None: ... + def attach_observer(self, observer: _Observer) -> None: ... + def detach_observer(self, observer: _Observer) -> None: ... def notify_observers(self) -> None: ... class State(Generic[_Context]): patterns: ClassVar[dict[str, str | Pattern[str]] | None] initial_transitions: ClassVar[Sequence[str] | Sequence[tuple[str, str]] | None] nested_sm: type[StateMachine[_Context]] - nested_sm_kwargs: dict[str, Any] + nested_sm_kwargs: _StateMachineKwargs[_Context] transition_order: list[str] - transitions: dict[str, tuple[Pattern[str], Callable[[], None], str]] + transitions: dict[str, _Transition[_Context]] state_machine: StateMachine[_Context] debug: bool def __init__(self, state_machine: StateMachine[_Context], debug: bool = False) -> None: ... def runtime_init(self) -> None: ... def unlink(self) -> None: ... def add_initial_transitions(self) -> None: ... - def add_transitions(self, names: Iterable[str], transitions) -> None: ... - def add_transition(self, name: str, transition: tuple[Pattern[str], str, str]) -> None: ... + def add_transitions(self, names: Iterable[str], transitions: Mapping[str, _Transition[_Context]]) -> None: ... + def add_transition(self, name: str, transition: _Transition[_Context]) -> None: ... def remove_transition(self, name: str) -> None: ... - def make_transition( - self, name: str, next_state: str | None = None - ) -> tuple[Pattern[str], _TransitionMethod[_Context], str]: ... + def make_transition(self, name: str, next_state: str | None = None) -> _Transition[_Context]: ... def make_transitions( - self, name_list: list[str | tuple[str] | tuple[str, str]] - ) -> tuple[list[str], dict[str, tuple[Pattern[str], _TransitionMethod[_Context], str]]]: ... + self, name_list: Iterable[str | tuple[str] | tuple[str, str]] + ) -> tuple[list[str], dict[str, _Transition[_Context]]]: ... def no_match( - self, context: _Context, transitions: tuple[list[str], dict[str, tuple[Pattern[str], _TransitionMethod[_Context], str]]] + self, context: _Context, transitions: tuple[list[str], dict[str, _Transition[_Context]]] | None ) -> _TransitionResult[_Context]: ... - def bof(self, context: _Context) -> tuple[list[str], list[str]]: ... + def bof(self, context: _Context) -> tuple[_Context, list[str]]: ... def eof(self, context: _Context) -> list[str]: ... def nop(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... @@ -89,16 +98,16 @@ class StateMachineWS(StateMachine[_Context]): def get_indented(self, until_blank: bool = False, strip_indent: bool = True) -> tuple[StringList, int, int, bool]: ... def get_known_indented( self, indent: int, until_blank: bool = False, strip_indent: bool = True - ) -> tuple[list[str], int, bool]: ... + ) -> tuple[StringList, int, bool]: ... def get_first_known_indented( self, indent: int, until_blank: bool = False, strip_indent: bool = True, strip_top: bool = True - ) -> tuple[list[str], int, int, bool]: ... + ) -> tuple[StringList, int, int, bool]: ... class StateWS(State[_Context]): indent_sm: type[StateMachine[_Context]] | None - indent_sm_kwargs: dict[str, Any] | None + indent_sm_kwargs: _StateMachineKwargs[_Context] | None known_indent_sm: type[StateMachine[_Context]] | None - known_indent_sm_kwargs: dict[str, Any] | None + known_indent_sm_kwargs: _StateMachineKwargs[_Context] | None ws_patterns: dict[str, Pattern[str]] ws_initial_transitions: Sequence[str] def __init__(self, state_machine: StateMachine[_Context], debug: bool = False) -> None: ... @@ -116,23 +125,23 @@ class SearchStateMachineWS(_SearchOverride, StateMachineWS[_Context]): ... class ViewList(Generic[_T]): data: list[_T] - items: list[tuple[str, int]] + items: list[tuple[str | None, int]] parent: Self parent_offset: int def __init__( self, initlist: Self | Sequence[_T] | None = None, source: str | None = None, - items: list[tuple[str, int]] | None = None, + items: list[tuple[str | None, int]] | None = None, parent: Self | None = None, parent_offset: int | None = None, ) -> None: ... - def __lt__(self, other: Any) -> bool: ... - def __le__(self, other: Any) -> bool: ... + def __lt__(self, other: ViewList[_T] | list[_T]) -> bool: ... + def __le__(self, other: ViewList[_T] | list[_T]) -> bool: ... def __eq__(self, other: object) -> bool: ... def __ne__(self, other: object) -> bool: ... - def __gt__(self, other: Any) -> bool: ... - def __ge__(self, other: Any) -> bool: ... + def __gt__(self, other: ViewList[_T] | list[_T]) -> bool: ... + def __ge__(self, other: ViewList[_T] | list[_T]) -> bool: ... def __contains__(self, item: _T) -> bool: ... def __len__(self) -> int: ... @@ -164,15 +173,16 @@ class ViewList(Generic[_T]): def index(self, item: _T) -> int: ... def reverse(self) -> None: ... def sort(self, *args: tuple[_T, tuple[str, int]]) -> None: ... - def info(self, i: int) -> tuple[str, int | None]: ... - def source(self, i: int) -> str: ... + def info(self, i: int) -> tuple[str | None, int | None]: ... + def source(self, i: int) -> str | None: ... def offset(self, i: int) -> int: ... def disconnect(self) -> None: ... - def xitems(self) -> Generator[tuple[str, int, str]]: ... + def xitems(self) -> Generator[tuple[str | None, int, _T]]: ... def pprint(self) -> None: ... - # dummy atribute to indicate to mypy that ViewList is Iterable[str] - def __iter__(self) -> Iterator[str]: ... + # Dummy attribute that lets mypy know that ViewList is iterable (via __getitem__). + @type_check_only + def __iter__(self) -> Iterator[_T]: ... class StringList(ViewList[str]): def trim_left(self, length: int, start: int = 0, end: int = sys.maxsize) -> None: ... diff --git a/stubs/docutils/docutils/transforms/__init__.pyi b/stubs/docutils/docutils/transforms/__init__.pyi index a848d0768f9f..fdd159a5ecd4 100644 --- a/stubs/docutils/docutils/transforms/__init__.pyi +++ b/stubs/docutils/docutils/transforms/__init__.pyi @@ -1,9 +1,8 @@ -from _typeshed import Incomplete from collections.abc import Iterable, Mapping from typing import Any, ClassVar, Final, TypeAlias from docutils import ApplicationError, TransformSpec, nodes -from docutils.languages import LanguageImporter +from docutils.languages import LanguageModule _TransformTuple: TypeAlias = tuple[str, type[Transform], nodes.Node | None, dict[str, Any]] @@ -15,9 +14,13 @@ class Transform: default_priority: ClassVar[int | None] document: nodes.document startnode: nodes.Node | None - language: LanguageImporter + language: LanguageModule def __init__(self, document: nodes.document, startnode: nodes.Node | None = None) -> None: ... - def __getattr__(self, name: str, /) -> Incomplete: ... # method apply is not implemented + # The base method accepts (and ignores) `**kwargs` at runtime, so that `Transformer` + # can pass on the keyword arguments given to `add_transform()`. These are never used + # in practice, and docutils' own transforms don't accept any, so the stub declares the + # call that all transforms support; subclasses may still accept optional keywords. + def apply(self) -> None: ... class Transformer(TransformSpec): transforms: list[_TransformTuple] @@ -26,8 +29,8 @@ class Transformer(TransformSpec): sorted: bool components: Mapping[str, TransformSpec] serialno: int - def __init__(self, document: nodes.document): ... - def add_transform(self, transform_class: type[Transform], priority: int | None = None, **kwargs) -> None: ... + def __init__(self, document: nodes.document) -> None: ... + def add_transform(self, transform_class: type[Transform], priority: int | None = None, **kwargs: object) -> None: ... def add_transforms(self, transform_list: Iterable[type[Transform]]) -> None: ... def add_pending(self, pending: nodes.pending, priority: int | None = None) -> None: ... def get_priority_string(self, priority: int) -> str: ... diff --git a/stubs/docutils/docutils/transforms/frontmatter.pyi b/stubs/docutils/docutils/transforms/frontmatter.pyi index bb0a86afb869..56c675f435e0 100644 --- a/stubs/docutils/docutils/transforms/frontmatter.pyi +++ b/stubs/docutils/docutils/transforms/frontmatter.pyi @@ -25,10 +25,10 @@ class DocInfo(Transform): biblio_nodes: ClassVar[dict[str, type[nodes.Element]]] rcs_keyword_substitutions: ClassVar[list[tuple[re.Pattern[str], str]]] def apply(self) -> None: ... - def extract_bibliographic(self, field_list): ... - def check_empty_biblio_field(self, field, name) -> bool: ... - def check_compound_biblio_field(self, field, name) -> bool: ... - def extract_authors(self, field, name, docinfo) -> None: ... - def authors_from_one_paragraph(self, field) -> list[list[nodes.Text]]: ... - def authors_from_bullet_list(self, field): ... - def authors_from_paragraphs(self, field): ... + def extract_bibliographic(self, field_list: nodes.field_list) -> list[nodes.docinfo | nodes.topic]: ... + def check_empty_biblio_field(self, field: nodes.field, name: str) -> bool: ... + def check_compound_biblio_field(self, field: nodes.field, name: str) -> bool: ... + def extract_authors(self, field: nodes.field, name: str, docinfo: nodes.docinfo) -> None: ... + def authors_from_one_paragraph(self, field: nodes.field) -> list[list[nodes.Text]]: ... + def authors_from_bullet_list(self, field: nodes.field) -> list[list[nodes.Node]]: ... + def authors_from_paragraphs(self, field: nodes.field) -> list[list[nodes.Node]]: ... diff --git a/stubs/docutils/docutils/transforms/parts.pyi b/stubs/docutils/docutils/transforms/parts.pyi index 39aa9e2aa8df..c13d70265b0e 100644 --- a/stubs/docutils/docutils/transforms/parts.pyi +++ b/stubs/docutils/docutils/transforms/parts.pyi @@ -1,6 +1,6 @@ -from _typeshed import Incomplete, Unused +from _typeshed import Unused from collections.abc import Iterable, Sequence -from typing import ClassVar, Final +from typing import ClassVar, Final, Literal from typing_extensions import Never from docutils import nodes @@ -19,8 +19,8 @@ class SectNum(Transform): class Contents(Transform): default_priority: ClassVar[int] - toc_id: Incomplete - backlinks: Incomplete + toc_id: str + backlinks: Literal["entry", "top", False] | None def apply(self) -> None: ... def build_contents( self, node: nodes.Element, level: int = 0 diff --git a/stubs/docutils/docutils/transforms/references.pyi b/stubs/docutils/docutils/transforms/references.pyi index 6bb14effc834..6f3518032e63 100644 --- a/stubs/docutils/docutils/transforms/references.pyi +++ b/stubs/docutils/docutils/transforms/references.pyi @@ -1,8 +1,7 @@ -from _typeshed import Incomplete -from collections.abc import Iterable +from collections.abc import Iterable, MutableMapping, Sequence from typing import ClassVar, Final, overload -from docutils import nodes +from docutils import _UnknownReferenceResolver, nodes from docutils.transforms import Transform __docformat__: Final = "reStructuredText" @@ -25,7 +24,7 @@ class IndirectHyperlinks(Transform): def resolve_indirect_target(self, target: nodes.Element) -> None: ... def nonexistent_indirect_target(self, target: nodes.Element) -> None: ... def circular_indirect_reference(self, target: nodes.Element) -> None: ... - def indirect_target_error(self, target: nodes.Element, explanation) -> None: ... + def indirect_target_error(self, target: nodes.Element, explanation: str) -> None: ... def resolve_indirect_references(self, target: nodes.Element) -> None: ... class ExternalTargets(Transform): @@ -62,10 +61,13 @@ class Substitutions(Transform): class TargetNotes(Transform): default_priority: ClassVar[int] - classes: Incomplete - def __init__(self, document: nodes.document, startnode: nodes.Node) -> None: ... + classes: list[str] + startnode: nodes.pending + def __init__(self, document: nodes.document, startnode: nodes.pending) -> None: ... def apply(self) -> None: ... - def make_target_footnote(self, refuri: str, refs: list[Incomplete], notes: dict[Incomplete, Incomplete]): ... + def make_target_footnote( + self, refuri: str, refs: Sequence[nodes.Element], notes: MutableMapping[str, nodes.footnote] + ) -> nodes.footnote: ... class CitationReferences(Transform): default_priority: ClassVar[int] @@ -77,7 +79,8 @@ class DanglingReferences(Transform): class DanglingReferencesVisitor(nodes.SparseNodeVisitor): document: nodes.document - def __init__(self, document: nodes.document, unknown_reference_resolvers) -> None: ... + unknown_reference_resolvers: Sequence[_UnknownReferenceResolver] + def __init__(self, document: nodes.document, unknown_reference_resolvers: Sequence[_UnknownReferenceResolver]) -> None: ... def unknown_visit(self, node: nodes.Node) -> None: ... def visit_reference(self, node: nodes.reference) -> None: ... def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: ... diff --git a/stubs/docutils/docutils/transforms/universal.pyi b/stubs/docutils/docutils/transforms/universal.pyi index 5d54735bbca8..0603f7dad912 100644 --- a/stubs/docutils/docutils/transforms/universal.pyi +++ b/stubs/docutils/docutils/transforms/universal.pyi @@ -1,4 +1,3 @@ -from _typeshed import Incomplete from collections.abc import Generator, Iterable from typing import ClassVar, Final, Literal @@ -37,7 +36,7 @@ class StripComments(Transform): class StripClassesAndElements(Transform): default_priority: ClassVar[int] - strip_elements: set[Incomplete] + strip_elements: set[str] def apply(self) -> None: ... def check_classes(self, node: object) -> bool: ... diff --git a/stubs/docutils/docutils/utils/__init__.pyi b/stubs/docutils/docutils/utils/__init__.pyi index f076c0f2e8d8..410c646e3555 100644 --- a/stubs/docutils/docutils/utils/__init__.pyi +++ b/stubs/docutils/docutils/utils/__init__.pyi @@ -1,8 +1,7 @@ -import optparse from _typeshed import StrPath, SupportsWrite from collections.abc import Callable, Iterable, Mapping, Sequence from re import Pattern -from typing import Any, Final, Literal, TypeAlias, TypeVar +from typing import Any, Final, Literal, Protocol, TypeAlias, TypeVar, type_check_only from typing_extensions import deprecated from docutils import ApplicationError, DataError, nodes @@ -12,16 +11,16 @@ from docutils.nodes import document, unescape as unescape _T = TypeVar("_T") _Observer: TypeAlias = Callable[[nodes.system_message], object] -_SystemMessageLevel: TypeAlias = Literal[0, 1, 2, 3, 4] __docformat__: Final = "reStructuredText" class DependencyList: list: list[str] file: FileOutput | None - def __init__(self, output_file: str | None = None, dependencies: Iterable[str] = ()) -> None: ... - def set_output(self, output_file: str | None) -> None: ... - def add(self, *paths: str) -> None: ... + # `output_file` "-" means stdout. + def __init__(self, output_file: StrPath | None = None, dependencies: Iterable[StrPath] = ()) -> None: ... + def set_output(self, output_file: StrPath | None) -> None: ... + def add(self, *paths: StrPath) -> None: ... def close(self) -> None: ... class SystemMessagePropagation(ApplicationError): ... @@ -42,19 +41,19 @@ class Reporter: max_level: int def __init__( self, - source: str, + source: StrPath, report_level: int, halt_level: int, - stream: SupportsWrite[str] | SupportsWrite[bytes] | str | bool | None = None, + stream: ErrorOutput | SupportsWrite[str] | SupportsWrite[bytes] | str | Literal[False] | None = None, debug: bool = False, encoding: str | None = None, error_handler: str = "backslashreplace", ) -> None: ... - source: str + source: StrPath error_handler: str debug_flag: bool - report_level: _SystemMessageLevel + report_level: int halt_level: int def attach_observer(self, observer: _Observer) -> None: ... def detach_observer(self, observer: _Observer) -> None: ... @@ -64,45 +63,91 @@ class Reporter: level: int, message: str | Exception, *children: nodes.Node, - base_node: nodes.Node = ..., - source: str = ..., - **kwargs, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node ) -> nodes.system_message: ... def debug( - self, message: str | Exception, *children: nodes.Node, base_node: nodes.Node = ..., source: str = ..., **kwargs + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node ) -> nodes.system_message: ... def info( - self, message: str | Exception, *children: nodes.Node, base_node: nodes.Node = ..., source: str = ..., **kwargs + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node ) -> nodes.system_message: ... def warning( - self, message: str | Exception, *children: nodes.Node, base_node: nodes.Node = ..., source: str = ..., **kwargs + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node ) -> nodes.system_message: ... def error( - self, message: str | Exception, *children: nodes.Node, base_node: nodes.Node = ..., source: str = ..., **kwargs + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node ) -> nodes.system_message: ... def severe( - self, message: str | Exception, *children: nodes.Node, base_node: nodes.Node = ..., source: str = ..., **kwargs + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, # additional attributes of the system_message node + ) -> nodes.system_message: ... + +# The signature of `Reporter.debug()`, ..., `Reporter.severe()`, +# which are e.g. stored as `warn` and `error` attributes by some translators. +@type_check_only +class _ReporterMessageMethod(Protocol): # noqa: Y046 # used by writers + def __call__( + self, + message: str | Exception, + *children: nodes.Node, + base_node: nodes.Node | None = ..., + source: StrPath | None = ..., + line: int | None = ..., + **kwargs: object, ) -> nodes.system_message: ... class SystemMessage(ApplicationError): - level: _SystemMessageLevel - def __init__(self, system_message: object, level: _SystemMessageLevel): ... + level: int + def __init__(self, system_message: nodes.system_message, level: int) -> None: ... -def new_reporter(source_path: str, settings: optparse.Values) -> Reporter: ... -def new_document(source_path: str, settings: optparse.Values | None = None) -> document: ... +def new_reporter(source_path: StrPath, settings: Values) -> Reporter: ... +def new_document(source_path: StrPath, settings: Values | None = None) -> document: ... class ExtensionOptionError(DataError): ... class BadOptionError(ExtensionOptionError): ... class BadOptionDataError(ExtensionOptionError): ... class DuplicateOptionError(ExtensionOptionError): ... +# Option conversion functions are called with `None` for options without argument. def extract_extension_options( - field_list: nodes.field_list, options_spec: Mapping[str, Callable[[str], Any]] -) -> dict[str, Any]: ... -def extract_options(field_list: nodes.field_list) -> list[tuple[str, str]]: ... + field_list: nodes.field_list, options_spec: Mapping[str, Callable[[str], object]] +) -> dict[str, Any]: ... # values of arbitrary options, as returned by the conversion functions +def extract_options(field_list: nodes.field_list) -> list[tuple[str, str | None]]: ... def assemble_option_dict( - option_list: Iterable[tuple[str, str]], options_spec: Mapping[str, Callable[[str], Any]] -) -> dict[str, Any]: ... + option_list: Iterable[tuple[str, str | None]], options_spec: Mapping[str, Callable[[str], object]] +) -> dict[str, Any]: ... # values of arbitrary options, as returned by the conversion functions class NameValueError(DataError): ... @@ -116,7 +161,7 @@ def get_stylesheet_reference(settings: Values, relative_to: StrPath | None = Non def get_stylesheet_list(settings: Values) -> list[str]: ... def find_file_in_dirs(path: StrPath, dirs: Iterable[StrPath]) -> str: ... def get_trim_footnote_ref_space(settings: Values) -> bool: ... -def get_source_line(node: nodes.Node) -> tuple[str, int]: ... +def get_source_line(node: nodes.Node | None) -> tuple[str | None, int | None]: ... def escape2null(text: str) -> str: ... def split_escaped_whitespace(text: str) -> list[str]: ... def strip_combining_chars(text: str) -> str: ... @@ -128,4 +173,4 @@ east_asian_widths: dict[str, int] def column_width(text: str) -> int: ... def uniq(L: list[_T]) -> list[_T]: ... def normalize_language_tag(tag: str) -> list[str]: ... -def xml_declaration(encoding: str | None = None) -> str: ... +def xml_declaration(encoding: str | None = None) -> str: ... # encoding may be "unicode" diff --git a/stubs/docutils/docutils/utils/_roman_numerals.pyi b/stubs/docutils/docutils/utils/_roman_numerals.pyi index 0d7b27baff83..91b0a6c19213 100644 --- a/stubs/docutils/docutils/utils/_roman_numerals.pyi +++ b/stubs/docutils/docutils/utils/_roman_numerals.pyi @@ -1,7 +1,7 @@ from typing import Final, final from typing_extensions import Self -__all__ = ("MAX", "MIN", "InvalidRomanNumeralError", "OutOfRangeError", "RomanNumeral") +__all__: Final = ("MAX", "MIN", "InvalidRomanNumeralError", "OutOfRangeError", "RomanNumeral") MIN: Final = 1 MAX: Final = 4_999 @@ -15,7 +15,7 @@ class InvalidRomanNumeralError(ValueError): @final class RomanNumeral: - __slots__ = ("_value",) + __slots__: Final = ("_value",) def __init__(self, value: int, /) -> None: ... def __int__(self) -> int: ... def __eq__(self, other: object) -> bool: ... diff --git a/stubs/docutils/docutils/utils/math/math2html.pyi b/stubs/docutils/docutils/utils/math/math2html.pyi index 0972842a9ad0..46a1149dd5d4 100644 --- a/stubs/docutils/docutils/utils/math/math2html.pyi +++ b/stubs/docutils/docutils/utils/math/math2html.pyi @@ -1,8 +1,17 @@ -from _typeshed import Incomplete -from collections.abc import Generator -from typing import ClassVar, Final, TextIO, TypeVar +from collections.abc import Callable, Generator, Mapping +from typing import ClassVar, Final, Protocol, TextIO, TypeVar, type_check_only +from typing_extensions import Self _T = TypeVar("_T") +_ContainerT = TypeVar("_ContainerT", bound=Container) +_FormulaBitT = TypeVar("_FormulaBitT", bound=FormulaBit) + +# The line reader expected by the (unused) eLyXer parsers; there is no implementation in docutils. +@type_check_only +class _LineReader(Protocol): + linenumber: int + def currentline(self) -> str: ... + def nextline(self) -> None: ... __docformat__: Final = "reStructuredText" __version__: Final[str] @@ -56,23 +65,23 @@ class FormulaConfig: value: str class CommandLineParser: - options: Incomplete - def __init__(self, options) -> None: ... - def parseoptions(self, args): ... - def readoption(self, args): ... - def readquoted(self, args, initial): ... - def readequalskey(self, arg, args): ... + options: type[Options] + def __init__(self, options: type[Options]) -> None: ... + def parseoptions(self, args: list[str]) -> str | None: ... + def readoption(self, args: list[str]) -> tuple[str | None, str | bool | list[str] | None]: ... + def readquoted(self, args: list[str], initial: str) -> str | None: ... + def readequalskey(self, arg: str, args: list[str]) -> str: ... class Options: - location: Incomplete + location: str | None debug: bool quiet: bool version: bool help: bool simplemath: bool showlines: bool - branches: Incomplete - def parseoptions(self, args) -> None: ... + branches: dict[str, bool] + def parseoptions(self, args: list[str]) -> None: ... def processoptions(self) -> None: ... def usage(self) -> None: ... def showoptions(self) -> None: ... @@ -85,380 +94,382 @@ class Cloner: def create(cls, type: type[_T]) -> _T: ... class ContainerExtractor: - allowed: Incomplete - extracted: Incomplete - def __init__(self, config) -> None: ... - def extract(self, container): ... - def process(self, container, lst) -> None: ... - def safeclone(self, container): ... + allowed: list[str] + extracted: list[str] + def __init__(self, config: Mapping[str, list[str]]) -> None: ... + def extract(self, container: Container) -> list[Container]: ... + def process(self, container: Container, lst: list[Container]) -> None: ... + def safeclone(self, container: Container) -> Container: ... class Parser: begin: int - parameters: Incomplete + parameters: dict[str, str | bool] def __init__(self) -> None: ... - def parseheader(self, reader): ... - def parseparameter(self, reader) -> None: ... - def parseending(self, reader, process) -> None: ... - def parsecontainer(self, reader, contents) -> None: ... + def parseheader(self, reader: _LineReader) -> list[str]: ... + def parseparameter(self, reader: _LineReader) -> None: ... + def parseending(self, reader: _LineReader, process: Callable[[], object]) -> None: ... + def parsecontainer(self, reader: _LineReader, contents: list[Container]) -> None: ... class LoneCommand(Parser): - def parse(self, reader): ... + def parse(self, reader: _LineReader) -> list[Container]: ... class TextParser(Parser): - stack: Incomplete - ending: Incomplete - endings: Incomplete - def __init__(self, container) -> None: ... - def parse(self, reader): ... - def isending(self, reader): ... + stack: ClassVar[list[str]] + ending: str | None + endings: list[str] + def __init__(self, container: Container) -> None: ... + def parse(self, reader: _LineReader) -> list[Container]: ... + def isending(self, reader: _LineReader) -> bool: ... class ExcludingParser(Parser): - def parse(self, reader): ... + def parse(self, reader: _LineReader) -> list[Container]: ... class BoundedParser(ExcludingParser): - def parse(self, reader): ... + def parse(self, reader: _LineReader) -> list[Container]: ... class BoundedDummy(Parser): - def parse(self, reader): ... + def parse(self, reader: _LineReader) -> list[Container]: ... class StringParser(Parser): - begin: Incomplete - def parseheader(self, reader): ... - def parse(self, reader): ... + begin: int + def parseheader(self, reader: _LineReader) -> list[str]: ... + def parse(self, reader: _LineReader) -> list[Container]: ... class ContainerOutput: - def gethtml(self, container) -> None: ... - def isempty(self): ... + def gethtml(self, container: Container) -> list[str]: ... + def isempty(self) -> bool: ... class EmptyOutput(ContainerOutput): - def gethtml(self, container): ... - def isempty(self): ... + def gethtml(self, container: Container) -> list[str]: ... + def isempty(self) -> bool: ... class FixedOutput(ContainerOutput): - def gethtml(self, container): ... + def gethtml(self, container: Container) -> list[str]: ... class ContentsOutput(ContainerOutput): - def gethtml(self, container): ... + def gethtml(self, container: Container) -> list[str]: ... class TaggedOutput(ContentsOutput): - tag: Incomplete + tag: str | None breaklines: bool empty: bool - def settag(self, tag, breaklines: bool = False, empty: bool = False): ... - def setbreaklines(self, breaklines): ... - def gethtml(self, container): ... - def open(self, container): ... - def close(self, container): ... - def selfclosing(self, container): ... - def checktag(self, container): ... + def settag(self, tag: str, breaklines: bool = False, empty: bool = False) -> Self: ... + def setbreaklines(self, breaklines: bool) -> Self: ... + def gethtml(self, container: Container) -> list[str]: ... + def open(self, container: Container) -> str: ... + def close(self, container: Container) -> str: ... + def selfclosing(self, container: Container) -> str: ... + def checktag(self, container: Container) -> bool: ... class FilteredOutput(ContentsOutput): - filters: Incomplete + filters: list[tuple[str, str]] def __init__(self) -> None: ... - def addfilter(self, original, replacement) -> None: ... - def gethtml(self, container): ... - def filter(self, line): ... + def addfilter(self, original: str, replacement: str) -> None: ... + def gethtml(self, container: Container) -> list[str]: ... + def filter(self, line: str) -> str: ... class StringOutput(ContainerOutput): - def gethtml(self, container): ... + def gethtml(self, container: Container) -> list[str]: ... class Globable: leavepending: bool - endinglist: Incomplete + endinglist: EndingList def __init__(self) -> None: ... def checkbytemark(self) -> None: ... - def isout(self): ... - def current(self): ... - def checkfor(self, string): ... - def finished(self): ... - def skipcurrent(self): ... - def glob(self, currentcheck): ... - def globalpha(self): ... - def globnumber(self): ... - def isidentifier(self): ... - def globidentifier(self): ... - def isvalue(self): ... - def globvalue(self): ... - def skipspace(self): ... - def globincluding(self, magicchar): ... - def globexcluding(self, excluded): ... - def pushending(self, ending, optional: bool = False) -> None: ... - def popending(self, expected=None): ... - def nextending(self): ... + def isout(self) -> bool: ... + def current(self) -> str: ... + def checkfor(self, string: str) -> bool: ... + def finished(self) -> bool: ... + def skipcurrent(self) -> str: ... + def glob(self, currentcheck: Callable[[], bool]) -> str: ... + def globalpha(self) -> str: ... + def globnumber(self) -> str: ... + def isidentifier(self) -> bool: ... + def globidentifier(self) -> str: ... + def isvalue(self) -> bool: ... + def globvalue(self) -> str: ... + def skipspace(self) -> str: ... + def globincluding(self, magicchar: str) -> str: ... + def globexcluding(self, excluded: str) -> str: ... + def pushending(self, ending: str, optional: bool = False) -> None: ... + def popending(self, expected: str | None = None) -> str | None: ... + def nextending(self) -> str | None: ... class EndingList: - endings: Incomplete + endings: list[PositionEnding] def __init__(self) -> None: ... - def add(self, ending, optional: bool = False) -> None: ... - def pickpending(self, pos) -> None: ... - def checkin(self, pos): ... - def pop(self, pos): ... - def findending(self, pos): ... + def add(self, ending: str, optional: bool = False) -> None: ... + def pickpending(self, pos: Position) -> None: ... + def checkin(self, pos: Position) -> bool: ... + def pop(self, pos: Position) -> str: ... + def findending(self, pos: Position) -> None: ... def checkpending(self) -> None: ... class PositionEnding: - ending: Incomplete - optional: Incomplete - def __init__(self, ending, optional) -> None: ... - def checkin(self, pos): ... + ending: str + optional: bool + def __init__(self, ending: str, optional: bool) -> None: ... + def checkin(self, pos: Position) -> bool: ... class Position(Globable): def __init__(self) -> None: ... - def skip(self, string) -> None: ... - def identifier(self): ... - def extract(self, length) -> None: ... - def checkfor(self, string): ... - def checkforlower(self, string): ... - def skipcurrent(self): ... - def __next__(self): ... - def checkskip(self, string): ... - def error(self, message) -> None: ... + def skip(self, string: str) -> None: ... + def identifier(self) -> str: ... + def extract(self, length: int) -> str | None: ... + def checkfor(self, string: str) -> bool: ... + def checkforlower(self, string: str) -> bool: ... + def skipcurrent(self) -> str: ... + def __next__(self) -> str: ... + def checkskip(self, string: str) -> bool: ... + def error(self, message: str) -> None: ... class TextPosition(Position): pos: int - text: Incomplete - def __init__(self, text) -> None: ... - def skip(self, string) -> None: ... - def identifier(self): ... - def isout(self): ... - def current(self): ... - def extract(self, length): ... + text: str + def __init__(self, text: str) -> None: ... + def skip(self, string: str) -> None: ... + def identifier(self) -> str: ... + def isout(self) -> bool: ... + def current(self) -> str: ... + def extract(self, length: int) -> str: ... class Container: - partkey: Incomplete - parent: Incomplete - begin: Incomplete - contents: Incomplete + partkey: ClassVar[None] + parent: Container | None + begin: int | None + contents: list[Container] def __init__(self) -> None: ... def process(self) -> None: ... - def gethtml(self): ... - def escape(self, line, replacements={"&": "&", "<": "<", ">": ">"}): ... - def escapeentities(self, line): ... - def searchall(self, type): ... - def searchremove(self, type): ... - def searchprocess(self, type, process): ... - def locateprocess(self, locate, process) -> None: ... - def recursivesearch(self, locate, recursive, process) -> None: ... - def extracttext(self): ... - def group(self, index, group, isingroup) -> None: ... - def remove(self, index) -> None: ... + def gethtml(self) -> list[str]: ... + def escape(self, line: str, replacements: Mapping[str, str] = {"&": "&", "<": "<", ">": ">"}) -> str: ... + def escapeentities(self, line: str) -> str: ... + def searchall(self, type: type[_ContainerT]) -> list[_ContainerT]: ... + def searchremove(self, type: type[_ContainerT]) -> list[_ContainerT]: ... + def searchprocess(self, type: type[_ContainerT], process: Callable[[_ContainerT], object]) -> None: ... + def locateprocess(self, locate: Callable[[Container], bool], process: Callable[[Container], object]) -> None: ... + def recursivesearch( + self, locate: Callable[[Container], bool], recursive: Callable[[Container], bool], process: Callable[[Container], object] + ) -> None: ... + def extracttext(self) -> str: ... + def group(self, index: int, group: Container, isingroup: Callable[[Container], bool]) -> None: ... + def remove(self, index: int) -> None: ... def tree(self, level: int = 0) -> None: ... - def getparameter(self, name): ... - def getparameterlist(self, name): ... - def hasemptyoutput(self): ... + def getparameter(self, name: str) -> str | bool | None: ... + def getparameterlist(self, name: str) -> list[str]: ... + def hasemptyoutput(self) -> bool: ... class BlackBox(Container): - parser: Incomplete - output: Incomplete - contents: Incomplete + parser: LoneCommand + output: EmptyOutput + contents: list[Container] def __init__(self) -> None: ... class StringContainer(Container): - parsed: Incomplete - parser: Incomplete - output: Incomplete + parsed: str | None + parser: StringParser + output: StringOutput string: str def __init__(self) -> None: ... def process(self) -> None: ... - def replacespecial(self, line): ... - def changeline(self, line): ... - def extracttext(self): ... + def replacespecial(self, line: str) -> str: ... + def changeline(self, line: str) -> str: ... + def extracttext(self) -> str: ... class Constant(StringContainer): - contents: Incomplete - string: Incomplete - output: Incomplete - def __init__(self, text) -> None: ... + contents: list[Container] + string: str + output: StringOutput + def __init__(self, text: str) -> None: ... class DocumentParameters: displaymode: bool class FormulaParser(Parser): - begin: Incomplete - def parseheader(self, reader): ... - def parsetype(self, reader): ... - def parse(self, reader): ... - def parseformula(self, reader): ... - def parsesingleliner(self, reader, start, ending): ... - def parsemultiliner(self, reader, start, ending): ... + begin: int + def parseheader(self, reader: _LineReader) -> list[str]: ... + def parsetype(self, reader: _LineReader) -> str | None: ... + def parse(self, reader: _LineReader) -> str: ... + def parseformula(self, reader: _LineReader) -> str: ... + def parsesingleliner(self, reader: _LineReader, start: str, ending: str) -> str: ... + def parsemultiliner(self, reader: _LineReader, start: str, ending: str) -> str: ... class FormulaBit(Container): type: str | None size: int original: str - contents: Incomplete - output: Incomplete + contents: list[Container] + output: ContainerOutput def __init__(self) -> None: ... - factory: Incomplete - def setfactory(self, factory): ... - def add(self, bit) -> None: ... - def skiporiginal(self, string, pos) -> None: ... - def computesize(self): ... - def clone(self): ... + factory: FormulaFactory + def setfactory(self, factory: FormulaFactory) -> Self: ... + def add(self, bit: FormulaBit | FormulaConstant) -> None: ... + def skiporiginal(self, string: str, pos: Position) -> None: ... + def computesize(self) -> int: ... + def clone(self) -> FormulaBit: ... # re-parses the original text class TaggedBit(FormulaBit): - output: Incomplete - def constant(self, constant, tag): ... - contents: Incomplete - def complete(self, contents, tag, breaklines: bool = False): ... - def selfcomplete(self, tag): ... + output: TaggedOutput + def constant(self, constant: str, tag: str) -> Self: ... + contents: list[Container] + def complete(self, contents: list[Container], tag: str, breaklines: bool = False) -> Self: ... + def selfcomplete(self, tag: str) -> Self: ... class FormulaConstant(Constant): - original: Incomplete + original: str size: int type: str | None - def __init__(self, string) -> None: ... - def computesize(self): ... - def clone(self): ... + def __init__(self, string: str) -> None: ... + def computesize(self) -> int: ... + def clone(self) -> FormulaConstant: ... class RawText(FormulaBit): - def detect(self, pos): ... - def parsebit(self, pos) -> None: ... + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... class FormulaSymbol(FormulaBit): - modified: Incomplete - unmodified: Incomplete - def detect(self, pos): ... - def parsebit(self, pos) -> None: ... - def addsymbol(self, symbol, pos) -> None: ... + modified: ClassVar[dict[str, str]] + unmodified: ClassVar[list[str]] + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... + def addsymbol(self, symbol: str, pos: Position) -> None: ... class FormulaNumber(FormulaBit): - def detect(self, pos): ... - def parsebit(self, pos): ... + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... class Comment(FormulaBit): - start: Incomplete - def detect(self, pos): ... - def parsebit(self, pos) -> None: ... + start: ClassVar[str] + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... class WhiteSpace(FormulaBit): - def detect(self, pos): ... - def parsebit(self, pos) -> None: ... + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... class Bracket(FormulaBit): - start: Incomplete - ending: Incomplete - inner: Incomplete + start: ClassVar[str] + ending: ClassVar[str] + inner: None def __init__(self) -> None: ... - def detect(self, pos): ... - def parsebit(self, pos): ... - def parsetext(self, pos): ... - def parseliteral(self, pos): ... - def parsecomplete(self, pos, innerparser) -> None: ... - def innerformula(self, pos) -> None: ... - def innertext(self, pos) -> None: ... + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> Self: ... + def parsetext(self, pos: Position) -> Self: ... + def parseliteral(self, pos: Position) -> Self: ... + def parsecomplete(self, pos: Position, innerparser: Callable[[Position], object]) -> None: ... + def innerformula(self, pos: Position) -> None: ... + def innertext(self, pos: Position) -> None: ... literal: str - def innerliteral(self, pos) -> None: ... + def innerliteral(self, pos: Position) -> None: ... class SquareBracket(Bracket): - start: Incomplete - ending: Incomplete - def clone(self): ... + start: ClassVar[str] + ending: ClassVar[str] + def clone(self) -> SquareBracket: ... class MathsProcessor: - def process(self, contents, index) -> None: ... + def process(self, contents: list[Container], index: int) -> None: ... class FormulaProcessor: - processors: Incomplete - def process(self, bit) -> None: ... - def processcontents(self, bit) -> None: ... - def processinsides(self, bit) -> None: ... - def traversewhole(self, formula) -> None: ... - def traverse(self, bit) -> Generator[Incomplete, Incomplete]: ... - def italicize(self, bit, contents) -> None: ... + processors: ClassVar[list[MathsProcessor]] + def process(self, bit: WholeFormula) -> None: ... + def processcontents(self, bit: FormulaBit) -> None: ... + def processinsides(self, bit: FormulaBit) -> None: ... + def traversewhole(self, formula: WholeFormula) -> None: ... + def traverse(self, bit: FormulaBit) -> Generator[tuple[Container, list[Container]]]: ... + def italicize(self, bit: FormulaBit, contents: list[Container]) -> None: ... class Formula(Container): - parser: Incomplete - output: Incomplete + parser: FormulaParser + output: TaggedOutput def __init__(self) -> None: ... def process(self) -> None: ... - contents: Incomplete + contents: list[Container] def classic(self) -> None: ... - def parse(self, pos): ... - header: Incomplete - def parsedollarinline(self, pos) -> None: ... - def parsedollarblock(self, pos) -> None: ... - parsed: Incomplete - def parsedollar(self, pos) -> None: ... - def parseinlineto(self, pos, limit) -> None: ... - def parseblockto(self, pos, limit) -> None: ... - def parseupto(self, pos, limit): ... + def parse(self, pos: Position) -> Self: ... + header: list[str] + def parsedollarinline(self, pos: Position) -> None: ... + def parsedollarblock(self, pos: Position) -> None: ... + parsed: str + def parsedollar(self, pos: Position) -> None: ... + def parseinlineto(self, pos: Position, limit: str) -> None: ... + def parseblockto(self, pos: Position, limit: str) -> None: ... + def parseupto(self, pos: Position, limit: str) -> None: ... class WholeFormula(FormulaBit): - def detect(self, pos): ... - def parsebit(self, pos) -> None: ... + def detect(self, pos: Position) -> bool: ... + def parsebit(self, pos: Position) -> None: ... class FormulaFactory: - types: Incomplete - skippedtypes: Incomplete + types: ClassVar[list[type[FormulaBit]]] + skippedtypes: ClassVar[list[type[FormulaBit]]] defining: bool - instances: Incomplete + instances: dict[type[FormulaBit], FormulaBit] def __init__(self) -> None: ... - def detecttype(self, type, pos): ... - def instance(self, type): ... - def create(self, type): ... - def clearskipped(self, pos) -> None: ... - def skipany(self, pos): ... - def parseany(self, pos): ... - def parsetype(self, type, pos): ... - def parseformula(self, formula): ... + def detecttype(self, type: type[FormulaBit], pos: Position) -> bool: ... + def instance(self, type: type[_FormulaBitT]) -> _FormulaBitT: ... + def create(self, type: type[_FormulaBitT]) -> _FormulaBitT: ... + def clearskipped(self, pos: Position) -> None: ... + def skipany(self, pos: Position) -> FormulaBit | None: ... + def parseany(self, pos: Position) -> FormulaBit: ... + def parsetype(self, type: type[FormulaBit], pos: Position) -> FormulaBit | None: ... + def parseformula(self, formula: str) -> WholeFormula: ... class FormulaCommand(FormulaBit): - types: Incomplete - start: Incomplete + types: ClassVar[list[type[CommandBit]]] + start: ClassVar[str] commandmap: ClassVar[dict[str, str] | dict[str, list[str]] | None] - def detect(self, pos): ... - output: Incomplete - def parsebit(self, pos): ... - def parsewithcommand(self, command, pos): ... - def parsecommandtype(self, command, type, pos): ... - def extractcommand(self, pos): ... - def emptycommand(self, pos): ... - def parseupgreek(self, command, pos): ... + def detect(self, pos: Position) -> bool: ... + output: ContainerOutput + def parsebit(self, pos: Position) -> FormulaBit | None: ... + def parsewithcommand(self, command: str, pos: Position) -> FormulaBit | None: ... + def parsecommandtype(self, command: str, type: type[CommandBit], pos: Position) -> FormulaBit: ... + def extractcommand(self, pos: Position) -> str | None: ... + def emptycommand(self, pos: Position) -> str: ... + def parseupgreek(self, command: str, pos: Position) -> FormulaBit | None: ... class CommandBit(FormulaCommand): - command: Incomplete - translated: Incomplete - def setcommand(self, command) -> None: ... - def parseparameter(self, pos): ... - def parsesquare(self, pos): ... - def parseliteral(self, pos): ... - def parsesquareliteral(self, pos): ... - def parsetext(self, pos): ... + command: str + translated: str | list[str] + def setcommand(self, command: str) -> None: ... + def parseparameter(self, pos: Position) -> Bracket | None: ... + def parsesquare(self, pos: Position) -> SquareBracket | None: ... + def parseliteral(self, pos: Position) -> str | None: ... + def parsesquareliteral(self, pos: Position) -> str | None: ... + def parsetext(self, pos: Position) -> Bracket | None: ... class EmptyCommand(CommandBit): - commandmap: ClassVar[dict[str, str]] - contents: Incomplete - def parsebit(self, pos) -> None: ... + commandmap: ClassVar[dict[str, str] | None] # `None` in `LimitPreviousCommand` + contents: list[Container] + def parsebit(self, pos: Position) -> None: ... class SpacedCommand(CommandBit): commandmap: ClassVar[dict[str, str]] - contents: Incomplete - def parsebit(self, pos) -> None: ... + contents: list[Container] + def parsebit(self, pos: Position) -> None: ... class AlphaCommand(EmptyCommand): commandmap: ClassVar[dict[str, str]] - greek_capitals: Incomplete - def parsebit(self, pos) -> None: ... + greek_capitals: ClassVar[tuple[str, ...]] + def parsebit(self, pos: Position) -> None: ... class OneParamFunction(CommandBit): commandmap: ClassVar[dict[str, str]] simplified: bool - output: Incomplete - def parsebit(self, pos) -> None: ... - html: Incomplete + output: ContainerOutput + def parsebit(self, pos: Position) -> None: ... + html: list[str] def simplifyifpossible(self) -> None: ... class SymbolFunction(CommandBit): commandmap: ClassVar[dict[str, str]] - def detect(self, pos): ... - output: Incomplete - def parsebit(self, pos) -> None: ... + def detect(self, pos: Position) -> bool: ... + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... class TextFunction(CommandBit): commandmap: ClassVar[dict[str, str]] - output: Incomplete - def parsebit(self, pos) -> None: ... + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... def process(self) -> None: ... class FontFunction(OneParamFunction): @@ -466,173 +477,173 @@ class FontFunction(OneParamFunction): def process(self) -> None: ... class BigBracket: - size: Incomplete - original: Incomplete - alignment: Incomplete - pieces: Incomplete - def __init__(self, size, bracket, alignment: str = "l") -> None: ... - def getpiece(self, index): ... - def getpiece1(self, index): ... - def getpiece3(self, index): ... - def getpiece4(self, index): ... - def getcell(self, index): ... - def getcontents(self): ... - def getsinglebracket(self): ... + size: int + original: str + alignment: str + pieces: list[str] | None + def __init__(self, size: int, bracket: str, alignment: str = "l") -> None: ... + def getpiece(self, index: int) -> str: ... + def getpiece1(self, index: int) -> str: ... + def getpiece3(self, index: int) -> str: ... + def getpiece4(self, index: int) -> str: ... + def getcell(self, index: int) -> TaggedBit: ... + def getcontents(self) -> list[TaggedBit]: ... + def getsinglebracket(self) -> list[TaggedBit]: ... class FormulaEquation(CommandBit): piece: str - output: Incomplete - def parsebit(self, pos) -> None: ... + output: ContentsOutput + def parsebit(self, pos: Position) -> None: ... class FormulaCell(FormulaCommand): - alignment: Incomplete - output: Incomplete - def setalignment(self, alignment): ... - def parsebit(self, pos) -> None: ... + alignment: str + output: TaggedOutput + def setalignment(self, alignment: str) -> Self: ... + def parsebit(self, pos: Position) -> None: ... class FormulaRow(FormulaCommand): - cellseparator: Incomplete - alignments: Incomplete - output: Incomplete - def setalignments(self, alignments): ... - def parsebit(self, pos) -> None: ... - def createcell(self, index): ... + cellseparator: ClassVar[str] + alignments: list[str] + output: ContainerOutput + def setalignments(self, alignments: list[str]) -> Self: ... + def parsebit(self, pos: Position) -> None: ... + def createcell(self, index: int) -> FormulaCell: ... class MultiRowFormula(CommandBit): - rows: Incomplete - size: Incomplete - def parserows(self, pos) -> None: ... - def iteraterows(self, pos) -> Generator[Incomplete]: ... + rows: list[FormulaRow] + size: int + def parserows(self, pos: Position) -> None: ... + def iteraterows(self, pos: Position) -> Generator[FormulaRow]: ... def addempty(self) -> None: ... - def addrow(self, row) -> None: ... + def addrow(self, row: FormulaRow) -> None: ... class FormulaArray(MultiRowFormula): piece: str - output: Incomplete - def parsebit(self, pos) -> None: ... + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... valign: str - alignments: Incomplete - def parsealignments(self, pos) -> None: ... + alignments: list[str] + def parsealignments(self, pos: Position) -> None: ... class FormulaMatrix(MultiRowFormula): piece: str - output: Incomplete + output: TaggedOutput valign: str - alignments: Incomplete - def parsebit(self, pos) -> None: ... + alignments: list[str] + def parsebit(self, pos: Position) -> None: ... class FormulaCases(MultiRowFormula): piece: str - output: Incomplete - alignments: Incomplete - contents: Incomplete - def parsebit(self, pos) -> None: ... + output: ContentsOutput + alignments: list[str] + contents: list[Container] + def parsebit(self, pos: Position) -> None: ... class EquationEnvironment(MultiRowFormula): - output: Incomplete - alignments: Incomplete - def parsebit(self, pos) -> None: ... + output: TaggedOutput + alignments: list[str] + def parsebit(self, pos: Position) -> None: ... class BeginCommand(CommandBit): commandmap: ClassVar[dict[str, str]] - types: Incomplete - size: Incomplete - def parsebit(self, pos) -> None: ... - def findbit(self, piece): ... + types: ClassVar[list[type[CommandBit]]] + size: int + def parsebit(self, pos: Position) -> None: ... + def findbit(self, piece: str) -> CommandBit: ... class CombiningFunction(OneParamFunction): commandmap: ClassVar[dict[str, str]] - def parsebit(self, pos) -> None: ... - def parsesingleparameter(self, pos): ... + def parsebit(self, pos: Position) -> None: ... + def parsesingleparameter(self, pos: Position) -> Bracket | None: ... class OversetFunction(OneParamFunction): commandmap: ClassVar[dict[str, str]] - symbol: Incomplete - parameter: Incomplete - output: Incomplete - def parsebit(self, pos) -> None: ... + symbol: TaggedBit + parameter: Bracket | None + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... class UndersetFunction(OneParamFunction): commandmap: ClassVar[dict[str, str]] - symbol: Incomplete - parameter: Incomplete - output: Incomplete - def parsebit(self, pos) -> None: ... + symbol: TaggedBit + parameter: Bracket | None + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... class LimitCommand(EmptyCommand): - commandmap: ClassVar[dict[str, str]] - output: Incomplete - def parsebit(self, pos) -> None: ... + commandmap: ClassVar[dict[str, str] | None] + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... class LimitPreviousCommand(LimitCommand): - commandmap: ClassVar[None] # type: ignore[assignment] - output: Incomplete - def parsebit(self, pos) -> None: ... + commandmap: ClassVar[None] + output: TaggedOutput + def parsebit(self, pos: Position) -> None: ... class LimitsProcessor(MathsProcessor): - def process(self, contents, index) -> None: ... - def checklimits(self, contents, index): ... - def limitsahead(self, contents, index) -> None: ... - def modifylimits(self, contents, index) -> None: ... - def getlimit(self, contents, index): ... - def modifyscripts(self, contents, index) -> None: ... - def checkscript(self, contents, index): ... - def checkcommand(self, contents, index, type): ... - def getscript(self, contents, index): ... + def process(self, contents: list[Container], index: int) -> None: ... + def checklimits(self, contents: list[Container], index: int) -> bool: ... + def limitsahead(self, contents: list[Container], index: int) -> None: ... + def modifylimits(self, contents: list[Container], index: int) -> None: ... + def getlimit(self, contents: list[Container], index: int) -> Container: ... + def modifyscripts(self, contents: list[Container], index: int) -> None: ... + def checkscript(self, contents: list[Container], index: int) -> bool: ... + def checkcommand(self, contents: list[Container], index: int, type: type[Container]) -> bool: ... + def getscript(self, contents: list[Container], index: int) -> Container: ... class BracketCommand(OneParamFunction): commandmap: ClassVar[dict[str, str]] - def parsebit(self, pos) -> None: ... - original: Incomplete - command: Incomplete - contents: Incomplete - def create(self, direction, character): ... + def parsebit(self, pos: Position) -> None: ... + original: str + command: str + contents: list[Container] + def create(self, direction: str, character: str) -> Self: ... class BracketProcessor(MathsProcessor): - def process(self, contents, index): ... - def processleft(self, contents, index) -> None: ... - def checkleft(self, contents, index): ... - def checkright(self, contents, index): ... - def checkdirection(self, bit, command): ... - def findright(self, contents, index): ... - def findmax(self, contents, leftindex, rightindex): ... - def resize(self, command, size) -> None: ... + def process(self, contents: list[Container], index: int) -> None: ... + def processleft(self, contents: list[Container], index: int) -> None: ... + def checkleft(self, contents: list[Container], index: int) -> bool: ... + def checkright(self, contents: list[Container], index: int) -> bool: ... + def checkdirection(self, bit: Container, command: str) -> bool: ... + def findright(self, contents: list[Container], index: int) -> int | None: ... + def findmax(self, contents: list[Container], leftindex: int, rightindex: int) -> int: ... + def resize(self, command: str, size: int) -> None: ... class ParameterDefinition: parambrackets: ClassVar[list[tuple[str, str]]] name: str literal: bool optional: bool - value: Incomplete - literalvalue: Incomplete + value: FormulaBit | None + literalvalue: str | None def __init__(self) -> None: ... - def parse(self, pos): ... - def read(self, pos, function) -> None: ... + def parse(self, pos: Position) -> Self | None: ... + def read(self, pos: Position, function: ParameterFunction) -> None: ... class ParameterFunction(CommandBit): - params: Incomplete - def readparams(self, readtemplate, pos) -> None: ... - def paramdefs(self, readtemplate) -> Generator[Incomplete]: ... - def getparam(self, name): ... - def getvalue(self, name): ... - def getliteralvalue(self, name): ... + params: dict[str, ParameterDefinition] + def readparams(self, readtemplate: str, pos: Position) -> None: ... + def paramdefs(self, readtemplate: str) -> Generator[ParameterDefinition]: ... + def getparam(self, name: str) -> ParameterDefinition | None: ... + def getvalue(self, name: str) -> FormulaBit | None: ... + def getliteralvalue(self, name: str) -> str | None: ... class HybridFunction(ParameterFunction): commandmap: ClassVar[dict[str, list[str]]] - contents: Incomplete - def parsebit(self, pos) -> None: ... - def writeparams(self, writetemplate): ... - def writepos(self, pos): ... - def writeparam(self, pos): ... - def writefunction(self, pos): ... - def readtag(self, pos): ... - def writebracket(self, direction, character): ... - size: Incomplete + contents: list[Container] + def parsebit(self, pos: Position) -> None: ... + def writeparams(self, writetemplate: str) -> list[Container]: ... + def writepos(self, pos: Position) -> list[Container]: ... + def writeparam(self, pos: Position) -> FormulaBit | None: ... + def writefunction(self, pos: Position) -> TaggedBit | None: ... + def readtag(self, pos: Position) -> str | None: ... + def writebracket(self, direction: str, character: str) -> BracketCommand: ... + size: int def computehybridsize(self) -> None: ... class HybridSize: configsizes: ClassVar[dict[str, str]] - def getsize(self, function): ... + def getsize(self, function: ParameterFunction) -> int: ... -def math2html(formula): ... +def math2html(formula: str) -> str: ... def main() -> None: ... diff --git a/stubs/docutils/docutils/utils/math/mathml_elements.pyi b/stubs/docutils/docutils/utils/math/mathml_elements.pyi index d55220a93166..4f41026528ce 100644 --- a/stubs/docutils/docutils/utils/math/mathml_elements.pyi +++ b/stubs/docutils/docutils/utils/math/mathml_elements.pyi @@ -2,7 +2,6 @@ import numbers import xml.etree.ElementTree as ET from collections.abc import Iterable from typing import ClassVar, Final, SupportsIndex, overload -from typing_extensions import Self __docformat__: Final = "reStructuredText" GLOBAL_ATTRIBUTES: Final[tuple[str, ...]] @@ -10,7 +9,7 @@ GLOBAL_ATTRIBUTES: Final[tuple[str, ...]] class MathElement(ET.Element): nchildren: ClassVar[int | None] parent: MathElement | None - def __init__(self, *children, **attributes: object) -> None: ... # attributes is passed to self.a_str method + def __init__(self, *children: MathElement, **attributes: object) -> None: ... # attributes is passed to self.a_str method @staticmethod def a_str(v: object) -> str: ... def set(self, key: str, value: object) -> None: ... # value is passed to self.a_str method @@ -22,9 +21,11 @@ class MathElement(ET.Element): def is_full(self) -> bool: ... def close(self) -> MathElement | None: ... - def append(self, element: MathElement) -> Self: ... # type: ignore[override] - def extend(self, elements: Iterable[MathElement]) -> Self: ... # type: ignore[override] - def pop(self, index: int = -1): ... + # Return the new "current node" (insertion point): `self`, or, if `self` is full + # after appending, the first non-full ancestor or `None` (see `close()`). + def append(self, element: MathElement) -> MathElement | None: ... # type: ignore[override] + def extend(self, elements: Iterable[MathElement]) -> MathElement | None: ... # type: ignore[override] + def pop(self, index: int = -1) -> MathElement: ... def in_block(self) -> bool: ... def indent_xml(self, space: str = " ", level: int = 0) -> None: ... def unindent_xml(self) -> None: ... @@ -35,7 +36,7 @@ class MathRow(MathElement): ... class MathSchema(MathElement): nchildren: ClassVar[int] switch: bool - def __init__(self, *children, switch: bool = False, **kwargs) -> None: ... + def __init__(self, *children: MathElement, switch: bool = False, **kwargs: object) -> None: ... class MathToken(MathElement): nchildren: ClassVar[int] @@ -52,7 +53,7 @@ class mspace(MathElement): nchildren: ClassVar[int] class mrow(MathRow): - def transfer_attributes(self, other) -> None: ... + def transfer_attributes(self, other: MathElement) -> None: ... class mfrac(MathSchema): ... diff --git a/stubs/docutils/docutils/utils/smartquotes.pyi b/stubs/docutils/docutils/utils/smartquotes.pyi index 1d68592d288c..a51bb6efca28 100644 --- a/stubs/docutils/docutils/utils/smartquotes.pyi +++ b/stubs/docutils/docutils/utils/smartquotes.pyi @@ -30,8 +30,8 @@ class RegularExpressions: regexes: RegularExpressions default_smartypants_attr: Final = "1" -def smartyPants(text: str, attr="1", language: str = "en") -> str: ... -def educate_tokens(text_tokens: Iterable[tuple[str, str]], attr="1", language: str = "en") -> Generator[str]: ... +def smartyPants(text: str, attr: str = "1", language: str = "en") -> str: ... +def educate_tokens(text_tokens: Iterable[tuple[str, str]], attr: str = "1", language: str = "en") -> Generator[str]: ... def educateQuotes(text: str, language: str = "en") -> str: ... def educateBackticks(text: str, language: str = "en") -> str: ... def educateSingleBackticks(text: str, language: str = "en") -> str: ... diff --git a/stubs/docutils/docutils/writers/__init__.pyi b/stubs/docutils/docutils/writers/__init__.pyi index 3fa0f555d1ae..317c8ff92950 100644 --- a/stubs/docutils/docutils/writers/__init__.pyi +++ b/stubs/docutils/docutils/writers/__init__.pyi @@ -1,77 +1,150 @@ from _typeshed import StrPath from pathlib import Path -from typing import Any, Final, Generic, TypedDict, TypeVar, type_check_only -from typing_extensions import Required +from typing import Final, Generic, TypedDict, TypeVar, type_check_only +from typing_extensions import NotRequired, Required from docutils import Component, nodes from docutils.frontend import Values from docutils.io import Output -from docutils.languages import LanguageImporter +from docutils.languages import LanguageModule _S = TypeVar("_S") __docformat__: Final = "reStructuredText" # It would probably be better to specialize writers for subclasses, -# but this gives us all possible Writer items w/o instance checks +# but this gives us all possible Writer items without instance checks +# Parameters provided by any and all docutils :class:docutils.writers.`Writer`. +# +# See: +# +# +# +# +# +# +# @type_check_only class _WriterParts(TypedDict, total=False): - # Parts Provided by All Writers https://docutils.sourceforge.io/docs/api/publisher.html#parts-provided-by-all-writers - - # See Writer.assemble_parts + # Required/provided by all writers. whole: Required[str | bytes] + # Required/provided by all writers. encoding: Required[str] + # Required/provided by all writers. errors: Required[str] + # Required/provided by all writers. version: Required[str] - - # Parts Provided by the HTML Writers https://docutils.sourceforge.io/docs/api/publisher.html#parts-provided-by-the-html-writers - - # HTML4 Writer https://docutils.sourceforge.io/docs/api/publisher.html#html4-writer - # + HTML5 Writer https://docutils.sourceforge.io/docs/api/publisher.html#html5-writer + # Required/provided by HTML and (Xe)LaTeX writers. body: str + # Required/provided by HTML writers. body_prefix: str + # Required/provided by HTML and (Xe)LaTeX writers. body_pre_docinfo: str + # Required/provided by HTML writers. body_suffix: str + # Required/provided by HTML and (Xe)LaTeX writers. docinfo: str + # Required/provided by HTML writers. footer: str + # Required/provided by HTML writers. fragment: str + # Required/provided by HTML writers. head: str + # Required/provided by HTML and (Xe)LaTeX writers. head_prefix: str + # Required/provided by HTML writers. header: str + # Required/provided by HTML writers. html_body: str + # Required/provided by HTML writers. html_head: str + # Required/provided by HTML writers. html_prolog: str + # Required/provided by HTML writers. html_subtitle: str + # Required/provided by HTML writers. html_title: str + # Required/provided by HTML writers. meta: str + # Required/provided by HTML and (Xe)LaTeX writers. stylesheet: str + # Required/provided by HTML and (Xe)LaTeX writers. subtitle: str + # Required/provided by HTML and (Xe)LaTeX writers. title: str - # PEP/HTML Writer https://docutils.sourceforge.io/docs/api/publisher.html#pep-html-writer - # + S5/HTML Writer https://docutils.sourceforge.io/docs/api/publisher.html#s5-html-writer + # Required/provided by PEP/HTML and S5/HTML writers. pepnum: str + # Required/provided by (Xe)LaTeX writers. + abstract: str + # Required/provided by (Xe)LaTeX writers. + dedication: str + # Required/provided by (Xe)LaTeX writers. + fallbacks: str + # Required/provided by (Xe)LaTeX writers. + latex_preamble: str + # Required/provided by (Xe)LaTeX writers. + pdfsetup: str + # Required/provided by (Xe)LaTeX writers. + requirements: str + # Required/provided by (Xe)LaTeX writers. + template: str + # Required/provided by (Xe)LaTeX writers. + titledata: str - # Parts Provided by the (Xe)LaTeX Writers https://docutils.sourceforge.io/docs/api/publisher.html#parts-provided-by-the-xe-latex-writers +# Parts returned by HTML writers (e.g. "html4css1", "html5_polyglot", "s5_html", "pep_html"). +@type_check_only +class _HTMLWriterParts(TypedDict, total=True): # noqa: Y049 # used by `core.publish_parts()` + whole: str + encoding: str + errors: str + version: str + body: str + body_prefix: str + body_pre_docinfo: str + body_suffix: str + docinfo: str + footer: str + fragment: str + head: str + head_prefix: str + header: str + html_body: str + html_head: str + html_prolog: str + html_subtitle: str + html_title: str + meta: str + stylesheet: str + subtitle: str + title: str + pepnum: NotRequired[str] # only "pep_html" - # (commenting out those already included) +# Parts returned by the (Xe)LaTeX writers ("latex2e", "xetex"). +@type_check_only +class _LaTeXWriterParts(TypedDict, total=True): # noqa: Y049 # used by `core.publish_parts()` + whole: str + encoding: str + errors: str + version: str abstract: str - # body: str - # body_pre_docinfo: str + body: str + body_pre_docinfo: str dedication: str - # docinfo: str + docinfo: str fallbacks: str - # head_prefix: str + head_prefix: str latex_preamble: str pdfsetup: str requirements: str - # stylesheet: str - # subtitle: str - # title: str + stylesheet: str + subtitle: str + template: str + title: str titledata: str class Writer(Component, Generic[_S]): parts: _WriterParts - language: LanguageImporter | None = None + language: LanguageModule | None = None document: nodes.document | None = None destination: Output | None = None output: _S | None = None @@ -89,4 +162,4 @@ class DoctreeTranslator(nodes.NodeVisitor): WRITER_ALIASES: Final[dict[str, str]] -def get_writer_class(writer_name: str) -> type[Writer[Any]]: ... +def get_writer_class(writer_name: str) -> type[Writer[str | bytes]]: ... diff --git a/stubs/docutils/docutils/writers/_html_base.pyi b/stubs/docutils/docutils/writers/_html_base.pyi index dccf180e85ce..1de5bc287d2b 100644 --- a/stubs/docutils/docutils/writers/_html_base.pyi +++ b/stubs/docutils/docutils/writers/_html_base.pyi @@ -1,12 +1,12 @@ -from _typeshed import Incomplete, StrPath -from collections.abc import Callable +from _typeshed import StrPath +from collections.abc import Callable, Mapping from re import Pattern -from typing import ClassVar, Final +from typing import Any, ClassVar, Final from typing_extensions import Never from docutils import nodes, writers from docutils.frontend import Values -from docutils.languages import _LanguageModule +from docutils.languages import LanguageModule __docformat__: Final = "reStructuredText" @@ -40,31 +40,32 @@ class HTMLTranslator(nodes.NodeVisitor): videotypes: ClassVar[tuple[str, ...]] attribution_formats: ClassVar[dict[str, tuple[str, str]]] settings: Values - language: _LanguageModule + language: LanguageModule initial_header_level: int image_loading: str body: list[str] body_prefix: list[str] - body_pre_docinfo: list[Incomplete] + body_pre_docinfo: list[str] body_suffix: list[str] docinfo: list[str] footer: list[str] - fragment: list[Incomplete] - head: list[Incomplete] - head_prefix: list[Incomplete] - header: list[Incomplete] - html_body: list[Incomplete] - html_head: list[Incomplete] - html_prolog: list[Incomplete] - html_subtitle: list[Incomplete] - html_title: list[Incomplete] - meta: list[Incomplete] - stylesheet: list[Incomplete] - title: list[Incomplete] - subtitle: list[Incomplete] - context: list[Incomplete] + fragment: list[str] + head: list[str] + head_prefix: list[str] + header: list[str] + html_body: list[str] + html_head: list[str] + html_prolog: list[str] + html_subtitle: list[str] + html_title: list[str] + meta: list[str] + stylesheet: list[str] + title: list[str] + subtitle: list[str] + # A stack of heterogeneous values (closing tags, flags, body positions, ...) used by visit/depart pairs. + context: list[Any] section_level: int - colspecs: list[Incomplete] + colspecs: list[nodes.colspec] compact_p: bool compact_simple: bool compact_field_list: bool @@ -74,7 +75,7 @@ class HTMLTranslator(nodes.NodeVisitor): in_mailto: bool author_in_authors: bool math_header: list[str] - messages: list[Incomplete] + messages: list[nodes.system_message] def __init__(self, document: nodes.document) -> None: ... def astext(self) -> str: ... def attval(self, text: str, whitespace: Pattern[str] = ...) -> str: ... @@ -82,13 +83,16 @@ class HTMLTranslator(nodes.NodeVisitor): def cloak_mailto(self, uri: str) -> str: ... def encode(self, text: object) -> str: ... def image_size(self, node: nodes.image) -> str: ... - def read_size_with_PIL(self, node) -> tuple[int, int] | None: ... - def prepare_svg(self, code: str | bytes, node: nodes.Element, atts: dict[str, Incomplete]) -> str: ... + def read_size_with_PIL(self, node: nodes.image) -> tuple[int, int] | None: ... + def prepare_svg(self, code: str, node: nodes.Element, atts: Mapping[str, str | int | float]) -> str: ... def stylesheet_call(self, path: StrPath, adjust_path: bool | None = None) -> str: ... - def starttag(self, node: nodes.Element, tagname: str, suffix: str = "\n", empty: bool = False, **attributes) -> str: ... - def emptytag(self, node: nodes.Element, tagname: str, suffix: str = "\n", **attributes) -> str: ... + # `attributes` are HTML attributes; values are converted with `str()`, lists are space-joined. + def starttag( + self, node: nodes.Element, tagname: str, suffix: str = "\n", empty: bool = False, **attributes: object + ) -> str: ... + def emptytag(self, node: nodes.Element, tagname: str, suffix: str = "\n", **attributes: object) -> str: ... def report_messages(self, node: nodes.Node) -> None: ... - def set_class_on_child(self, node, class_, index: int = 0) -> None: ... + def set_class_on_child(self, node: nodes.Element, class_: str, index: int = 0) -> None: ... def visit_Text(self, node: nodes.Text) -> None: ... def depart_Text(self, node: nodes.Text) -> None: ... def visit_abbreviation(self, node: nodes.abbreviation) -> None: ... @@ -144,7 +148,7 @@ class HTMLTranslator(nodes.NodeVisitor): def depart_description(self, node: nodes.description) -> None: ... def visit_docinfo(self, node: nodes.docinfo) -> None: ... def depart_docinfo(self, node: nodes.docinfo) -> None: ... - def visit_docinfo_item(self, node, name: str, meta: bool = True) -> None: ... + def visit_docinfo_item(self, node: nodes.Element, name: str, meta: bool = True) -> None: ... def depart_docinfo_item(self) -> None: ... def visit_doctest_block(self, node: nodes.doctest_block) -> None: ... def depart_doctest_block(self, node: nodes.doctest_block) -> None: ... @@ -195,7 +199,8 @@ class HTMLTranslator(nodes.NodeVisitor): def visit_literal_block(self, node: nodes.literal_block) -> None: ... def depart_literal_block(self, node: nodes.literal_block) -> None: ... math_tags: dict[str, tuple[str, str, list[str]]] - math_output: str | Incomplete + math_output: str + math_options: str def visit_math(self, node: nodes.math) -> None: ... def depart_math(self, node: nodes.math) -> None: ... def visit_math_block(self, node: nodes.math_block) -> None: ... diff --git a/stubs/docutils/docutils/writers/docutils_xml.pyi b/stubs/docutils/docutils/writers/docutils_xml.pyi index dfd4096071d4..9851c613c9dd 100644 --- a/stubs/docutils/docutils/writers/docutils_xml.pyi +++ b/stubs/docutils/docutils/writers/docutils_xml.pyi @@ -1,4 +1,3 @@ -from collections.abc import Callable from typing import ClassVar, Final from xml.sax.handler import ContentHandler from xml.sax.xmlreader import Locator, XMLReader @@ -6,6 +5,7 @@ from xml.sax.xmlreader import Locator, XMLReader import docutils from docutils import nodes, writers from docutils.frontend import Values +from docutils.utils import _ReporterMessageMethod __docformat__: Final = "reStructuredText" @@ -22,8 +22,8 @@ class XMLTranslator(nodes.GenericNodeVisitor): doctype: ClassVar[str] generator: ClassVar[str] xmlparser: ClassVar[XMLReader] - warn: Callable[..., nodes.system_message] - error: Callable[..., nodes.system_message] + warn: _ReporterMessageMethod + error: _ReporterMessageMethod settings: Values indent: str newline: str diff --git a/stubs/docutils/docutils/writers/html4css1/__init__.pyi b/stubs/docutils/docutils/writers/html4css1/__init__.pyi index 76da0b68d282..9674bad831a0 100644 --- a/stubs/docutils/docutils/writers/html4css1/__init__.pyi +++ b/stubs/docutils/docutils/writers/html4css1/__init__.pyi @@ -1,4 +1,3 @@ -from _typeshed import Incomplete from typing import ClassVar, Final from docutils import nodes @@ -17,7 +16,7 @@ class HTMLTranslator(_html_base.HTMLTranslator): content_type: ClassVar[str] content_type_mathml: ClassVar[str] object_image_types: ClassVar[dict[str, str]] - def set_first_last(self, node) -> None: ... + def set_first_last(self, node: nodes.Element) -> None: ... def visit_address(self, node: nodes.address) -> None: ... def depart_address(self, node: nodes.address) -> None: ... def visit_admonition(self, node: nodes.admonition) -> None: ... @@ -48,23 +47,23 @@ class HTMLTranslator(_html_base.HTMLTranslator): def depart_description(self, node: nodes.description) -> None: ... in_docinfo: bool def visit_docinfo(self, node: nodes.docinfo) -> None: ... - docinfo: Incomplete - body: Incomplete + docinfo: list[str] + body: list[str] def depart_docinfo(self, node: nodes.docinfo) -> None: ... - def visit_docinfo_item(self, node, name, meta: bool = True) -> None: ... + def visit_docinfo_item(self, node: nodes.Element, name: str, meta: bool = True) -> None: ... def depart_docinfo_item(self) -> None: ... - def visit_doctest_block(self, node) -> None: ... - def depart_doctest_block(self, node) -> None: ... - def visit_entry(self, node) -> None: ... - def depart_entry(self, node) -> None: ... - compact_p: Incomplete - compact_simple: Incomplete - def visit_enumerated_list(self, node) -> None: ... - def depart_enumerated_list(self, node) -> None: ... - def visit_field(self, node) -> None: ... - def depart_field(self, node) -> None: ... - def visit_field_body(self, node) -> None: ... - def depart_field_body(self, node) -> None: ... + def visit_doctest_block(self, node: nodes.doctest_block) -> None: ... + def depart_doctest_block(self, node: nodes.doctest_block) -> None: ... + def visit_entry(self, node: nodes.entry) -> None: ... + def depart_entry(self, node: nodes.entry) -> None: ... + compact_p: bool + compact_simple: bool + def visit_enumerated_list(self, node: nodes.enumerated_list) -> None: ... + def depart_enumerated_list(self, node: nodes.enumerated_list) -> None: ... + def visit_field(self, node: nodes.field) -> None: ... + def depart_field(self, node: nodes.field) -> None: ... + def visit_field_body(self, node: nodes.field_body) -> None: ... + def depart_field_body(self, node: nodes.field_body) -> None: ... compact_field_list: bool def visit_field_list(self, node: nodes.field_list) -> None: ... def depart_field_list(self, node: nodes.field_list) -> None: ... @@ -102,7 +101,7 @@ class HTMLTranslator(_html_base.HTMLTranslator): def depart_subscript(self, node: nodes.subscript) -> None: ... in_document_title: int def visit_subtitle(self, node: nodes.subtitle) -> None: ... - subtitle: list[Incomplete] + subtitle: list[str] def depart_subtitle(self, node: nodes.subtitle) -> None: ... def visit_superscript(self, node: nodes.superscript) -> None: ... def depart_superscript(self, node: nodes.superscript) -> None: ... diff --git a/stubs/docutils/docutils/writers/latex2e/__init__.pyi b/stubs/docutils/docutils/writers/latex2e/__init__.pyi index 359019018439..cf52324e36bb 100644 --- a/stubs/docutils/docutils/writers/latex2e/__init__.pyi +++ b/stubs/docutils/docutils/writers/latex2e/__init__.pyi @@ -1,15 +1,15 @@ import re -from _typeshed import Incomplete, StrPath -from collections.abc import Callable, Iterable +from _typeshed import StrPath +from collections.abc import Iterable from io import TextIOWrapper from pathlib import Path -from typing import ClassVar, Final, Literal, TypeVar, overload +from typing import Any, ClassVar, Final, Literal, TypeVar, overload from typing_extensions import Never, deprecated from docutils import nodes from docutils.frontend import Values -from docutils.languages import _LanguageModule -from docutils.utils import Reporter +from docutils.languages import LanguageModule +from docutils.utils import Reporter, _ReporterMessageMethod from docutils.writers import Writer as _Writer _K = TypeVar("_K") @@ -34,7 +34,7 @@ class Writer(_Writer[str]): class Babel: language_codes: ClassVar[dict[str, str]] - warn_msg: ClassVar[str] + warn_msg: str active_chars: ClassVar[dict[str, str]] reporter: Reporter | None @@ -117,17 +117,18 @@ class DocumentClass: class Table: legacy_column_widths: bool caption: list[str] - stubs: list[Incomplete] + stubs: list[bool | None] colwidths_auto: bool borders: str def __init__(self, translator: LaTeXTranslator, latex_type: str) -> None: ... def open(self) -> None: ... def close(self) -> None: ... def is_open(self) -> bool: ... - def set_table_style(self, node, settings) -> None: ... + def set_table_style(self, node: nodes.table, settings: Values) -> None: ... def get_latex_type(self) -> str: ... - def set(self, attr, value) -> None: ... - def get(self, attr): ... + # Only used for the "align" attribute. + def set(self, attr: str, value: str) -> None: ... + def get(self, attr: str) -> str | None: ... def get_vertical_bar(self) -> Literal["|", ""]: ... def get_opening(self, width: str = r"\linewidth") -> str: ... def get_closing(self) -> str: ... @@ -140,14 +141,14 @@ class Table: def depart_thead(self) -> list[str]: ... def visit_row(self) -> None: ... def depart_row(self) -> list[str]: ... - def set_rowspan(self, cell, value) -> None: ... - def get_rowspan(self, cell): ... + def set_rowspan(self, cell: int, value: int) -> None: ... + def get_rowspan(self, cell: int) -> int: ... def get_entry_number(self) -> int: ... def visit_entry(self) -> None: ... - def is_stub_column(self): ... + def is_stub_column(self) -> bool | None: ... class LaTeXTranslator(nodes.NodeVisitor): - is_xetex: ClassVar[bool] + is_xetex: bool compound_enumerators: ClassVar[bool] section_prefix_for_enumerators: ClassVar[bool] section_enumerator_separator: ClassVar[str] @@ -161,55 +162,56 @@ class LaTeXTranslator(nodes.NodeVisitor): alltt: ClassVar[bool] TITLEDATA_NODES: ClassVar[tuple[type[nodes.Element], ...]] - warn: Callable[..., nodes.system_message] - error: Callable[..., nodes.system_message] + warn: _ReporterMessageMethod + error: _ReporterMessageMethod settings: Values latex_encoding: str - use_latex_toc: Incomplete - use_latex_docinfo: Incomplete - use_latex_citations: Incomplete - reference_label: Incomplete - hyperlink_color: Incomplete + use_latex_toc: bool + use_latex_docinfo: bool + use_latex_citations: bool + reference_label: str | None + hyperlink_color: str font_encoding: str literal_block_env: str literal_block_options: str - bibtex: Incomplete - language_module: _LanguageModule + bibtex: list[str] | None + language_module: LanguageModule babel: Babel author_separator: str documentoptions: str d_class: DocumentClass graphicx_package: str - docutils_footnotes: Incomplete + docutils_footnotes: bool head_prefix: list[str] requirements: SortableDict[str, str] | list[str] - latex_preamble: list[Incomplete] + latex_preamble: list[str] fallbacks: SortableDict[str, str] | list[str] pdfsetup: list[str] - title: list[Incomplete] - subtitle: list[Incomplete] - titledata: list[Incomplete] - body_pre_docinfo: list[Incomplete] - docinfo: list[Incomplete] - dedication: list[Incomplete] - abstract: list[Incomplete] - body: list[Incomplete] - context: list[Incomplete] - title_labels: list[Incomplete] - subtitle_labels: list[Incomplete] - author_stack: list[Incomplete] - date: list[Incomplete] - pdfauthor: list[Incomplete] - pdfinfo: list[Incomplete] - table_stack: list[Incomplete] + title: list[str] + subtitle: list[str] + titledata: list[str] + body_pre_docinfo: list[str] + docinfo: list[str] + dedication: list[str] + abstract: list[str] + body: list[str] + # A stack of heterogeneous values (mostly closing LaTeX code) used by visit/depart pairs. + context: list[Any] + title_labels: list[str] + subtitle_labels: list[str] + author_stack: list[list[str]] + date: list[str] + pdfauthor: list[str] + pdfinfo: list[str] + table_stack: list[Table] active_table: Table - out: list[Incomplete] - out_stack: list[Incomplete] + out: list[str] + out_stack: list[list[str]] fallback_stylesheet: bool stylesheet: list[str] hyperref_options: str - def __init__(self, document: nodes.document, babel_class: type = ...) -> None: ... + def __init__(self, document: nodes.document, babel_class: type[Babel] = ...) -> None: ... def stylesheet_call(self, path: StrPath) -> str: ... def to_latex_encoding(self, docutils_encoding: str) -> str: ... def language_label(self, docutil_label: str) -> str: ... @@ -220,12 +222,12 @@ class LaTeXTranslator(nodes.NodeVisitor): self, node: nodes.Element, set_anchor: bool = True, protect: bool = False, newline: bool = False, pre_nl: bool = False ) -> list[str]: ... def append_hypertargets(self, node: nodes.Element) -> None: ... - def set_align_from_classes(self, node) -> None: ... + def set_align_from_classes(self, node: nodes.Element) -> None: ... def insert_align_declaration(self, node: nodes.Element, default: str | None = None) -> None: ... def provide_fallback(self, feature: str, key: str | None = None) -> None: ... - def duclass_open(self, node) -> None: ... - def duclass_close(self, node) -> None: ... - def push_output_collector(self, new_out) -> None: ... + def duclass_open(self, node: nodes.Element) -> None: ... + def duclass_close(self, node: nodes.Element) -> None: ... + def push_output_collector(self, new_out: list[str]) -> None: ... def pop_output_collector(self) -> None: ... def term_postfix(self, node: nodes.Element) -> str: ... def visit_Text(self, node: nodes.Text) -> None: ... @@ -288,12 +290,12 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_docinfo(self, node: nodes.docinfo) -> None: ... @overload - def visit_docinfo_item(self, node) -> None: ... + def visit_docinfo_item(self, node: nodes.Element) -> None: ... @overload @deprecated("The `name` parameter is deprecated and will be removed in Docutils 0.24.") - def visit_docinfo_item(self, node, name: str | None) -> None: ... + def visit_docinfo_item(self, node: nodes.Element, name: str | None) -> None: ... - def depart_docinfo_item(self, node) -> None: ... + def depart_docinfo_item(self, node: nodes.Element) -> None: ... def visit_doctest_block(self, node: nodes.doctest_block) -> None: ... def depart_doctest_block(self, node: nodes.doctest_block) -> None: ... def visit_document(self, node: nodes.document) -> None: ... @@ -325,7 +327,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_footnote(self, node: nodes.footnote) -> None: ... def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: ... def depart_footnote_reference(self, node: nodes.footnote_reference) -> None: ... - def label_delim(self, node, bracket, superscript) -> None: ... + def label_delim(self, node: nodes.Element, bracket: str, superscript: str) -> None: ... def visit_label(self, node: nodes.label) -> None: ... def depart_label(self, node: nodes.label) -> None: ... def visit_generated(self, node: nodes.generated) -> None: ... @@ -347,7 +349,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_list_item(self, node: nodes.list_item) -> None: ... def visit_literal(self, node: nodes.literal) -> None: ... def depart_literal(self, node: nodes.literal) -> None: ... - def is_plaintext(self, node) -> bool: ... + def is_plaintext(self, node: nodes.Element) -> bool: ... def visit_literal_block(self, node: nodes.literal_block) -> None: ... def depart_literal_block(self, node: nodes.literal_block) -> None: ... def visit_meta(self, node: nodes.meta) -> None: ... @@ -412,9 +414,10 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_tgroup(self, node: nodes.tgroup) -> None: ... def thead_depth(self) -> int: ... def visit_thead(self, node: nodes.thead) -> None: ... + def depart_thead(self, node: nodes.thead) -> None: ... def visit_title(self, node: nodes.title) -> None: ... def depart_title(self, node: nodes.title) -> None: ... - def visit_contents(self, node) -> None: ... + def visit_contents(self, node: nodes.Element) -> None: ... def visit_topic(self, node: nodes.topic) -> None: ... def depart_topic(self, node: nodes.topic) -> None: ... def visit_transition(self, node: nodes.transition) -> None: ... diff --git a/stubs/docutils/docutils/writers/manpage.pyi b/stubs/docutils/docutils/writers/manpage.pyi index 9b9606008bb3..185126b978a2 100644 --- a/stubs/docutils/docutils/writers/manpage.pyi +++ b/stubs/docutils/docutils/writers/manpage.pyi @@ -1,12 +1,11 @@ import re -from _typeshed import Incomplete from collections.abc import Callable -from typing import ClassVar, Final, Protocol, type_check_only +from typing import ClassVar, Final, Literal, Protocol, type_check_only from typing_extensions import Never from docutils import nodes, writers from docutils.frontend import Values -from docutils.languages import _LanguageModule +from docutils.languages import LanguageModule @type_check_only class _RegexPatternSub(Protocol): @@ -32,7 +31,7 @@ class Writer(writers.Writer[str]): class Table: def __init__(self) -> None: ... def new_row(self) -> None: ... - def append_separator(self, separator) -> None: ... + def append_separator(self, separator: str) -> None: ... def append_cell(self, cell_lines: list[str]) -> None: ... def as_list(self) -> list[str]: ... @@ -41,7 +40,7 @@ class Translator(nodes.NodeVisitor): possibly_a_roff_command: ClassVar[re.Pattern[str]] document_start: ClassVar[str] settings: Values - language: _LanguageModule + language: LanguageModule head: list[str] body: list[str] foot: list[str] @@ -50,9 +49,9 @@ class Translator(nodes.NodeVisitor): topic_class: str colspecs: list[nodes.colspec] compact_p: int - compact_simple: Incomplete + compact_simple: bool | None header_written: int - authors: list[Incomplete] + authors: list[str] defs: dict[str, tuple[str, ...]] def comment_begin(self, text: str) -> str: ... def comment(self, text: str) -> str: ... @@ -63,7 +62,7 @@ class Translator(nodes.NodeVisitor): def encode_special_chars(self, text: str) -> str: ... def visit_Text(self, node: nodes.Text) -> None: ... def depart_Text(self, node: nodes.Text) -> None: ... - def list_start(self, node) -> None: ... + def list_start(self, node: nodes.Element) -> None: ... def list_end(self) -> None: ... def header(self) -> str: ... def append_header(self) -> None: ... @@ -144,7 +143,7 @@ class Translator(nodes.NodeVisitor): def depart_footer(self, node: nodes.footer) -> None: ... def visit_footnote(self, node: nodes.footnote) -> None: ... def depart_footnote(self, node: nodes.footnote) -> None: ... - def footnote_backrefs(self, node) -> None: ... + def footnote_backrefs(self, node: nodes.Element) -> None: ... def visit_footnote_reference(self, node: nodes.footnote_reference) -> None: ... def depart_footnote_reference(self, node: nodes.footnote_reference) -> None: ... def visit_generated(self, node: nodes.generated) -> None: ... @@ -200,7 +199,7 @@ class Translator(nodes.NodeVisitor): def depart_option_argument(self, node: nodes.option_argument) -> None: ... def visit_organization(self, node: nodes.organization) -> None: ... def depart_organization(self, node: nodes.organization) -> None: ... - def first_child(self, node): ... + def first_child(self, node: nodes.Node) -> Literal[0, 1]: ... def visit_paragraph(self, node: nodes.paragraph) -> None: ... def depart_paragraph(self, node: nodes.paragraph) -> None: ... def visit_problematic(self, node: nodes.problematic) -> None: ... @@ -225,6 +224,7 @@ class Translator(nodes.NodeVisitor): def visit_table(self, node: nodes.table) -> None: ... def depart_table(self, node: nodes.table) -> None: ... def visit_target(self, node: nodes.target) -> None: ... + def depart_target(self, node: nodes.target) -> None: ... def visit_tbody(self, node: nodes.tbody) -> None: ... def depart_tbody(self, node: nodes.tbody) -> None: ... def visit_term(self, node: nodes.term) -> None: ... diff --git a/stubs/docutils/docutils/writers/odf_odt/__init__.pyi b/stubs/docutils/docutils/writers/odf_odt/__init__.pyi index d9a6795a9438..2bdd6e43972e 100644 --- a/stubs/docutils/docutils/writers/odf_odt/__init__.pyi +++ b/stubs/docutils/docutils/writers/odf_odt/__init__.pyi @@ -1,14 +1,14 @@ import itertools import re import zipfile -from _typeshed import FileDescriptorOrPath, Incomplete, ReadableBuffer, SizedBuffer, Unused +from _typeshed import FileDescriptorOrPath, ReadableBuffer, SizedBuffer, Unused from collections.abc import Generator from typing import ClassVar, Final, Literal from xml.etree import ElementTree from docutils import nodes, writers from docutils.frontend import Values -from docutils.languages import _LanguageModule +from docutils.languages import LanguageModule from docutils.readers import standalone __docformat__: Final = "reStructuredText" @@ -17,8 +17,8 @@ IMAGE_NAME_COUNTER: Final[itertools.count[int]] class _ElementInterfaceWrapper(ElementTree.Element): def __init__(self, tag: str, attrib: dict[str, str] | None = None) -> None: ... - def setparent(self, parent) -> None: ... - def getparent(self): ... + def setparent(self, parent: ElementTree.Element) -> None: ... + def getparent(self) -> ElementTree.Element: ... SPACES_PATTERN: Final[re.Pattern[str]] TABS_PATTERN: Final[re.Pattern[str]] @@ -57,12 +57,12 @@ class TableStyle: border: str | None backgroundcolor: str | None def __init__(self, border: str | None = None, backgroundcolor: str | None = None) -> None: ... - def get_border_(self): ... - def set_border_(self, border) -> None: ... - border_: Incomplete - def get_backgroundcolor_(self): ... - def set_backgroundcolor_(self, backgroundcolor) -> None: ... - backgroundcolor_: Incomplete + def get_border_(self) -> str | None: ... + def set_border_(self, border: str | None) -> None: ... + border_: str | None + def get_backgroundcolor_(self) -> str | None: ... + def set_backgroundcolor_(self, backgroundcolor: str | None) -> None: ... + backgroundcolor_: str | None BUILTIN_DEFAULT_TABLE_STYLE: TableStyle @@ -89,7 +89,9 @@ class Writer(writers.Writer[bytes]): settings: Values visitor: ODFTranslator def assemble_my_parts(self) -> None: ... - def update_stylesheet(self, stylesheet_root, language_code: str | None, region_code: str | None): ... + def update_stylesheet( + self, stylesheet_root: ElementTree.Element, language_code: str | None, region_code: str | None + ) -> tuple[bool, ElementTree.Element, set[ElementTree.Element]]: ... def write_zip_str( self, zfile: zipfile.ZipFile, name: str, bytes_: str | SizedBuffer, compress_type: int = zipfile.ZIP_DEFLATED ) -> None: ... @@ -105,7 +107,7 @@ class ODFTranslator(nodes.GenericNodeVisitor): used_styles: ClassVar[tuple[str, ...]] settings: Values language_code: str - language: _LanguageModule + language: LanguageModule format_map: dict[str, str] section_level: int section_count: int @@ -119,17 +121,17 @@ class ODFTranslator(nodes.GenericNodeVisitor): column_count: int trace_level: int optiontablestyles_generated: bool - field_name: Incomplete - field_element: Incomplete + field_name: None # unused + field_element: None # unused title: str | None image_count: int image_style_count: int image_dict: dict[str, tuple[str, str]] - embedded_file_list: list[Incomplete] + embedded_file_list: list[tuple[str, str]] syntaxhighlighting: int syntaxhighlight_lexer: str - header_content: list[Incomplete] - footer_content: list[Incomplete] + header_content: list[_ElementInterfaceWrapper] + footer_content: list[_ElementInterfaceWrapper] in_header: bool in_footer: bool blockstyle: str @@ -137,18 +139,18 @@ class ODFTranslator(nodes.GenericNodeVisitor): table_of_content_index_body: _ElementInterfaceWrapper | None list_level: int def_list_level: int - footnote_ref_dict: dict[Incomplete, _ElementInterfaceWrapper] - footnote_list: list[tuple[Incomplete, Incomplete]] + footnote_ref_dict: dict[str, _ElementInterfaceWrapper] + footnote_list: list[tuple[nodes.footnote, _ElementInterfaceWrapper]] footnote_chars_idx: int footnote_level: int - pending_ids: Incomplete + pending_ids: list[str] in_paragraph: bool found_doc_title: bool bumped_list_level_stack: list[ListLevel] - meta_dict: dict[Incomplete, Incomplete] + meta_dict: dict[str, str] line_block_level: int line_indent_level: int - citation_id: Incomplete + citation_id: str | None style_index: int str_stylesheet: str | bytes str_stylesheetcontent: str | bytes | None @@ -166,26 +168,28 @@ class ODFTranslator(nodes.GenericNodeVisitor): def attach_page_style(self, el: _ElementInterfaceWrapper) -> None: ... def rststyle(self, name: str, parameters: tuple[object, ...] = ()) -> str: ... def generate_content_element(self, root: _ElementInterfaceWrapper) -> _ElementInterfaceWrapper: ... - def setup_page(self): ... + def setup_page(self) -> bytes: ... def get_dom_stylesheet(self) -> ElementTree.Element | None: ... - def setup_paper(self, root_el) -> None: ... - def add_header_footer(self, root_el) -> None: ... + def setup_paper(self, root_el: ElementTree.Element) -> None: ... + def add_header_footer(self, root_el: ElementTree.Element) -> None: ... code_none: int code_field: int code_text: int field_pat: re.Pattern[str] - def create_custom_headfoot(self, parent: _ElementInterfaceWrapper, text: str, style_name, automatic_styles) -> None: ... + def create_custom_headfoot( + self, parent: _ElementInterfaceWrapper, text: str, style_name: str, automatic_styles: ElementTree.Element + ) -> None: ... def make_field_element( - self, parent: _ElementInterfaceWrapper, text: str, style_name, automatic_styles + self, parent: _ElementInterfaceWrapper, text: str, style_name: str, automatic_styles: ElementTree.Element ) -> _ElementInterfaceWrapper | None: ... def split_field_specifiers_iter(self, text: str) -> Generator[tuple[int, str]]: ... def astext(self) -> str: ... def content_astext(self) -> str: ... def set_title(self, title: str) -> None: ... def get_title(self) -> str | None: ... - def set_embedded_file_list(self, embedded_file_list) -> None: ... - def get_embedded_file_list(self): ... - def get_meta_dict(self): ... + def set_embedded_file_list(self, embedded_file_list: list[tuple[str, str]]) -> None: ... + def get_embedded_file_list(self) -> list[tuple[str, str]]: ... + def get_meta_dict(self) -> dict[str, str]: ... def process_footnotes(self) -> None: ... def append_child( self, tag: str, attrib: dict[str, str] | None = None, parent: _ElementInterfaceWrapper | None = None @@ -197,10 +201,10 @@ class ODFTranslator(nodes.GenericNodeVisitor): def generate_labeled_block(self, node: nodes.Node, label: str) -> _ElementInterfaceWrapper: ... def generate_labeled_line(self, node: nodes.Node, label: str) -> _ElementInterfaceWrapper: ... def encode(self, text: str) -> str: ... - def dispatch_visit(self, node: nodes.Element) -> None: ... # type: ignore[override] + def dispatch_visit(self, node: nodes.Node) -> None: ... def handle_basic_atts(self, node: nodes.Element) -> None: ... - def default_visit(self, node: nodes.Element) -> None: ... # type: ignore[override] - def default_departure(self, node: nodes.Element) -> None: ... # type: ignore[override] + def default_visit(self, node: nodes.Node) -> None: ... + def default_departure(self, node: nodes.Node) -> None: ... def visit_Text(self, node: nodes.Text) -> None: ... def depart_Text(self, node: nodes.Text) -> None: ... def visit_address(self, node: nodes.address) -> None: ... @@ -293,12 +297,20 @@ class ODFTranslator(nodes.GenericNodeVisitor): def get_image_width_height(self, node: nodes.image, attr: str) -> tuple[float | None, Literal["%", "cm"] | None]: ... def convert_to_cm(self, size: str) -> tuple[float, Literal["cm"]]: ... def get_image_scale(self, node: nodes.image) -> float: ... - def get_image_scaled_width_height(self, node: nodes.image, source) -> tuple[Incomplete, Incomplete]: ... + def get_image_scaled_width_height(self, node: nodes.image, source: str) -> tuple[str, str]: ... def get_page_width(self) -> float: ... - def generate_figure(self, node: nodes.image, source, destination, current_element): ... + # Returns (frame, text box, paragraph, caption text). + def generate_figure( + self, node: nodes.image, source: str, destination: str, current_element: _ElementInterfaceWrapper + ) -> tuple[_ElementInterfaceWrapper, _ElementInterfaceWrapper, _ElementInterfaceWrapper, str | None]: ... def generate_image( - self, node: nodes.image, source, destination, current_element, frame_attrs: dict[str, str] | None = None - ): ... + self, + node: nodes.image, + source: str, + destination: str, + current_element: _ElementInterfaceWrapper, + frame_attrs: dict[str, str] | None = None, + ) -> tuple[_ElementInterfaceWrapper, str]: ... def is_in_table(self, node: nodes.Node) -> bool: ... def visit_legend(self, node: nodes.legend) -> None: ... def depart_legend(self, node: nodes.legend) -> None: ... @@ -355,7 +367,7 @@ class ODFTranslator(nodes.GenericNodeVisitor): def depart_substitution_definition(self, node: nodes.substitution_definition) -> None: ... def visit_system_message(self, node: nodes.system_message) -> None: ... def depart_system_message(self, node: nodes.system_message) -> None: ... - def get_table_style(self, node) -> TableStyle: ... + def get_table_style(self, node: nodes.Element) -> TableStyle: ... current_table_style: _ElementInterfaceWrapper table_width: float def visit_table(self, node: nodes.table) -> None: ... @@ -381,14 +393,16 @@ class ODFTranslator(nodes.GenericNodeVisitor): def depart_subtitle(self, node: nodes.subtitle) -> None: ... def visit_title_reference(self, node: nodes.title_reference) -> None: ... def depart_title_reference(self, node: nodes.title_reference) -> None: ... - def generate_table_of_content_entry_template(self, el1) -> None: ... - def find_title_label(self, node, class_type, label_key): ... - save_current_element: Incomplete + def generate_table_of_content_entry_template(self, el1: _ElementInterfaceWrapper) -> None: ... + def find_title_label(self, node: nodes.Element, class_type: type[nodes.Node], label_key: str) -> str: ... + save_current_element: _ElementInterfaceWrapper def visit_topic(self, node: nodes.topic) -> None: ... def depart_topic(self, node: nodes.topic) -> None: ... - def update_toc_page_numbers(self, el) -> None: ... - def update_toc_collect(self, el, level, collection) -> None: ... - def update_toc_add_numbers(self, collection) -> None: ... + def update_toc_page_numbers(self, el: ElementTree.Element) -> None: ... + def update_toc_collect( + self, el: ElementTree.Element, level: int, collection: list[tuple[int, ElementTree.Element]] + ) -> None: ... + def update_toc_add_numbers(self, collection: list[tuple[int, ElementTree.Element]]) -> None: ... def visit_transition(self, node: nodes.transition) -> None: ... def depart_transition(self, node: nodes.transition) -> None: ... def visit_warning(self, node: nodes.warning) -> None: ... diff --git a/stubs/docutils/docutils/writers/odf_odt/pygmentsformatter.pyi b/stubs/docutils/docutils/writers/odf_odt/pygmentsformatter.pyi index 10293d3fb075..4b1587a789c2 100644 --- a/stubs/docutils/docutils/writers/odf_odt/pygmentsformatter.pyi +++ b/stubs/docutils/docutils/writers/odf_odt/pygmentsformatter.pyi @@ -1,31 +1,36 @@ -from _typeshed import Incomplete -from typing import Any +from _typeshed import SupportsWrite +from collections.abc import Callable, Iterable +from typing import Any, Protocol, type_check_only -# Formatter[str] from types-pygments +# A minimal stand-in for `pygments.formatter.Formatter[str]` (pygments is an optional dependency). +@type_check_only class _Formatter: - name: Any - aliases: Any - filenames: Any + name: str | None + aliases: list[str] + filenames: list[str] unicodeoutput: bool - style: Any - full: Any - title: Any - encoding: Any - options: Any - def __init__(self, *, encoding: None = None, outencoding: None = None, **options) -> None: ... - def get_style_defs(self, arg: str = ""): ... - def format(self, tokensource, outfile): ... + style: type[object] + full: bool + title: str + encoding: str | None + options: dict[str, Any] # arbitrary formatter options + def __init__(self, *, encoding: None = None, outencoding: None = None, **options: object) -> None: ... + def get_style_defs(self, arg: str = "") -> str: ... + def format(self, tokensource: Iterable[tuple[object, str]], outfile: SupportsWrite[str]) -> None: ... + +# `ODFTranslator.rststyle()` +@type_check_only +class _RstStyleFunction(Protocol): + def __call__(self, name: str, parameters: tuple[object, ...] = ..., /) -> str: ... class OdtPygmentsFormatter(_Formatter): - rststyle_function: Incomplete - escape_function: Incomplete - def __init__(self, rststyle_function, escape_function) -> None: ... - def rststyle(self, name, parameters=()): ... - def get_style_defs(self, arg: str = ""): ... - def format(self, tokensource, outfile): ... + rststyle_function: _RstStyleFunction + escape_function: Callable[[str], str] + def __init__(self, rststyle_function: _RstStyleFunction, escape_function: Callable[[str], str]) -> None: ... + def rststyle(self, name: str, parameters: tuple[object, ...] = ()) -> str: ... class OdtPygmentsProgFormatter(OdtPygmentsFormatter): - def format(self, tokensource, outfile) -> None: ... + def format(self, tokensource: Iterable[tuple[object, str]], outfile: SupportsWrite[str]) -> None: ... class OdtPygmentsLaTeXFormatter(OdtPygmentsFormatter): - def format(self, tokensource, outfile) -> None: ... + def format(self, tokensource: Iterable[tuple[object, str]], outfile: SupportsWrite[str]) -> None: ... diff --git a/stubs/docutils/docutils/writers/pep_html/__init__.pyi b/stubs/docutils/docutils/writers/pep_html/__init__.pyi index bdefd546ad4e..0bd9b08c521c 100644 --- a/stubs/docutils/docutils/writers/pep_html/__init__.pyi +++ b/stubs/docutils/docutils/writers/pep_html/__init__.pyi @@ -1,5 +1,6 @@ from typing import ClassVar, Final +from docutils import nodes from docutils.writers import html4css1 __docformat__: Final = "reStructuredText" @@ -17,4 +18,4 @@ class Writer(html4css1.Writer): def interpolation_dict(self) -> dict[str, str | int]: ... # type: ignore[override] class HTMLTranslator(html4css1.HTMLTranslator): - def depart_field_list(self, node) -> None: ... + def depart_field_list(self, node: nodes.field_list) -> None: ... diff --git a/stubs/docutils/docutils/writers/s5_html/__init__.pyi b/stubs/docutils/docutils/writers/s5_html/__init__.pyi index fe0f36f15b47..ff6ee70a5c66 100644 --- a/stubs/docutils/docutils/writers/s5_html/__init__.pyi +++ b/stubs/docutils/docutils/writers/s5_html/__init__.pyi @@ -1,6 +1,6 @@ import re from _typeshed import StrPath -from typing import ClassVar, Final +from typing import ClassVar, Final, Literal from docutils import nodes from docutils.writers import html4css1 @@ -33,7 +33,7 @@ class S5HTMLTranslator(html4css1.HTMLTranslator): def setup_theme(self) -> None: ... def copy_theme(self) -> None: ... files_to_skip_pattern: re.Pattern[str] - def copy_file(self, name, source_dir, dest_dir): ... + def copy_file(self, name: str, source_dir: StrPath, dest_dir: StrPath) -> Literal[True] | None: ... def depart_document(self, node: nodes.document) -> None: ... def depart_footer(self, node: nodes.footer) -> None: ... def depart_header(self, node: nodes.header) -> None: ... diff --git a/stubs/docutils/docutils/writers/xetex/__init__.pyi b/stubs/docutils/docutils/writers/xetex/__init__.pyi index a8528b3670b2..dc7f434407a9 100644 --- a/stubs/docutils/docutils/writers/xetex/__init__.pyi +++ b/stubs/docutils/docutils/writers/xetex/__init__.pyi @@ -17,7 +17,7 @@ class Babel(latex2e.Babel): language_code: str reporter: Reporter language: str - warn_msg: str # type: ignore[misc] + warn_msg: str quote_index: int quotes: tuple[str, ...] literal_double_quote: str @@ -25,6 +25,6 @@ class Babel(latex2e.Babel): def __init__(self, language_code: str, reporter: Reporter) -> None: ... class XeLaTeXTranslator(latex2e.LaTeXTranslator): - is_xetex: bool # type: ignore[misc] + is_xetex: bool def __init__(self, document: nodes.document) -> None: ... def to_latex_length(self, length_str: str, node: nodes.Node | None = None) -> str: ...