From c4a50e7c4dc6b3e832d0a88e89be3b29544cf92b Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Sun, 1 Jun 2025 19:25:27 +0100 Subject: [PATCH 01/16] First pass of `Body(RSTState)` annotations --- .../docutils/docutils/parsers/rst/states.pyi | 356 ++++++------------ 1 file changed, 124 insertions(+), 232 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 8e657cd3cdad..9f06576376c6 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,16 +1,18 @@ from _typeshed import Incomplete -from collections.abc import Callable, Iterable, Sequence +from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType -from typing import Any, ClassVar, Final, NoReturn +from typing import Any, Literal, TypeVar from typing_extensions import TypeAlias from docutils import ApplicationError, DataError, nodes -from docutils.parsers.rst.languages import _RstLanguageModule +from docutils.parsers.rst import Directive +from docutils.parsers.rst.tableparser import TableParser from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList from docutils.utils import Reporter -__docformat__: Final = "reStructuredText" +_Context = TypeVar("_Context") +_TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] class MarkupError(DataError): ... class UnknownInterpretedRoleError(DataError): ... @@ -21,14 +23,8 @@ class MarkupMismatch(Exception): ... class Struct: def __init__(self, **keywordargs) -> None: ... -class RSTStateMachine(StateMachineWS[list[str]]): - language: _RstLanguageModule - match_titles: bool - memo: Struct | None - document: nodes.document - reporter: Reporter - node: nodes.document | None - def run( # type: ignore[override] +class RSTStateMachine(StateMachineWS[Incomplete]): + def run( self, input_lines: Sequence[str] | StringList, document: nodes.document, @@ -37,15 +33,9 @@ class RSTStateMachine(StateMachineWS[list[str]]): inliner: Inliner | None = None, ) -> None: ... -class NestedStateMachine(StateMachineWS[list[str]]): - match_titles: bool - memo: Incomplete - document: nodes.document - reporter: Reporter - language: Incomplete - node: Incomplete - def run( # type: ignore[override] - self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node, match_titles: bool = True +class NestedStateMachine(StateMachineWS[Incomplete]): + def run( + self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node: nodes.Node, match_titles: bool = True ) -> list[str]: ... class RSTState(StateWS[list[str]]): @@ -91,7 +81,7 @@ class RSTState(StateWS[list[str]]): def inline_text(self, text: str, lineno: int): ... def unindent_warning(self, node_name: str): ... -def build_regexp(definition, compile: bool = True): ... +def build_regexp(definition: _BasicDefinition, compile: bool = True): ... _BasicDefinition: TypeAlias = tuple[str, str, str, list[Pattern[str]]] _DefinitionParts: TypeAlias = tuple[str, str, str, list[Pattern[str] | _BasicDefinition]] @@ -177,217 +167,119 @@ class Inliner: dispatch: dict[str, Callable[[Match[str], int], tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]] = ... 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, ...]] - 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): ... - 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): ... - -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): ... - -class SpecializedBody(Body): - def invalid_input( - self, match: Match[str] | None = None, context: list[str] | None = None, next_state: str | None = None - ) -> NoReturn: ... - 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 - -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]]: ... - -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] - -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]]: ... - -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]]: ... + double_width_pad_char: TableParser + enum: Struct + grid_table_top_pat: Pattern[str] + simple_table_top_pat: Pattern[str] + pats: dict[str, str] + patterns: dict[str, str | Pattern[str]] + initial_transitions: tuple[str, ...] + attribution_pattern: Pattern[str] + explicit = Struct() -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]]: ... - -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 - -class ExtensionOptions(FieldList): + def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... + def split_attribution( + self, indented: StringList, line_offset: int + ) -> tuple[StringList, None, None, None, None] | tuple[StringList, StringList, int, StringList, int]: ... + def check_attribution(self, indented: StringList, attribution_start: int) -> tuple[None, None]: ... + def parse_attribution(self, indented: StringList, line_offset: int) -> tuple[nodes.attribution, nodes.system_message]: ... + def bullet(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def list_item(self, indent: int) -> tuple[nodes.list_item, bool]: ... + def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def parse_enumerator( + self, match: Match[str], expected_sequence: str | None = None + ) -> tuple[Literal["period", "parens", "rparen"], str, str, int | None]: ... + def is_enumerated_list_item(self, ordinal: int | None, sequence: str, format) -> bool: ... + def make_enumerator(self, ordinal: int, sequence: str, format) -> tuple[str, str] | None: ... + def field_marker(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + 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, offset, node) -> None: ... + def option_marker(self, match: Match[str], context, next_state): ... + 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[_Context]: ... + def line_block(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def line_block_line(self, match: Match[str], lineno: int) -> tuple[nodes.line, nodes.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[_Context]: ... + def simple_table_top(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def table_top( + self, match: Match[str], context, next_state: str, isolate_function, parser_class + ) -> tuple[list[Incomplete], str, list[Incomplete]]: ... + def table(self, isolate_function, parser_class) -> tuple[list[Incomplete], bool]: ... + def isolate_grid_table(self) -> tuple[StringList | list[Incomplete], list[Incomplete], Literal[1, 0]]: ... + def isolate_simple_table(self) -> tuple[StringList | list[Incomplete], list[Incomplete], bool]: ... + def malformed_table(self, block, detail: str = "", offset: int = 0) -> list[Incomplete]: ... + def build_table( + self, tabledata: tuple[Incomplete, Incomplete, Incomplete], tableline, stub_columns: int = 0, widths=None + ) -> nodes.table: ... + def build_table_row(self, rowdata, tableline) -> nodes.row: ... + def footnote(self, match: Match[str]) -> tuple[list[nodes.footnote], bool]: ... + def citation(self, match: Match[str]) -> tuple[list[nodes.citation], bool]: ... + def hyperlink_target(self, match: Match[str]) -> tuple[list[nodes.target], bool]: ... + def make_target(self, block: StringList, block_text, lineno: int, target_name: str | None) -> nodes.target | str: ... + def parse_target( + self, block: StringList, block_text, lineno: int + ) -> tuple[Literal["refname"], str] | tuple[Literal["refuri"], str]: ... + def is_reference(self, reference: str) -> str | None: ... + def add_target(self, targetname: str | None, refuri: str, target: nodes.Element, lineno: int) -> None: ... + def substitution_def(self, match: Match[str]) -> tuple[list[Incomplete], bool]: ... + def disallowed_inside_substitution_definitions(self, node: nodes.Node) -> bool: ... + def directive(self, match: Match[str], **option_presets) -> tuple[list[nodes.Node], bool]: ... + def run_directive(self, directive: Directive, match: Match[str], type_name: str, option_presets: dict[str, Any]): ... + def parse_directive_block( + self, indented: list[str], line_offset: int, directive: Directive, option_presets: dict[str, Any] + ): ... + def parse_directive_options(self, option_presets, option_spec: Mapping[str, Incomplete], arg_block): ... + def parse_directive_arguments(self, directive: Directive, arg_block): ... + def parse_extension_options( + self, option_spec: Mapping[str, Incomplete], datalines: Sequence[str] + ) -> tuple[Literal[0], str] | tuple[Literal[1], dict[str, Any]]: ... + def unknown_directive(self, type_name: str) -> tuple[list[Incomplete], bool]: ... + def comment(self, match: Match[str]) -> tuple[list[nodes.comment], bool]: ... + def explicit_markup(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Incomplete]]: ... + def explicit_construct(self, match: Match[str]) -> tuple[list[Incomplete], bool]: ... + def explicit_list(self, blank_finish) -> None: ... + def anonymous(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Any]]: ... + def anonymous_target(self, match: Match[str]) -> tuple[list[nodes.target], bool]: ... + def line(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Any]]: ... + def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], list[Any]]: ... -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]]: ... - -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]]: ... - -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: ... - -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): ... - -class SpecializedText(Text): - def eof(self, context): ... - def invalid_input( - self, match: Match[str] | None = None, context: list[str] | None = None, next_state: str | None = None - ) -> NoReturn: ... - blank = invalid_input - indent = invalid_input - underline = invalid_input - text = invalid_input - -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]]: ... - -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: ... - -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) -> NoReturn: ... - 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: ... +class RFC2822Body(Body): ... +class SpecializedBody(Body): ... +class BulletList(SpecializedBody): ... +class DefinitionList(SpecializedBody): ... +class EnumeratedList(SpecializedBody): ... +class FieldList(SpecializedBody): ... +class OptionList(SpecializedBody): ... +class RFC2822List(SpecializedBody, RFC2822Body): ... +class ExtensionOptions(FieldList): ... +class LineBlock(SpecializedBody): ... +class Explicit(SpecializedBody): ... +class SubstitutionDef(Body): ... +class Text(RSTState): ... +class SpecializedText(Text): ... +class Definition(SpecializedText): ... +class Line(SpecializedText): ... +class QuotedLiteralBlock(RSTState): ... -state_classes: tuple[type[RSTState], ...] +state_classes: tuple[ + Body, + BulletList, + DefinitionList, + EnumeratedList, + FieldList, + OptionList, + LineBlock, + ExtensionOptions, + Explicit, + Text, + Definition, + Line, + SubstitutionDef, + RFC2822Body, + RFC2822List, +] From 1b63dc68b1e51b2c8911aee0b82221e75689ceb6 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Sun, 1 Jun 2025 20:10:33 +0100 Subject: [PATCH 02/16] First pass of `Body` subclass annotations --- .../docutils/docutils/parsers/rst/states.pyi | 151 +++++++++++++++--- 1 file changed, 131 insertions(+), 20 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 9f06576376c6..1e1c935a2706 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -2,7 +2,7 @@ from _typeshed import Incomplete from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType -from typing import Any, Literal, TypeVar +from typing import Any, Literal, Never, TypeVar, overload from typing_extensions import TypeAlias from docutils import ApplicationError, DataError, nodes @@ -12,6 +12,8 @@ from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringL from docutils.utils import Reporter _Context = TypeVar("_Context") +_NextState = TypeVar("_NextState", str, None) +_EmptyContext = TypeVar("_EmptyContext", Literal[""], None) _TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] class MarkupError(DataError): ... @@ -177,14 +179,14 @@ class Body(RSTState): attribution_pattern: Pattern[str] explicit = Struct() - def indent(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def indent(self, match: Any, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... def split_attribution( self, indented: StringList, line_offset: int ) -> tuple[StringList, None, None, None, None] | tuple[StringList, StringList, int, StringList, int]: ... def check_attribution(self, indented: StringList, attribution_start: int) -> tuple[None, None]: ... def parse_attribution(self, indented: StringList, line_offset: int) -> tuple[nodes.attribution, nodes.system_message]: ... - def bullet(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... def list_item(self, indent: int) -> tuple[nodes.list_item, bool]: ... def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def parse_enumerator( @@ -248,23 +250,132 @@ class Body(RSTState): def line(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Any]]: ... def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], list[Any]]: ... -class RFC2822Body(Body): ... -class SpecializedBody(Body): ... -class BulletList(SpecializedBody): ... -class DefinitionList(SpecializedBody): ... -class EnumeratedList(SpecializedBody): ... -class FieldList(SpecializedBody): ... -class OptionList(SpecializedBody): ... -class RFC2822List(SpecializedBody, RFC2822Body): ... -class ExtensionOptions(FieldList): ... -class LineBlock(SpecializedBody): ... -class Explicit(SpecializedBody): ... -class SubstitutionDef(Body): ... -class Text(RSTState): ... -class SpecializedText(Text): ... -class Definition(SpecializedText): ... -class Line(SpecializedText): ... -class QuotedLiteralBlock(RSTState): ... +class RFC2822Body(Body): + patterns: dict[str, str | Pattern[str]] + initial_transitions: list[tuple[str | tuple[str, str], str]] + + def rfc2822(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... + def rfc2822_field(self, match: Match[str]): ... + +class SpecializedBody(Body): + def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + + indent = invalid_input + 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 + line = invalid_input + text = invalid_input + +class BulletList(SpecializedBody): + def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + +class DefinitionList(SpecializedBody): + def text(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[str], Literal["Definition"], list[Any]]: ... + +class EnumeratedList(SpecializedBody): + def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + +class FieldList(SpecializedBody): + def field_marker( + self, match: Match[str], context: Any, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... + +class OptionList(SpecializedBody): + def option_marker( + self, match: Match[str], context: Any, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... + +class RFC2822List(SpecializedBody, RFC2822Body): + def rfc2822( + self, match: Match[str], context: Any, next_state: Any + ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... + def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + +class ExtensionOptions(FieldList): + def parse_field_body(self, indented: StringList, offset: Any, node: nodes.Node) -> None: ... + +class LineBlock(SpecializedBody): + def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + +class Explicit(SpecializedBody): + def explicit_markup( + self, match: Match[str], context: Any, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... + def anonymous(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + +class SubstitutionDef(Body): + def embedded_directive(self, match: Match[str], context: Any, next_state: Any) -> Never: ... + def text(self, match: Any, context: Any, next_state: Any) -> Never: ... + +class Text(RSTState): + classifier_delimiter: Pattern[str] + + def blank(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def eof(self, context: Any) -> list[Any]: ... + def indent(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def underline( + self, match: Match[Any], context: Sequence[str], next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... + def text(self, match: Any, context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def literal_block(self) -> list[nodes.Node]: ... + def quoted_literal_block(self) -> list[nodes.Node]: ... + def definition_list_item(self, termline: StringList) -> tuple[nodes.definition_list_item, bool]: ... + def term(self, lines: StringList, lineno: int) -> tuple[nodes.Node, nodes.system_message]: ... + +class SpecializedText(Text): + def eof(self, context: Any) -> list[Any]: ... + def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + + blank = invalid_input + indent = invalid_input + underline = invalid_input + text = invalid_input + +class Definition(SpecializedText): + def eof(self, context: Any) -> list[Any]: ... + def indent( + self, match: Any, context: StringList, next_state: Any + ) -> tuple[list[Any], Literal["DefinitionList"], list[Any]]: ... + +class Line(SpecializedText): + eofcheck: Literal[1] + + def eof(self, context: Any) -> list[Any]: ... + def blank(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def text(self, match: Match[str], context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def indent(self, match: Match[str], context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def underline(self, match: Any, context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def short_overline(self, context: list[Any], blocktext: Any, lineno: int | None, lines: int = 1) -> None: ... + def state_correction(self, context: list[Any], lines: int = 1) -> Never: ... + +class QuotedLiteralBlock(RSTState): + messages: list[Incomplete] + initial_lineno: int | None + + def __init__(self, state_machine: StateMachine[Incomplete], debug=False) -> None: ... + @overload + def blank( + self, match: Any, context: _EmptyContext, next_state: _NextState + ) -> tuple[_EmptyContext, _NextState, list[Any]]: ... + @overload + def blank(self, match: Any, context: Any, next_state: _NextState) -> Never: ... + def eof(self, context: StringList) -> list[Any]: ... + def indent(self, match: Any, context: StringList, next_state: Any) -> Never: ... + def initial_quoted( + self, match: Match[str], context: Any, next_state: _NextState + ) -> tuple[list[str], _NextState, list[Any]]: ... + def quoted(self, match: Match[str], context: _Context, next_state: _NextState) -> tuple[_Context, _NextState, list[Any]]: ... + def text(self, match: Any, context: Any, next_state: Any) -> Never: ... state_classes: tuple[ Body, From dfefce2819c6ea9c58013d6b4b74ab24fc039543 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Sun, 1 Jun 2025 20:31:35 +0100 Subject: [PATCH 03/16] Implement some changes from #14191 Co-authored-by: Semyon Moroz --- .../docutils/docutils/parsers/rst/states.pyi | 67 ++++++++++++++++--- 1 file changed, 56 insertions(+), 11 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 1e1c935a2706..06fa951b8726 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -2,15 +2,18 @@ from _typeshed import Incomplete from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType -from typing import Any, Literal, Never, TypeVar, overload -from typing_extensions import TypeAlias +from typing import Any, ClassVar, Final, Literal, TypeVar, overload +from typing_extensions import Never, TypeAlias from docutils import ApplicationError, DataError, nodes from docutils.parsers.rst import Directive +from docutils.parsers.rst.languages import _RstLanguageModule from docutils.parsers.rst.tableparser import TableParser from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList from docutils.utils import Reporter +__docformat__: Final = "reStructuredText" + _Context = TypeVar("_Context") _NextState = TypeVar("_NextState", str, None) _EmptyContext = TypeVar("_EmptyContext", Literal[""], None) @@ -26,6 +29,12 @@ class Struct: def __init__(self, **keywordargs) -> None: ... class RSTStateMachine(StateMachineWS[Incomplete]): + language: _RstLanguageModule + match_titles: bool + memo: Struct | None + document: nodes.document + reporter: Reporter + node: nodes.document | None def run( self, input_lines: Sequence[str] | StringList, @@ -36,13 +45,20 @@ class RSTStateMachine(StateMachineWS[Incomplete]): ) -> None: ... class NestedStateMachine(StateMachineWS[Incomplete]): + match_titles: bool + memo: Incomplete + document: nodes.document + reporter: Reporter + language: Incomplete + node: Incomplete def run( self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node: nodes.Node, match_titles: bool = True ) -> list[str]: ... class RSTState(StateWS[list[str]]): - nested_sm: type[NestedStateMachine] - nested_sm_cache: list[StateMachine[Incomplete]] + nested_sm: ClassVar[type[NestedStateMachine]] + nested_sm_cache: ClassVar[list[StateMachine[Incomplete]]] + nested_sm_kwargs: dict[str, Any] def __init__(self, state_machine, debug: bool = False) -> None: ... memo: Incomplete reporter: Reporter @@ -174,13 +190,15 @@ class Body(RSTState): grid_table_top_pat: Pattern[str] simple_table_top_pat: Pattern[str] pats: dict[str, str] - patterns: dict[str, str | Pattern[str]] - initial_transitions: tuple[str, ...] - attribution_pattern: Pattern[str] - explicit = Struct() + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[tuple[str, ...]] + explicit: Struct def indent(self, match: Any, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... + + attribution_pattern: Pattern[str] + def split_attribution( self, indented: StringList, line_offset: int ) -> tuple[StringList, None, None, None, None] | tuple[StringList, StringList, int, StringList, int]: ... @@ -251,13 +269,15 @@ class Body(RSTState): def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], list[Any]]: ... class RFC2822Body(Body): - patterns: dict[str, str | Pattern[str]] - initial_transitions: list[tuple[str | tuple[str, str], str]] + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] def rfc2822(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... def rfc2822_field(self, match: Match[str]): ... class SpecializedBody(Body): + blank_finish: Incomplete + def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... indent = invalid_input @@ -281,19 +301,31 @@ class DefinitionList(SpecializedBody): def text(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[str], Literal["Definition"], list[Any]]: ... class EnumeratedList(SpecializedBody): + auto: int + blank_finish: Incomplete + lastordinal: Incomplete + def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... class FieldList(SpecializedBody): + blank_finish: Incomplete + def field_marker( self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class OptionList(SpecializedBody): + blank_finish: Incomplete + def option_marker( self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class RFC2822List(SpecializedBody, RFC2822Body): + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] + blank_finish: Incomplete + def rfc2822( self, match: Match[str], context: Any, next_state: Any ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... @@ -303,10 +335,16 @@ class ExtensionOptions(FieldList): def parse_field_body(self, indented: StringList, offset: Any, node: nodes.Node) -> None: ... class LineBlock(SpecializedBody): + blank: Incomplete + blank_finish: Incomplete + def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... class Explicit(SpecializedBody): + blank_finish: Incomplete + blank: Incomplete + def explicit_markup( self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... @@ -314,11 +352,16 @@ class Explicit(SpecializedBody): def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... class SubstitutionDef(Body): + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[list[str]] + blank_finish: Incomplete + def embedded_directive(self, match: Match[str], context: Any, next_state: Any) -> Never: ... def text(self, match: Any, context: Any, next_state: Any) -> Never: ... class Text(RSTState): - classifier_delimiter: Pattern[str] + patterns: ClassVar[dict[str, str | Pattern[str]]] + initial_transitions: ClassVar[list[tuple[str, str]]] def blank(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... def eof(self, context: Any) -> list[Any]: ... @@ -330,6 +373,7 @@ class Text(RSTState): def literal_block(self) -> list[nodes.Node]: ... def quoted_literal_block(self) -> list[nodes.Node]: ... def definition_list_item(self, termline: StringList) -> tuple[nodes.definition_list_item, bool]: ... + classifier_delimiter: Pattern[str] def term(self, lines: StringList, lineno: int) -> tuple[nodes.Node, nodes.system_message]: ... class SpecializedText(Text): @@ -359,6 +403,7 @@ class Line(SpecializedText): def state_correction(self, context: list[Any], lines: int = 1) -> Never: ... class QuotedLiteralBlock(RSTState): + patterns: ClassVar[dict[str, str | Pattern[str]]] messages: list[Incomplete] initial_lineno: int | None From beec95fd6960ff22dfbe4676af300ba5ad146b93 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Sun, 1 Jun 2025 20:49:16 +0100 Subject: [PATCH 04/16] Fix MyPy errors --- .../docutils/docutils/parsers/rst/states.pyi | 50 +++++++++---------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 06fa951b8726..e44c88488048 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,16 +1,16 @@ -from _typeshed import Incomplete from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType from typing import Any, ClassVar, Final, Literal, TypeVar, overload -from typing_extensions import Never, TypeAlias +from _typeshed import Incomplete from docutils import ApplicationError, DataError, nodes from docutils.parsers.rst import Directive from docutils.parsers.rst.languages import _RstLanguageModule from docutils.parsers.rst.tableparser import TableParser from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList from docutils.utils import Reporter +from typing_extensions import Never, TypeAlias __docformat__: Final = "reStructuredText" @@ -35,7 +35,7 @@ class RSTStateMachine(StateMachineWS[Incomplete]): document: nodes.document reporter: Reporter node: nodes.document | None - def run( + def run( # type: ignore[override] self, input_lines: Sequence[str] | StringList, document: nodes.document, @@ -51,12 +51,12 @@ class NestedStateMachine(StateMachineWS[Incomplete]): reporter: Reporter language: Incomplete node: Incomplete - def run( + def run( # type: ignore[override] self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node: nodes.Node, match_titles: bool = True ) -> list[str]: ... class RSTState(StateWS[list[str]]): - nested_sm: ClassVar[type[NestedStateMachine]] + nested_sm: ClassVar[type[NestedStateMachine]] # type: ignore[misc] nested_sm_cache: ClassVar[list[StateMachine[Incomplete]]] nested_sm_kwargs: dict[str, Any] def __init__(self, state_machine, debug: bool = False) -> None: ... @@ -270,7 +270,7 @@ class Body(RSTState): class RFC2822Body(Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] + initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] # type: ignore[assignment] def rfc2822(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... def rfc2822_field(self, match: Match[str]): ... @@ -295,29 +295,29 @@ class SpecializedBody(Body): text = invalid_input class BulletList(SpecializedBody): - def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class DefinitionList(SpecializedBody): - def text(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[str], Literal["Definition"], list[Any]]: ... + def text(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[str], Literal["Definition"], list[Any]]: ... # type: ignore[override] class EnumeratedList(SpecializedBody): auto: int blank_finish: Incomplete lastordinal: Incomplete - def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class FieldList(SpecializedBody): blank_finish: Incomplete - def field_marker( + def field_marker( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class OptionList(SpecializedBody): blank_finish: Incomplete - def option_marker( + def option_marker( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... @@ -326,7 +326,7 @@ class RFC2822List(SpecializedBody, RFC2822Body): initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] blank_finish: Incomplete - def rfc2822( + def rfc2822( # type: ignore[override] self, match: Match[str], context: Any, next_state: Any ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... @@ -335,25 +335,23 @@ class ExtensionOptions(FieldList): def parse_field_body(self, indented: StringList, offset: Any, node: nodes.Node) -> None: ... class LineBlock(SpecializedBody): - blank: Incomplete blank_finish: Incomplete def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... - def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class Explicit(SpecializedBody): blank_finish: Incomplete - blank: Incomplete - def explicit_markup( + def explicit_markup( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... - def anonymous(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def anonymous(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... class SubstitutionDef(Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[str]] + initial_transitions: ClassVar[list[str]] # type: ignore[assignment] blank_finish: Incomplete def embedded_directive(self, match: Match[str], context: Any, next_state: Any) -> Never: ... @@ -387,18 +385,18 @@ class SpecializedText(Text): class Definition(SpecializedText): def eof(self, context: Any) -> list[Any]: ... - def indent( - self, match: Any, context: StringList, next_state: Any + def indent( # type: ignore[override] + self, match: Any, context: list[str], next_state: Any ) -> tuple[list[Any], Literal["DefinitionList"], list[Any]]: ... class Line(SpecializedText): eofcheck: Literal[1] def eof(self, context: Any) -> list[Any]: ... - def blank(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... - def text(self, match: Match[str], context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... - def indent(self, match: Match[str], context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... - def underline(self, match: Any, context: StringList, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def blank(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def text(self, match: Match[str], context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def indent(self, match: Match[str], context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def underline(self, match: Any, context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] def short_overline(self, context: list[Any], blocktext: Any, lineno: int | None, lines: int = 1) -> None: ... def state_correction(self, context: list[Any], lines: int = 1) -> Never: ... @@ -414,8 +412,8 @@ class QuotedLiteralBlock(RSTState): ) -> tuple[_EmptyContext, _NextState, list[Any]]: ... @overload def blank(self, match: Any, context: Any, next_state: _NextState) -> Never: ... - def eof(self, context: StringList) -> list[Any]: ... - def indent(self, match: Any, context: StringList, next_state: Any) -> Never: ... + def eof(self, context: list[str]) -> list[Any]: ... + def indent(self, match: Any, context: list[str], next_state: Any) -> Never: ... def initial_quoted( self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[str], _NextState, list[Any]]: ... From e6cab0c4dbc96ba667cc5b1969fcdc00417bb47b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 1 Jun 2025 19:50:57 +0000 Subject: [PATCH 05/16] [pre-commit.ci] auto fixes from pre-commit.com hooks --- stubs/docutils/docutils/parsers/rst/states.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index e44c88488048..1b1a0cc7d4c1 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,16 +1,16 @@ +from _typeshed import Incomplete from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType from typing import Any, ClassVar, Final, Literal, TypeVar, overload +from typing_extensions import Never, TypeAlias -from _typeshed import Incomplete from docutils import ApplicationError, DataError, nodes from docutils.parsers.rst import Directive from docutils.parsers.rst.languages import _RstLanguageModule from docutils.parsers.rst.tableparser import TableParser from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList from docutils.utils import Reporter -from typing_extensions import Never, TypeAlias __docformat__: Final = "reStructuredText" From 69f5c9c1202a58de8ff568df8e4049690ac1fffd Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 15:21:40 +0100 Subject: [PATCH 06/16] Fix incomplete type annotations --- stubs/docutils/docutils/parsers/rst/states.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 1b1a0cc7d4c1..63d23fc512af 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -28,7 +28,7 @@ class MarkupMismatch(Exception): ... class Struct: def __init__(self, **keywordargs) -> None: ... -class RSTStateMachine(StateMachineWS[Incomplete]): +class RSTStateMachine(StateMachineWS[list[str]]): language: _RstLanguageModule match_titles: bool memo: Struct | None @@ -44,7 +44,7 @@ class RSTStateMachine(StateMachineWS[Incomplete]): inliner: Inliner | None = None, ) -> None: ... -class NestedStateMachine(StateMachineWS[Incomplete]): +class NestedStateMachine(StateMachineWS[list[str]]): match_titles: bool memo: Incomplete document: nodes.document From 7fb31b9aa6a3f8afaf23cca7e7e052d6bc16de9c Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 21:49:09 +0100 Subject: [PATCH 07/16] Remove redundant whitespace --- stubs/docutils/docutils/parsers/rst/states.pyi | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 63d23fc512af..c30548078fa2 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -193,12 +193,9 @@ class Body(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[tuple[str, ...]] explicit: Struct - def indent(self, match: Any, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... - attribution_pattern: Pattern[str] - def split_attribution( self, indented: StringList, line_offset: int ) -> tuple[StringList, None, None, None, None] | tuple[StringList, StringList, int, StringList, int]: ... @@ -271,15 +268,12 @@ class Body(RSTState): 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: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... def rfc2822_field(self, match: Match[str]): ... class SpecializedBody(Body): blank_finish: Incomplete - def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... - indent = invalid_input bullet = invalid_input enumerator = invalid_input @@ -304,19 +298,16 @@ class EnumeratedList(SpecializedBody): auto: int blank_finish: Incomplete lastordinal: Incomplete - def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class FieldList(SpecializedBody): blank_finish: Incomplete - def field_marker( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class OptionList(SpecializedBody): blank_finish: Incomplete - def option_marker( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... @@ -325,7 +316,6 @@ class RFC2822List(SpecializedBody, RFC2822Body): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] blank_finish: Incomplete - def rfc2822( # type: ignore[override] self, match: Match[str], context: Any, next_state: Any ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... @@ -336,13 +326,11 @@ class ExtensionOptions(FieldList): class LineBlock(SpecializedBody): blank_finish: Incomplete - def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class Explicit(SpecializedBody): blank_finish: Incomplete - def explicit_markup( # type: ignore[override] self, match: Match[str], context: Any, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... @@ -391,7 +379,6 @@ class Definition(SpecializedText): class Line(SpecializedText): eofcheck: Literal[1] - def eof(self, context: Any) -> list[Any]: ... def blank(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] def text(self, match: Match[str], context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] @@ -404,7 +391,6 @@ class QuotedLiteralBlock(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] messages: list[Incomplete] initial_lineno: int | None - def __init__(self, state_machine: StateMachine[Incomplete], debug=False) -> None: ... @overload def blank( From 306e16e18fe91d4f9f8bb917a4c3808a7cf6ae6a Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 21:59:20 +0100 Subject: [PATCH 08/16] First pass of replacing Any -> Unused --- .../docutils/docutils/parsers/rst/states.pyi | 62 ++++++++++--------- 1 file changed, 33 insertions(+), 29 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index c30548078fa2..5ab3d13dbb25 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,4 +1,4 @@ -from _typeshed import Incomplete +from _typeshed import Incomplete, Unused from collections.abc import Callable, Iterable, Mapping, Sequence from re import Match, Pattern from types import ModuleType @@ -268,12 +268,11 @@ class Body(RSTState): 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: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... + def rfc2822(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... def rfc2822_field(self, match: Match[str]): ... class SpecializedBody(Body): - blank_finish: Incomplete - def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + def invalid_input(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... indent = invalid_input bullet = invalid_input enumerator = invalid_input @@ -289,16 +288,20 @@ class SpecializedBody(Body): text = invalid_input class BulletList(SpecializedBody): - def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + def bullet(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class DefinitionList(SpecializedBody): - def text(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[str], Literal["Definition"], list[Any]]: ... # type: ignore[override] + def text( + self, match: Match[str], context: Unused, next_state: Unused + ) -> tuple[list[str], Literal["Definition"], list[Any]]: ... # type: ignore[override] class EnumeratedList(SpecializedBody): auto: int blank_finish: Incomplete lastordinal: Incomplete - def enumerator(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + def enumerator( + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class FieldList(SpecializedBody): blank_finish: Incomplete @@ -341,21 +344,19 @@ 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: Match[str], context: Any, next_state: Any) -> Never: ... def text(self, match: Any, context: Any, next_state: Any) -> Never: ... class Text(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str, str]]] - - def blank(self, match: Match[str], context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... - def eof(self, context: Any) -> list[Any]: ... - def indent(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def blank(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def eof(self, context) -> list[Any]: ... + def indent(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... def underline( self, match: Match[Any], context: Sequence[str], next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... - def text(self, match: Any, context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def text(self, match: Unused, context, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... def literal_block(self) -> list[nodes.Node]: ... def quoted_literal_block(self) -> list[nodes.Node]: ... def definition_list_item(self, termline: StringList) -> tuple[nodes.definition_list_item, bool]: ... @@ -363,28 +364,31 @@ class Text(RSTState): def term(self, lines: StringList, lineno: int) -> tuple[nodes.Node, nodes.system_message]: ... class SpecializedText(Text): - def eof(self, context: Any) -> list[Any]: ... - def invalid_input(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... - + def eof(self, context: Unused) -> list[Any]: ... + def invalid_input(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... blank = invalid_input indent = invalid_input underline = invalid_input text = invalid_input class Definition(SpecializedText): - def eof(self, context: Any) -> list[Any]: ... + def eof(self, context: Unused) -> list[Any]: ... def indent( # type: ignore[override] - self, match: Any, context: list[str], next_state: Any - ) -> tuple[list[Any], Literal["DefinitionList"], list[Any]]: ... + self, match: Unused, context: list[str], next_state: Unused + ) -> tuple[list[str], Literal["DefinitionList"], list[str]]: ... class Line(SpecializedText): eofcheck: Literal[1] def eof(self, context: Any) -> list[Any]: ... - def blank(self, match: Any, context: Any, next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def text(self, match: Match[str], context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def indent(self, match: Match[str], context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def underline(self, match: Any, context: list[str], next_state: Any) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def short_overline(self, context: list[Any], blocktext: Any, lineno: int | None, lines: int = 1) -> None: ... + def blank(self, match: Unused, context: Any, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def text(self, match: Match[str], context: list[str], next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def indent( + self, match: Match[str], context: list[str], next_state: Unused + ) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def underline( + self, match: Unused, context: list[str], next_state: Unused + ) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def short_overline(self, context: list[Any], blocktext: Unused, lineno: int | None, lines: int = 1) -> None: ... def state_correction(self, context: list[Any], lines: int = 1) -> Never: ... class QuotedLiteralBlock(RSTState): @@ -394,17 +398,17 @@ class QuotedLiteralBlock(RSTState): def __init__(self, state_machine: StateMachine[Incomplete], debug=False) -> None: ... @overload def blank( - self, match: Any, context: _EmptyContext, next_state: _NextState + self, match: Unused, context: _EmptyContext, next_state: _NextState ) -> tuple[_EmptyContext, _NextState, list[Any]]: ... @overload - def blank(self, match: Any, context: Any, next_state: _NextState) -> Never: ... + def blank(self, match: Unused, context: Any, next_state: _NextState) -> Never: ... def eof(self, context: list[str]) -> list[Any]: ... - def indent(self, match: Any, context: list[str], next_state: Any) -> Never: ... + def indent(self, match: Unused, context: list[str], next_state: Unused) -> Never: ... def initial_quoted( - self, match: Match[str], context: Any, next_state: _NextState + self, match: Match[str], context: Unused, next_state: _NextState ) -> tuple[list[str], _NextState, list[Any]]: ... def quoted(self, match: Match[str], context: _Context, next_state: _NextState) -> tuple[_Context, _NextState, list[Any]]: ... - def text(self, match: Any, context: Any, next_state: Any) -> Never: ... + def text(self, match: Unused, context: Any, next_state: Unused) -> Never: ... state_classes: tuple[ Body, From 759f4e9ed32bba7d9307f82cf0f0116d47100ebf Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:12:35 +0100 Subject: [PATCH 09/16] Replace more Any -> Unused and remove several uncertain annotations --- .../docutils/docutils/parsers/rst/states.pyi | 54 ++++++++----------- 1 file changed, 21 insertions(+), 33 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 5ab3d13dbb25..ce51592480ff 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -306,13 +306,13 @@ class EnumeratedList(SpecializedBody): class FieldList(SpecializedBody): blank_finish: Incomplete def field_marker( # type: ignore[override] - self, match: Match[str], context: Any, next_state: _NextState + self, match: Match[str], context: Unused, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class OptionList(SpecializedBody): blank_finish: Incomplete def option_marker( # type: ignore[override] - self, match: Match[str], context: Any, next_state: _NextState + self, match: Match[str], context: Unused, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... class RFC2822List(SpecializedBody, RFC2822Body): @@ -320,38 +320,42 @@ class RFC2822List(SpecializedBody, RFC2822Body): initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] blank_finish: Incomplete def rfc2822( # type: ignore[override] - self, match: Match[str], context: Any, next_state: Any + self, match: Match[str], context: Unused, next_state: Unused ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... - def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... class ExtensionOptions(FieldList): - def parse_field_body(self, indented: StringList, offset: Any, node: nodes.Node) -> None: ... + def parse_field_body(self, indented: StringList, offset, node: nodes.Node) -> None: ... class LineBlock(SpecializedBody): blank_finish: Incomplete - def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... - def line_block(self, match: Match[Any], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... + def line_block( + self, match: Match[Any], context: Unused, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] class Explicit(SpecializedBody): blank_finish: Incomplete def explicit_markup( # type: ignore[override] - self, match: Match[str], context: Any, next_state: _NextState + self, match: Match[str], context: Unused, next_state: _NextState ) -> tuple[list[Any], _NextState, list[Any]]: ... - def anonymous(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] - def blank(self, match: Any = None, context: Any = None, next_state: Any = None) -> Never: ... + def anonymous( + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... 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: Match[str], context: Any, next_state: Any) -> Never: ... - def text(self, match: Any, context: Any, next_state: Any) -> Never: ... + def embedded_directive(self, match: Match[str], context: Unused, next_state: Unused) -> Never: ... + def text(self, match: Unused, context: Unused, next_state: Unused) -> Never: ... class Text(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str, str]]] def blank(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... - def eof(self, context) -> list[Any]: ... + def eof(self, context): ... def indent(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... def underline( self, match: Match[Any], context: Sequence[str], next_state: _NextState @@ -364,7 +368,7 @@ class Text(RSTState): def term(self, lines: StringList, lineno: int) -> tuple[nodes.Node, nodes.system_message]: ... class SpecializedText(Text): - def eof(self, context: Unused) -> list[Any]: ... + def eof(self, context: Unused): ... def invalid_input(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... blank = invalid_input indent = invalid_input @@ -395,14 +399,14 @@ class QuotedLiteralBlock(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] messages: list[Incomplete] initial_lineno: int | None - def __init__(self, state_machine: StateMachine[Incomplete], debug=False) -> None: ... + def __init__(self, state_machine: StateMachine[Incomplete], debug: bool = False) -> None: ... @overload def blank( self, match: Unused, context: _EmptyContext, next_state: _NextState ) -> tuple[_EmptyContext, _NextState, list[Any]]: ... @overload def blank(self, match: Unused, context: Any, next_state: _NextState) -> Never: ... - def eof(self, context: list[str]) -> list[Any]: ... + def eof(self, context: list[str]): ... def indent(self, match: Unused, context: list[str], next_state: Unused) -> Never: ... def initial_quoted( self, match: Match[str], context: Unused, next_state: _NextState @@ -410,20 +414,4 @@ class QuotedLiteralBlock(RSTState): def quoted(self, match: Match[str], context: _Context, next_state: _NextState) -> tuple[_Context, _NextState, list[Any]]: ... def text(self, match: Unused, context: Any, next_state: Unused) -> Never: ... -state_classes: tuple[ - Body, - BulletList, - DefinitionList, - EnumeratedList, - FieldList, - OptionList, - LineBlock, - ExtensionOptions, - Explicit, - Text, - Definition, - Line, - SubstitutionDef, - RFC2822Body, - RFC2822List, -] +state_classes: tuple[type[RSTState], ...] From 355affe9c95a84816192fcbef64d98b8f825c86c Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:16:02 +0100 Subject: [PATCH 10/16] Re-order stubs --- stubs/docutils/docutils/parsers/rst/states.pyi | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index ce51592480ff..16306e79844d 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -189,10 +189,10 @@ class Body(RSTState): enum: Struct grid_table_top_pat: Pattern[str] simple_table_top_pat: Pattern[str] + simple_table_border_pat: Pattern[str] pats: dict[str, str] patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[tuple[str, ...]] - explicit: Struct def indent(self, match: Any, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... attribution_pattern: Pattern[str] @@ -234,6 +234,7 @@ class Body(RSTState): self, tabledata: tuple[Incomplete, Incomplete, Incomplete], tableline, stub_columns: int = 0, widths=None ) -> nodes.table: ... def build_table_row(self, rowdata, tableline) -> nodes.row: ... + explicit: Struct def footnote(self, match: Match[str]) -> tuple[list[nodes.footnote], bool]: ... def citation(self, match: Match[str]) -> tuple[list[nodes.citation], bool]: ... def hyperlink_target(self, match: Match[str]) -> tuple[list[nodes.target], bool]: ... From 87f645f346b67baa212ee7d900a14aa461499062 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:33:52 +0100 Subject: [PATCH 11/16] Replace `list[Any]` with `EmptyList` --- .../docutils/docutils/parsers/rst/states.pyi | 68 ++++++++++--------- 1 file changed, 35 insertions(+), 33 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 16306e79844d..18edbbfe775b 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -19,6 +19,8 @@ _NextState = TypeVar("_NextState", str, None) _EmptyContext = TypeVar("_EmptyContext", Literal[""], None) _TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] +EmptyList = list[object] + class MarkupError(DataError): ... class UnknownInterpretedRoleError(DataError): ... class InterpretedRoleNotImplementedError(DataError): ... @@ -193,7 +195,7 @@ class Body(RSTState): pats: dict[str, str] patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[tuple[str, ...]] - def indent(self, match: Any, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def indent(self, match: Unused, context: _Context, next_state: str) -> _TransitionResult[_Context]: ... def block_quote(self, indented: StringList, line_offset: int) -> list[nodes.block_quote | nodes.system_message]: ... attribution_pattern: Pattern[str] def split_attribution( @@ -201,9 +203,9 @@ class Body(RSTState): ) -> tuple[StringList, None, None, None, None] | tuple[StringList, StringList, int, StringList, int]: ... def check_attribution(self, indented: StringList, attribution_start: int) -> tuple[None, None]: ... def parse_attribution(self, indented: StringList, line_offset: int) -> tuple[nodes.attribution, nodes.system_message]: ... - def bullet(self, match: Match[str], context: Any, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + def bullet(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[EmptyList, _NextState, EmptyList]: ... def list_item(self, indent: int) -> tuple[nodes.list_item, bool]: ... - def enumerator(self, match: Match[str], context: _Context, next_state: str) -> _TransitionResult[_Context]: ... + def enumerator(self, match: Match[str], context: Unused, next_state: str): ... def parse_enumerator( self, match: Match[str], expected_sequence: str | None = None ) -> tuple[Literal["period", "parens", "rparen"], str, str, int | None]: ... @@ -261,15 +263,15 @@ class Body(RSTState): def explicit_markup(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Incomplete]]: ... def explicit_construct(self, match: Match[str]) -> tuple[list[Incomplete], bool]: ... def explicit_list(self, blank_finish) -> None: ... - def anonymous(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Any]]: ... + def anonymous(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... def anonymous_target(self, match: Match[str]) -> tuple[list[nodes.target], bool]: ... - def line(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Any]]: ... - def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], list[Any]]: ... + def line(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... + def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], EmptyList]: ... 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: Match[str], context: Unused, next_state: _NextState) -> tuple[list[Any], _NextState, list[str]]: ... + def rfc2822(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[EmptyList, _NextState, list[str]]: ... def rfc2822_field(self, match: Match[str]): ... class SpecializedBody(Body): @@ -289,12 +291,12 @@ class SpecializedBody(Body): text = invalid_input class BulletList(SpecializedBody): - def bullet(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + def bullet(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] class DefinitionList(SpecializedBody): def text( self, match: Match[str], context: Unused, next_state: Unused - ) -> tuple[list[str], Literal["Definition"], list[Any]]: ... # type: ignore[override] + ) -> tuple[list[str], Literal["Definition"], EmptyList]: ... # type: ignore[override] class EnumeratedList(SpecializedBody): auto: int @@ -302,19 +304,19 @@ class EnumeratedList(SpecializedBody): lastordinal: Incomplete def enumerator( self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] class FieldList(SpecializedBody): blank_finish: Incomplete def field_marker( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... + ) -> tuple[EmptyList, _NextState, EmptyList]: ... class OptionList(SpecializedBody): blank_finish: Incomplete def option_marker( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... + ) -> tuple[EmptyList, _NextState, EmptyList]: ... class RFC2822List(SpecializedBody, RFC2822Body): patterns: ClassVar[dict[str, str | Pattern[str]]] @@ -322,7 +324,7 @@ class RFC2822List(SpecializedBody, RFC2822Body): blank_finish: Incomplete def rfc2822( # type: ignore[override] self, match: Match[str], context: Unused, next_state: Unused - ) -> tuple[list[Any], Literal["RFC2822List"], list[Any]]: ... + ) -> tuple[EmptyList, Literal["RFC2822List"], EmptyList]: ... def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... class ExtensionOptions(FieldList): @@ -332,17 +334,17 @@ class LineBlock(SpecializedBody): blank_finish: Incomplete def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... def line_block( - self, match: Match[Any], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] class Explicit(SpecializedBody): blank_finish: Incomplete def explicit_markup( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... + ) -> tuple[EmptyList, _NextState, EmptyList]: ... def anonymous( self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... # type: ignore[override] + ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... class SubstitutionDef(Body): @@ -355,13 +357,13 @@ class SubstitutionDef(Body): class Text(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str, str]]] - def blank(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def blank(self, match: Unused, context, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... def eof(self, context): ... - def indent(self, match: Unused, context, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... + def indent(self, match: Unused, context, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... def underline( - self, match: Match[Any], context: Sequence[str], next_state: _NextState - ) -> tuple[list[Any], _NextState, list[Any]]: ... - def text(self, match: Unused, context, next_state: _NextState) -> tuple[list[Any], _NextState, list[Any]]: ... + self, match: Match[str], context: Sequence[str], next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... + def text(self, match: Unused, context, next_state: _NextState) -> tuple[EmptyList, _NextState, EmptyList]: ... def literal_block(self) -> list[nodes.Node]: ... def quoted_literal_block(self) -> list[nodes.Node]: ... def definition_list_item(self, termline: StringList) -> tuple[nodes.definition_list_item, bool]: ... @@ -377,24 +379,24 @@ class SpecializedText(Text): text = invalid_input class Definition(SpecializedText): - def eof(self, context: Unused) -> list[Any]: ... + def eof(self, context: Unused) -> EmptyList: ... def indent( # type: ignore[override] self, match: Unused, context: list[str], next_state: Unused ) -> tuple[list[str], Literal["DefinitionList"], list[str]]: ... class Line(SpecializedText): eofcheck: Literal[1] - def eof(self, context: Any) -> list[Any]: ... - def blank(self, match: Unused, context: Any, next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def text(self, match: Match[str], context: list[str], next_state: Unused) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + def eof(self, context: Any) -> EmptyList: ... + def blank(self, match: Unused, context: Any, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] + def text(self, match: Match[str], context: list[str], next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] def indent( self, match: Match[str], context: list[str], next_state: Unused - ) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] + ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] def underline( self, match: Unused, context: list[str], next_state: Unused - ) -> tuple[list[Any], Literal["Body"], list[Any]]: ... # type: ignore[override] - def short_overline(self, context: list[Any], blocktext: Unused, lineno: int | None, lines: int = 1) -> None: ... - def state_correction(self, context: list[Any], lines: int = 1) -> Never: ... + ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] + def short_overline(self, context, blocktext: Unused, lineno: int | None, lines: int = 1) -> None: ... + def state_correction(self, context, lines: int = 1) -> Never: ... class QuotedLiteralBlock(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] @@ -404,15 +406,15 @@ class QuotedLiteralBlock(RSTState): @overload def blank( self, match: Unused, context: _EmptyContext, next_state: _NextState - ) -> tuple[_EmptyContext, _NextState, list[Any]]: ... + ) -> tuple[_EmptyContext, _NextState, EmptyList]: ... @overload def blank(self, match: Unused, context: Any, next_state: _NextState) -> Never: ... def eof(self, context: list[str]): ... def indent(self, match: Unused, context: list[str], next_state: Unused) -> Never: ... def initial_quoted( self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[list[str], _NextState, list[Any]]: ... - def quoted(self, match: Match[str], context: _Context, next_state: _NextState) -> tuple[_Context, _NextState, list[Any]]: ... + ) -> tuple[list[str], _NextState, EmptyList]: ... + def quoted(self, match: Match[str], context: _Context, next_state: _NextState) -> tuple[_Context, _NextState, EmptyList]: ... def text(self, match: Unused, context: Any, next_state: Unused) -> Never: ... state_classes: tuple[type[RSTState], ...] From 7f6e1abd315009b3b7fc6fcbde42137619a41db1 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:36:14 +0100 Subject: [PATCH 12/16] Mark several more parameters as Unused --- stubs/docutils/docutils/parsers/rst/states.pyi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 18edbbfe775b..738795bb4c2a 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -263,10 +263,10 @@ class Body(RSTState): def explicit_markup(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, list[Incomplete]]: ... def explicit_construct(self, match: Match[str]) -> tuple[list[Incomplete], bool]: ... def explicit_list(self, blank_finish) -> None: ... - def anonymous(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... + def anonymous(self, match: Match[str], context: Unused, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... def anonymous_target(self, match: Match[str]) -> tuple[list[nodes.target], bool]: ... - def line(self, match: Match[str], context, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... - def text(self, match: Match[str], context, next_state: str) -> tuple[list[str], Literal["Text"], EmptyList]: ... + def line(self, match: Match[str], context: Unused, next_state: str) -> tuple[list[Incomplete], str, EmptyList]: ... + def text(self, match: Match[str], context: Unused, next_state: Unused) -> tuple[list[str], Literal["Text"], EmptyList]: ... class RFC2822Body(Body): patterns: ClassVar[dict[str, str | Pattern[str]]] From 5cb1be6d4aea57163a0f87d40e483e6164603971 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:39:47 +0100 Subject: [PATCH 13/16] Add TypeAlias to EmptyList --- stubs/docutils/docutils/parsers/rst/states.pyi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 738795bb4c2a..6188c4bc7f99 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -19,7 +19,7 @@ _NextState = TypeVar("_NextState", str, None) _EmptyContext = TypeVar("_EmptyContext", Literal[""], None) _TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] -EmptyList = list[object] +EmptyList: TypeAlias = list[object] class MarkupError(DataError): ... class UnknownInterpretedRoleError(DataError): ... From 653c6ec4e6da746efada9ed210f6fd5805ca1a5c Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:44:22 +0100 Subject: [PATCH 14/16] Fix MyPy errors --- .../docutils/docutils/parsers/rst/states.pyi | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 6188c4bc7f99..aab9af89e413 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -294,17 +294,17 @@ class BulletList(SpecializedBody): def bullet(self, match: Match[str], context: Unused, next_state: _NextState) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] class DefinitionList(SpecializedBody): - def text( + def text( # type: ignore[override] self, match: Match[str], context: Unused, next_state: Unused - ) -> tuple[list[str], Literal["Definition"], EmptyList]: ... # type: ignore[override] + ) -> tuple[list[str], Literal["Definition"], EmptyList]: ... class EnumeratedList(SpecializedBody): auto: int blank_finish: Incomplete lastordinal: Incomplete - def enumerator( + def enumerator( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] + ) -> tuple[EmptyList, _NextState, EmptyList]: ... class FieldList(SpecializedBody): blank_finish: Incomplete @@ -333,18 +333,18 @@ class ExtensionOptions(FieldList): class LineBlock(SpecializedBody): blank_finish: Incomplete def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... - def line_block( + def line_block( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] + ) -> tuple[EmptyList, _NextState, EmptyList]: ... class Explicit(SpecializedBody): blank_finish: Incomplete def explicit_markup( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState ) -> tuple[EmptyList, _NextState, EmptyList]: ... - def anonymous( + def anonymous( # type: ignore[override] self, match: Match[str], context: Unused, next_state: _NextState - ) -> tuple[EmptyList, _NextState, EmptyList]: ... # type: ignore[override] + ) -> tuple[EmptyList, _NextState, EmptyList]: ... def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... class SubstitutionDef(Body): @@ -357,9 +357,9 @@ class SubstitutionDef(Body): class Text(RSTState): patterns: ClassVar[dict[str, str | Pattern[str]]] initial_transitions: ClassVar[list[tuple[str, str]]] - def blank(self, match: Unused, context, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... + def blank(self, match: Unused, context, next_state: Unused) -> tuple[list[str], Literal["Body"], list[str]]: ... def eof(self, context): ... - def indent(self, match: Unused, context, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... + def indent(self, match: Unused, context, next_state: Unused) -> tuple[list[str], Literal["Body"], list[str]]: ... def underline( self, match: Match[str], context: Sequence[str], next_state: _NextState ) -> tuple[EmptyList, _NextState, EmptyList]: ... @@ -379,22 +379,22 @@ class SpecializedText(Text): text = invalid_input class Definition(SpecializedText): - def eof(self, context: Unused) -> EmptyList: ... + def eof(self, context: Unused) -> list[str]: ... def indent( # type: ignore[override] self, match: Unused, context: list[str], next_state: Unused ) -> tuple[list[str], Literal["DefinitionList"], list[str]]: ... class Line(SpecializedText): eofcheck: Literal[1] - def eof(self, context: Any) -> EmptyList: ... + def eof(self, context: Any) -> list[str]: ... def blank(self, match: Unused, context: Any, next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] def text(self, match: Match[str], context: list[str], next_state: Unused) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] - def indent( + def indent( # type: ignore[override] self, match: Match[str], context: list[str], next_state: Unused - ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] - def underline( + ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... + def underline( # type: ignore[override] self, match: Unused, context: list[str], next_state: Unused - ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... # type: ignore[override] + ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... def short_overline(self, context, blocktext: Unused, lineno: int | None, lines: int = 1) -> None: ... def state_correction(self, context, lines: int = 1) -> Never: ... From 54bb73f13c04477e03f5dae7d97752de7801c878 Mon Sep 17 00:00:00 2001 From: Harry Lees Date: Tue, 3 Jun 2025 22:50:21 +0100 Subject: [PATCH 15/16] Fix `double_width_pad_char` type --- stubs/docutils/docutils/parsers/rst/states.pyi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index aab9af89e413..90574464a80b 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -187,7 +187,7 @@ class Inliner: dispatch: dict[str, Callable[[Match[str], int], tuple[str, list[nodes.problematic], str, list[nodes.system_message]]]] = ... class Body(RSTState): - double_width_pad_char: TableParser + double_width_pad_char: str enum: Struct grid_table_top_pat: Pattern[str] simple_table_top_pat: Pattern[str] From 70be95271bc9c71fca72f2eec9c7d525af6b4f5b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 3 Jun 2025 21:52:13 +0000 Subject: [PATCH 16/16] [pre-commit.ci] auto fixes from pre-commit.com hooks --- stubs/docutils/docutils/parsers/rst/states.pyi | 1 - 1 file changed, 1 deletion(-) diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 90574464a80b..2b3268f263aa 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -8,7 +8,6 @@ from typing_extensions import Never, TypeAlias from docutils import ApplicationError, DataError, nodes from docutils.parsers.rst import Directive from docutils.parsers.rst.languages import _RstLanguageModule -from docutils.parsers.rst.tableparser import TableParser from docutils.statemachine import StateMachine, StateMachineWS, StateWS, StringList from docutils.utils import Reporter