From 860eb1712d4e0f62c48616afee35efad5ba51c8b Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 7 Jan 2024 14:30:50 +0100 Subject: [PATCH 01/15] Add remaining docutils node classes --- stubs/docutils/docutils/nodes.pyi | 255 +++++++++++++++++++++++++++--- 1 file changed, 234 insertions(+), 21 deletions(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 5239fef9517f..a8c0c7574cfc 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -2,17 +2,20 @@ import sys import xml.dom.minidom from _typeshed import Incomplete from abc import abstractmethod -from collections.abc import Callable, Generator, Iterable, Iterator, Sequence +from collections.abc import Callable, Generator, Iterable, Iterator, Sequence, Mapping from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload from typing_extensions import Self -from docutils.transforms import Transformer +from docutils.transforms import Transform, Transformer +from docutils.utils import Reporter _N = TypeVar("_N", bound=Node) class _DomModule(Protocol): Document: type[xml.dom.minidom.Document] +# Functional Node Base Classes + class Node: # children is initialized by the subclasses children: Sequence[Node] @@ -77,6 +80,25 @@ class Node: ascend: bool = False, ) -> Node: ... +# Left out +# - def ensure_str (deprecated) +# - def unescape (canonical import from docutils.utils) + +class Text(Node, str): + tagname: ClassVar[str] + children: tuple[()] + + # we omit the rawsource parameter because it has been deprecated and is ignored + def __new__(cls, data: str) -> Self: ... + def __init__(self, data: str) -> None: ... + 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: ... + class Element(Node): children: list[Node] rawsource: str @@ -113,40 +135,231 @@ class Element(Node): def __getattr__(self, __name: str) -> Incomplete: ... class TextElement(Element): + # A few classes not subclassing TextElement have this, too + child_text_separator: ClassVar[str] def __init__(self, rawsource: str = "", text: str = "", *children: Node, **attributes) -> None: ... -class Text(Node, str): - tagname: ClassVar[str] - children: tuple[()] +class FixedTextElement(TextElement): ... - # we omit the rawsource parameter because it has been deprecated and is ignored - def __new__(cls, data: str) -> Self: ... - def __init__(self, data: str) -> None: ... - 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: ... +# Mixins + +class Resolvable: + resolved: int + +class BackLinkable: + def add_backref(self, refid: str) -> None: ... + +# Element Categories +class Root: ... +class Titular: ... +class PreBibliographic: ... +class Bibliographic: ... +class Decorative(PreBibliographic): ... class Structural: ... class Body: ... class General(Body): ... -class Root: ... +class Sequential(Body): ... +class Admonition(Body): ... +class Special(Body): ... +class Invisible(PreBibliographic): ... +class Part: ... +class Inline: ... +class Referential(Resolvable): ... + +class Targetable(Resolvable): + referenced: int + indirect_reference_name: str | None + +class Labeled: ... + +# Root Element class document(Root, Structural, Element): transformer: Transformer - def copy(self) -> Self: ... - def deepcopy(self) -> Self: ... - def pformat(self, indent: str = " ", level: int = 0) -> str: ... - def astext(self) -> str: ... + def __init__(self, settings: Incomplete, reporter: Reporter, rawsource: str = "", *children: Node, **attributes) -> None: ... def __getattr__(self, __name: str) -> Incomplete: ... +# Title Elements + +class title(Titular, PreBibliographic, TextElement): ... +class subtitle(Titular, PreBibliographic, TextElement): ... +class rubric(Titular, TextElement): ... + +# Meta-Data Element + +class meta(PreBibliographic, Element): ... + +# Bibliographic Elements + +class docinfo(Bibliographic, Element): ... +class author(Bibliographic, TextElement): ... +class authors(Bibliographic, Element): ... +class organization(Bibliographic, TextElement): ... +class address(Bibliographic, FixedTextElement): ... +class contact(Bibliographic, TextElement): ... +class version(Bibliographic, TextElement): ... +class revision(Bibliographic, TextElement): ... +class status(Bibliographic, TextElement): ... +class date(Bibliographic, TextElement): ... +class copyright(Bibliographic, TextElement): ... + +# Decorative Elements + +class decoration(Decorative, Element): + def get_header(self) -> header: ... + def get_footer(self) -> footer: ... + +class header(Decorative, Element): ... +class footer(Decorative, Element): ... + +# Structural Elements + +class section(Structural, Element): ... +class topic(Structural, Element): ... +class sidebar(Structural, Element): ... +class transition(Structural, Element): ... + +# Body Elements +# =============== + class paragraph(General, TextElement): ... +class compound(General, Element): ... +class container(General, Element): ... +class bullet_list(Sequential, Element): ... +class enumerated_list(Sequential, Element): ... +class list_item(Part, Element): ... +class definition_list(Sequential, Element): ... +class definition_list_item(Part, Element): ... +class term(Part, TextElement): ... +class classifier(Part, TextElement): ... +class definition(Part, Element): ... +class field_list(Sequential, Element): ... +class field(Part, Element): ... +class field_name(Part, TextElement): ... +class field_body(Part, Element): ... + +# child_text_separator in some option* classes mirrors TextElement, +# but these classes do not subclass TextElement +class option(Part, Element): + child_text_separator: str + +class option_argument(Part, TextElement): ... + +class option_group(Part, Element): + child_text_separator: str # see above + +class option_list(Sequential, Element): ... + +class option_list_item(Part, Element): + child_text_separator: str # see above + +class option_string(Part, TextElement): ... +class description(Part, Element): ... +class literal_block(General, FixedTextElement): ... +class doctest_block(General, FixedTextElement): ... +class math_block(General, FixedTextElement): ... +class line_block(General, Element): ... + +class line(Part, TextElement): + indent: str | None + +class block_quote(General, Element): ... +class attribution(Part, TextElement): ... +class attention(Admonition, Element): ... +class caution(Admonition, Element): ... +class danger(Admonition, Element): ... +class error(Admonition, Element): ... +class important(Admonition, Element): ... +class note(Admonition, Element): ... +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 footnote(General, BackLinkable, Element, Labeled, Targetable): ... +class citation(General, BackLinkable, Element, Labeled, Targetable): ... +class label(Part, TextElement): ... +class figure(General, Element): ... +class caption(Part, TextElement): ... +class legend(Part, Element): ... +class table(General, Element): ... +class tgroup(Part, Element): ... +class colspec(Part, Element): ... +class thead(Part, Element): ... +class tbody(Part, Element): ... +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: ... + +class pending(Special, Invisible, Element): + transform: Transform + details: Mapping[str, Any] + def __init__( + self, transform: Transform, details: Mapping[str, Any] | None = None, rawsource: str = "", *children: Node, **attributes + ) -> None: ... + +class raw(Special, Inline, PreBibliographic, FixedTextElement): ... + +# Inline Elements + +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 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 image(General, Inline, Element): ... +class inline(Inline, TextElement): ... +class problematic(Inline, TextElement): ... +class generated(Inline, TextElement): ... + +# Auxiliary Classes, Functions, and Data + +node_class_names: list[str] class NodeVisitor: + optional: ClassVar[tuple[str, ...]] + document: document def __init__(self, document: document): ... + 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: ... + +class SparseNodeVisitor(NodeVisitor): ... + +class GenericNodeVisitor(NodeVisitor): + # all the visit_ methods def __getattr__(self, __name: str) -> Incomplete: ... -def __getattr__(name: str) -> Incomplete: ... +class TreeCopyVisitor(GenericNodeVisitor): + parent_stack: list[Node] + parent: list[Node] + def get_tree_copy(self) -> None: ... + +class TreePruningException(Exception): ... +class SkipChildren(TreePruningException): ... +class SkipSiblings(TreePruningException): ... +class SkipNode(TreePruningException): ... +class SkipDeparture(TreePruningException): ... +class NodeFound(TreePruningException): ... +class StopTraversal(TreePruningException): ... + +def make_id(string: str) -> str: ... +def dupname(node: Node, name: str) -> None: ... +def fully_normalize_name(name: str) -> str: ... +def whitespace_normalize_name(name: str) -> str: ... +def serial_escape(value: str) -> str: ... +def pseudo_quoteattr(value: str) -> str: ... From b8330c83aa949a628efb4665036de2aeba2201dc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 7 Jan 2024 13:31:40 +0000 Subject: [PATCH 02/15] [pre-commit.ci] auto fixes from pre-commit.com hooks --- stubs/docutils/docutils/nodes.pyi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index a8c0c7574cfc..61d0b65e2535 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -2,7 +2,7 @@ import sys import xml.dom.minidom from _typeshed import Incomplete from abc import abstractmethod -from collections.abc import Callable, Generator, Iterable, Iterator, Sequence, Mapping +from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload from typing_extensions import Self From 81a85ed52b2742f199faa4830837953e1804b29f Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 7 Jan 2024 14:42:53 +0100 Subject: [PATCH 03/15] Fixes --- stubs/docutils/docutils/__init__.pyi | 23 +++++++++++-------- .../docutils/docutils/languages/__init__.pyi | 16 +++++++++---- stubs/docutils/docutils/nodes.pyi | 7 ++++-- stubs/docutils/docutils/parsers/__init__.pyi | 4 ++-- 4 files changed, 33 insertions(+), 17 deletions(-) diff --git a/stubs/docutils/docutils/__init__.pyi b/stubs/docutils/docutils/__init__.pyi index 006592eb511c..83658dd961b5 100644 --- a/stubs/docutils/docutils/__init__.pyi +++ b/stubs/docutils/docutils/__init__.pyi @@ -1,8 +1,13 @@ -from typing import Any, ClassVar, NamedTuple +from collections.abc import Callable, Iterable, Mapping, Sequence +from typing import Any, ClassVar, Literal, NamedTuple from typing_extensions import Self +from docutils.nodes import Node +from docutils.transforms import Transform + __docformat__: str __version__: str +__version_details__: str class _VersionInfo(NamedTuple): major: int @@ -18,25 +23,25 @@ class VersionInfo(_VersionInfo): ) -> Self: ... __version_info__: VersionInfo -__version_details__: str class ApplicationError(Exception): ... class DataError(ApplicationError): ... class SettingsSpec: settings_spec: ClassVar[tuple[Any, ...]] - settings_defaults: ClassVar[dict[Any, Any] | None] - settings_default_overrides: ClassVar[dict[Any, Any] | None] - relative_path_settings: ClassVar[tuple[Any, ...]] + settings_defaults: ClassVar[Mapping[str, Any] | None] + settings_default_overrides: ClassVar[Mapping[str, Any] | None] + relative_path_settings: ClassVar[tuple[str, ...]] config_section: ClassVar[str | None] config_section_dependencies: ClassVar[tuple[str, ...] | None] class TransformSpec: - def get_transforms(self) -> list[Any]: ... - default_transforms: ClassVar[tuple[Any, ...]] - unknown_reference_resolvers: ClassVar[list[Any]] + def get_transforms(self) -> Iterable[Transform]: ... + # @deprecated("Use get_transforms() instead.") + default_transforms: ClassVar[tuple[Transform, ...]] + unknown_reference_resolvers: ClassVar[Sequence[Callable[[Node], bool]]] class Component(SettingsSpec, TransformSpec): - component_type: ClassVar[str | None] + component_type: ClassVar[Literal['reader', 'parser', 'writer'] | None] supported: ClassVar[tuple[str, ...]] def supports(self, format: str) -> bool: ... diff --git a/stubs/docutils/docutils/languages/__init__.pyi b/stubs/docutils/docutils/languages/__init__.pyi index 35522c07a700..dbbdc978891f 100644 --- a/stubs/docutils/docutils/languages/__init__.pyi +++ b/stubs/docutils/docutils/languages/__init__.pyi @@ -1,7 +1,8 @@ -from _typeshed import Incomplete -from typing import Protocol +from typing import ClassVar, Protocol -from docutils.utils import Reporter +from docutils.utils import Reporter, normalize_language_tag + +__all__ = ["get_language", "normalize_language_tag", "LanguageImporter"] class _LanguageModule(Protocol): labels: dict[str, str] @@ -9,7 +10,14 @@ class _LanguageModule(Protocol): bibliographic_fields: list[str] class LanguageImporter: + packages: ClassVar[tuple[str, ...]] + warn_msg: ClassVar[str] + fallback: ClassVar[str] + + cache: dict[str, _LanguageModule] + def __call__(self, language_code: str, reporter: Reporter | None = None) -> _LanguageModule: ... - def __getattr__(self, __name: str) -> Incomplete: ... + def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _LanguageModule: ... + def check_content(self, module: _LanguageModule) -> None: ... get_language: LanguageImporter diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 61d0b65e2535..5ffaa119279c 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -329,10 +329,13 @@ class generated(Inline, TextElement): ... node_class_names: list[str] +# necessary to disambiguate type and field in NodeVisitor +_Document = document + class NodeVisitor: optional: ClassVar[tuple[str, ...]] - document: document - def __init__(self, document: document): ... + document: _Document + def __init__(self, document: _Document): ... def dispatch_visit(self, node: Node) -> Any: ... def dispatch_departure(self, node: Node) -> Any: ... def unknown_visit(self, node: Node) -> Any: ... diff --git a/stubs/docutils/docutils/parsers/__init__.pyi b/stubs/docutils/docutils/parsers/__init__.pyi index 04683301d1e2..bebdc730c97c 100644 --- a/stubs/docutils/docutils/parsers/__init__.pyi +++ b/stubs/docutils/docutils/parsers/__init__.pyi @@ -1,10 +1,10 @@ -from typing import Any, ClassVar +from typing import Any, ClassVar, Literal from docutils import Component from docutils.nodes import document as _document class Parser(Component): - component_type: ClassVar[str] + component_type: ClassVar[Literal['parser']] config_section: ClassVar[str] inputstring: Any # defined after call to setup_parse() document: Any # defined after call to setup_parse() From 8125a21a94e4b204d66182482cd4e5e82d7df6ec Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 7 Jan 2024 13:43:34 +0000 Subject: [PATCH 04/15] [pre-commit.ci] auto fixes from pre-commit.com hooks --- stubs/docutils/docutils/__init__.pyi | 2 +- stubs/docutils/docutils/parsers/__init__.pyi | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/stubs/docutils/docutils/__init__.pyi b/stubs/docutils/docutils/__init__.pyi index 83658dd961b5..aa3a3003d903 100644 --- a/stubs/docutils/docutils/__init__.pyi +++ b/stubs/docutils/docutils/__init__.pyi @@ -42,6 +42,6 @@ class TransformSpec: unknown_reference_resolvers: ClassVar[Sequence[Callable[[Node], bool]]] class Component(SettingsSpec, TransformSpec): - component_type: ClassVar[Literal['reader', 'parser', 'writer'] | None] + component_type: ClassVar[Literal["reader", "parser", "writer"] | None] supported: ClassVar[tuple[str, ...]] def supports(self, format: str) -> bool: ... diff --git a/stubs/docutils/docutils/parsers/__init__.pyi b/stubs/docutils/docutils/parsers/__init__.pyi index bebdc730c97c..0388298865a1 100644 --- a/stubs/docutils/docutils/parsers/__init__.pyi +++ b/stubs/docutils/docutils/parsers/__init__.pyi @@ -4,7 +4,7 @@ from docutils import Component from docutils.nodes import document as _document class Parser(Component): - component_type: ClassVar[Literal['parser']] + component_type: ClassVar[Literal["parser"]] config_section: ClassVar[str] inputstring: Any # defined after call to setup_parse() document: Any # defined after call to setup_parse() From 6dcb4999909508674303957057ae64764e2c5511 Mon Sep 17 00:00:00 2001 From: Philipp A Date: Sun, 7 Jan 2024 14:44:03 +0100 Subject: [PATCH 05/15] Discard changes to stubs/docutils/docutils/languages/__init__.pyi --- stubs/docutils/docutils/languages/__init__.pyi | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/stubs/docutils/docutils/languages/__init__.pyi b/stubs/docutils/docutils/languages/__init__.pyi index dbbdc978891f..35522c07a700 100644 --- a/stubs/docutils/docutils/languages/__init__.pyi +++ b/stubs/docutils/docutils/languages/__init__.pyi @@ -1,8 +1,7 @@ -from typing import ClassVar, Protocol +from _typeshed import Incomplete +from typing import Protocol -from docutils.utils import Reporter, normalize_language_tag - -__all__ = ["get_language", "normalize_language_tag", "LanguageImporter"] +from docutils.utils import Reporter class _LanguageModule(Protocol): labels: dict[str, str] @@ -10,14 +9,7 @@ class _LanguageModule(Protocol): bibliographic_fields: list[str] class LanguageImporter: - packages: ClassVar[tuple[str, ...]] - warn_msg: ClassVar[str] - fallback: ClassVar[str] - - cache: dict[str, _LanguageModule] - def __call__(self, language_code: str, reporter: Reporter | None = None) -> _LanguageModule: ... - def import_from_packages(self, name: str, reporter: Reporter | None = None) -> _LanguageModule: ... - def check_content(self, module: _LanguageModule) -> None: ... + def __getattr__(self, __name: str) -> Incomplete: ... get_language: LanguageImporter From c8b48561e03ad9bcf44bd32d6f430ee7fb0ee470 Mon Sep 17 00:00:00 2001 From: Philipp A Date: Sun, 7 Jan 2024 14:45:09 +0100 Subject: [PATCH 06/15] Discard changes to stubs/docutils/docutils/__init__.pyi --- stubs/docutils/docutils/__init__.pyi | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/stubs/docutils/docutils/__init__.pyi b/stubs/docutils/docutils/__init__.pyi index aa3a3003d903..006592eb511c 100644 --- a/stubs/docutils/docutils/__init__.pyi +++ b/stubs/docutils/docutils/__init__.pyi @@ -1,13 +1,8 @@ -from collections.abc import Callable, Iterable, Mapping, Sequence -from typing import Any, ClassVar, Literal, NamedTuple +from typing import Any, ClassVar, NamedTuple from typing_extensions import Self -from docutils.nodes import Node -from docutils.transforms import Transform - __docformat__: str __version__: str -__version_details__: str class _VersionInfo(NamedTuple): major: int @@ -23,25 +18,25 @@ class VersionInfo(_VersionInfo): ) -> Self: ... __version_info__: VersionInfo +__version_details__: str class ApplicationError(Exception): ... class DataError(ApplicationError): ... class SettingsSpec: settings_spec: ClassVar[tuple[Any, ...]] - settings_defaults: ClassVar[Mapping[str, Any] | None] - settings_default_overrides: ClassVar[Mapping[str, Any] | None] - relative_path_settings: ClassVar[tuple[str, ...]] + settings_defaults: ClassVar[dict[Any, Any] | None] + settings_default_overrides: ClassVar[dict[Any, Any] | None] + relative_path_settings: ClassVar[tuple[Any, ...]] config_section: ClassVar[str | None] config_section_dependencies: ClassVar[tuple[str, ...] | None] class TransformSpec: - def get_transforms(self) -> Iterable[Transform]: ... - # @deprecated("Use get_transforms() instead.") - default_transforms: ClassVar[tuple[Transform, ...]] - unknown_reference_resolvers: ClassVar[Sequence[Callable[[Node], bool]]] + def get_transforms(self) -> list[Any]: ... + default_transforms: ClassVar[tuple[Any, ...]] + unknown_reference_resolvers: ClassVar[list[Any]] class Component(SettingsSpec, TransformSpec): - component_type: ClassVar[Literal["reader", "parser", "writer"] | None] + component_type: ClassVar[str | None] supported: ClassVar[tuple[str, ...]] def supports(self, format: str) -> bool: ... From c1315776e3c627da5f24bd7beb2c6523d9fab869 Mon Sep 17 00:00:00 2001 From: Philipp A Date: Sun, 7 Jan 2024 14:45:15 +0100 Subject: [PATCH 07/15] Discard changes to stubs/docutils/docutils/parsers/__init__.pyi --- stubs/docutils/docutils/parsers/__init__.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stubs/docutils/docutils/parsers/__init__.pyi b/stubs/docutils/docutils/parsers/__init__.pyi index 0388298865a1..04683301d1e2 100644 --- a/stubs/docutils/docutils/parsers/__init__.pyi +++ b/stubs/docutils/docutils/parsers/__init__.pyi @@ -1,10 +1,10 @@ -from typing import Any, ClassVar, Literal +from typing import Any, ClassVar from docutils import Component from docutils.nodes import document as _document class Parser(Component): - component_type: ClassVar[Literal["parser"]] + component_type: ClassVar[str] config_section: ClassVar[str] inputstring: Any # defined after call to setup_parse() document: Any # defined after call to setup_parse() From 81974a73777dfd9975600bed2537c28df2bb735e Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 7 Jan 2024 14:53:20 +0100 Subject: [PATCH 08/15] stubtest --- stubs/docutils/@tests/stubtest_allowlist.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/stubs/docutils/@tests/stubtest_allowlist.txt b/stubs/docutils/@tests/stubtest_allowlist.txt index 82dcbd5eb6e0..2a35ab92d9cf 100644 --- a/stubs/docutils/@tests/stubtest_allowlist.txt +++ b/stubs/docutils/@tests/stubtest_allowlist.txt @@ -7,9 +7,8 @@ docutils.io.FileOutput.__init__ docutils.io.Input.__init__ docutils.languages.LanguageImporter.__getattr__ docutils.nodes.Element.__getattr__ -docutils.nodes.NodeVisitor.__getattr__ +docutils.nodes.GenericNodeVisitor.__getattr__ docutils.nodes.document.__getattr__ -docutils.nodes.document.__init__ docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__ docutils.parsers.rst.Directive.__getattr__ docutils.transforms.Transform.__getattr__ From 5743214eb3b8ead58c8c222a4c75cf5eea64c3c9 Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 7 Jan 2024 15:06:29 +0100 Subject: [PATCH 09/15] remove duplicated Node methods --- stubs/docutils/docutils/nodes.pyi | 8 -------- 1 file changed, 8 deletions(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 5ffaa119279c..8baf94bf3408 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -92,10 +92,6 @@ class Text(Node, str): def __new__(cls, data: str) -> Self: ... def __init__(self, data: str) -> None: ... 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: ... @@ -124,10 +120,6 @@ class Element(Node): def __add__(self, other: list[Node]) -> list[Node]: ... def __radd__(self, other: list[Node]) -> list[Node]: ... def __iadd__(self, other: Node | Iterable[Node]) -> Self: ... - def copy(self) -> Self: ... - def deepcopy(self) -> Self: ... - def pformat(self, indent: str = " ", level: int = 0) -> str: ... - def astext(self) -> str: ... def index(self, item: Node, start: int = 0, stop: int = sys.maxsize) -> int: ... def remove(self, item: Node) -> None: ... def insert(self, index: SupportsIndex, item: Node | Iterable[Node] | None) -> None: ... From 0ed3dce0e92bd4a2c347422934255d11dfe706fa Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sun, 7 Jan 2024 15:09:35 +0100 Subject: [PATCH 10/15] Revert "remove duplicated Node methods" This reverts commit 5743214eb3b8ead58c8c222a4c75cf5eea64c3c9. --- stubs/docutils/docutils/nodes.pyi | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 8baf94bf3408..5ffaa119279c 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -92,6 +92,10 @@ class Text(Node, str): def __new__(cls, data: str) -> Self: ... def __init__(self, data: str) -> None: ... 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: ... @@ -120,6 +124,10 @@ class Element(Node): def __add__(self, other: list[Node]) -> list[Node]: ... def __radd__(self, other: list[Node]) -> list[Node]: ... def __iadd__(self, other: Node | Iterable[Node]) -> Self: ... + def copy(self) -> Self: ... + def deepcopy(self) -> Self: ... + def pformat(self, indent: str = " ", level: int = 0) -> str: ... + def astext(self) -> str: ... def index(self, item: Node, start: int = 0, stop: int = sys.maxsize) -> int: ... def remove(self, item: Node) -> None: ... def insert(self, index: SupportsIndex, item: Node | Iterable[Node] | None) -> None: ... From f9b87f80c78b05090699eee5e0a910d4edf8f475 Mon Sep 17 00:00:00 2001 From: Philipp A Date: Sun, 14 Jan 2024 14:34:43 +0100 Subject: [PATCH 11/15] Apply suggestions from code review Co-authored-by: Sebastian Rittau --- stubs/docutils/docutils/nodes.pyi | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 5ffaa119279c..58e5382e387c 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -3,7 +3,7 @@ import xml.dom.minidom from _typeshed import Incomplete from abc import abstractmethod from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence -from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload +from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeAlias, TypeVar, overload from typing_extensions import Self from docutils.transforms import Transform, Transformer @@ -177,7 +177,7 @@ class Labeled: ... class document(Root, Structural, Element): transformer: Transformer - def __init__(self, settings: Incomplete, reporter: Reporter, rawsource: str = "", *children: Node, **attributes) -> None: ... + def __init__(self, settings, reporter: Reporter, rawsource: str = "", *children: Node, **attributes) -> None: ... def __getattr__(self, __name: str) -> Incomplete: ... # Title Elements @@ -330,12 +330,12 @@ class generated(Inline, TextElement): ... node_class_names: list[str] # necessary to disambiguate type and field in NodeVisitor -_Document = document +_Document: TypeAlias = document class NodeVisitor: optional: ClassVar[tuple[str, ...]] document: _Document - def __init__(self, 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: ... @@ -350,7 +350,7 @@ class GenericNodeVisitor(NodeVisitor): class TreeCopyVisitor(GenericNodeVisitor): parent_stack: list[Node] parent: list[Node] - def get_tree_copy(self) -> None: ... + def get_tree_copy(self) -> Node: ... class TreePruningException(Exception): ... class SkipChildren(TreePruningException): ... From 965ad80c4b320210b91bb733025bef22927ec4ce Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Sun, 14 Jan 2024 15:20:12 +0100 Subject: [PATCH 12/15] Update stubs/docutils/docutils/nodes.pyi --- stubs/docutils/docutils/nodes.pyi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 58e5382e387c..242a3c102d8f 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -3,7 +3,8 @@ import xml.dom.minidom from _typeshed import Incomplete from abc import abstractmethod from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence -from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeAlias, TypeVar, overload +from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload +from typing_extensions import TypeAlias from typing_extensions import Self from docutils.transforms import Transform, Transformer From 134c2d5e6b24fd9dbb38e1ac7e6ad5e78ad21171 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 14 Jan 2024 14:20:50 +0000 Subject: [PATCH 13/15] [pre-commit.ci] auto fixes from pre-commit.com hooks --- stubs/docutils/docutils/nodes.pyi | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 242a3c102d8f..ee4e88c8bb38 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -4,8 +4,7 @@ from _typeshed import Incomplete from abc import abstractmethod from collections.abc import Callable, Generator, Iterable, Iterator, Mapping, Sequence from typing import Any, ClassVar, Literal, Protocol, SupportsIndex, TypeVar, overload -from typing_extensions import TypeAlias -from typing_extensions import Self +from typing_extensions import Self, TypeAlias from docutils.transforms import Transform, Transformer from docutils.utils import Reporter From 38a09e6360245910259e17aef0c480a07ffcc5ae Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Sat, 27 Jan 2024 16:19:09 +0100 Subject: [PATCH 14/15] Any trick --- stubs/docutils/docutils/nodes.pyi | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index ee4e88c8bb38..1911a5c99949 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -19,7 +19,10 @@ class _DomModule(Protocol): class Node: # children is initialized by the subclasses children: Sequence[Node] - parent: Node | None + # TODO: `parent` is actually `Node | None``, but `None`` only happens rarely, + # i.e. for synthetic nodes or `document`. + # See https://github.com/python/typeshed/blob/main/CONTRIBUTING.md#the-any-trick + parent: Node | Any source: str | None line: int | None document: document | None From 8b0506c96cbd1d34cc0abc36d88b931bd986d52b Mon Sep 17 00:00:00 2001 From: "Philipp A." Date: Mon, 29 Jan 2024 17:35:52 +0100 Subject: [PATCH 15/15] Only elements are parents --- stubs/docutils/docutils/nodes.pyi | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/stubs/docutils/docutils/nodes.pyi b/stubs/docutils/docutils/nodes.pyi index 1911a5c99949..0a8ab99842b6 100644 --- a/stubs/docutils/docutils/nodes.pyi +++ b/stubs/docutils/docutils/nodes.pyi @@ -19,10 +19,10 @@ class _DomModule(Protocol): class Node: # children is initialized by the subclasses children: Sequence[Node] - # TODO: `parent` is actually `Node | None``, but `None`` only happens rarely, - # i.e. for synthetic nodes or `document`. + # 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: Node | Any + parent: Element | Any source: str | None line: int | None document: document | None @@ -179,6 +179,7 @@ class Labeled: ... # Root Element class document(Root, Structural, Element): + parent: None transformer: Transformer def __init__(self, settings, reporter: Reporter, rawsource: str = "", *children: Node, **attributes) -> None: ... def __getattr__(self, __name: str) -> Incomplete: ...