diff --git a/stubs/docutils/docutils/parsers/rst/states.pyi b/stubs/docutils/docutils/parsers/rst/states.pyi index 8e657cd3cdad..2b3268f263aa 100644 --- a/stubs/docutils/docutils/parsers/rst/states.pyi +++ b/stubs/docutils/docutils/parsers/rst/states.pyi @@ -1,17 +1,25 @@ -from _typeshed import Incomplete -from collections.abc import Callable, Iterable, Sequence +from _typeshed import Incomplete, Unused +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_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.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) +_TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]] + +EmptyList: TypeAlias = list[object] + class MarkupError(DataError): ... class UnknownInterpretedRoleError(DataError): ... class InterpretedRoleNotImplementedError(DataError): ... @@ -45,12 +53,13 @@ class NestedStateMachine(StateMachineWS[list[str]]): language: Incomplete node: Incomplete def run( # type: ignore[override] - self, input_lines: Sequence[str] | StringList, input_offset: int, memo, node, match_titles: bool = True + self, input_lines: Sequence[str] | StringList, input_offset: int, memo, 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]] # 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: ... memo: Incomplete reporter: Reporter @@ -91,7 +100,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,84 +186,96 @@ 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 + double_width_pad_char: str + 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, ...]] - 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 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( + 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: 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: 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]: ... + 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, 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 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: ... + 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]: ... + 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: 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): ... + 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: 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]]] 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): ... + 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): - 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] + def invalid_input(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... + indent = invalid_input bullet = invalid_input enumerator = invalid_input field_marker = invalid_input @@ -264,130 +285,135 @@ class SpecializedBody(Body): grid_table_top = invalid_input simple_table_top = invalid_input explicit_markup = invalid_input - anonymous = invalid_input # type: ignore[assignment] + anonymous = invalid_input 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]]: ... + 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: list[str] | None, next_state: str | None) -> tuple[list[str], str, list[str]]: ... # type: ignore[override] + def text( # type: ignore[override] + self, match: Match[str], context: Unused, next_state: Unused + ) -> tuple[list[str], Literal["Definition"], EmptyList]: ... 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]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... 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]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... 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]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... class RFC2822List(SpecializedBody, RFC2822Body): patterns: ClassVar[dict[str, str | Pattern[str]]] - initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] # type: ignore[assignment] + initial_transitions: ClassVar[list[tuple[str | tuple[str, str], str]]] blank_finish: Incomplete - def rfc2822(self, match, context, next_state): ... - blank: Incomplete + def rfc2822( # type: ignore[override] + self, match: Match[str], context: Unused, next_state: Unused + ) -> tuple[EmptyList, Literal["RFC2822List"], EmptyList]: ... + def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... class ExtensionOptions(FieldList): - def parse_field_body(self, indented, offset, node) -> None: ... + def parse_field_body(self, indented: StringList, offset, node: nodes.Node) -> None: ... class LineBlock(SpecializedBody): - blank: Incomplete blank_finish: Incomplete + def blank(self, match: Unused = None, context: Unused = None, next_state: Unused = None) -> Never: ... 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]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... 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]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... def anonymous( # type: ignore[override] - self, match: Match[str], context: list[str] | None, next_state: str | None - ) -> tuple[list[str], str | None, list[str]]: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> tuple[EmptyList, _NextState, EmptyList]: ... + 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, context, next_state) -> None: ... - def text(self, match, context, next_state) -> None: ... + 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, context, next_state): ... + def blank(self, match: Unused, context, next_state: Unused) -> tuple[list[str], Literal["Body"], list[str]]: ... def eof(self, context): ... - def indent(self, match, context, next_state): ... - def underline(self, match, context, next_state): ... - def text(self, match, context, next_state): ... - def literal_block(self): ... - def quoted_literal_block(self): ... - def definition_list_item(self, termline): ... - classifier_delimiter: Incomplete - def term(self, lines, lineno): ... + def 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]: ... + 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]: ... + classifier_delimiter: Pattern[str] + def term(self, lines: StringList, lineno: int) -> tuple[nodes.Node, nodes.system_message]: ... 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: ... + 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 underline = invalid_input text = invalid_input class Definition(SpecializedText): - def eof(self, context): ... - blank_finish: Incomplete + def eof(self, context: Unused) -> list[str]: ... def indent( # type: ignore[override] - self, match: Match[str] | None, context: list[str], next_state: str | None - ) -> tuple[list[str], str, list[str]]: ... + self, match: Unused, context: list[str], next_state: Unused + ) -> tuple[list[str], Literal["DefinitionList"], 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] + eofcheck: Literal[1] + 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( # type: ignore[override] + self, match: Match[str], context: list[str], next_state: Unused + ) -> tuple[EmptyList, Literal["Body"], EmptyList]: ... 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: ... + self, match: Unused, context: list[str], next_state: Unused + ) -> 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: ... 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: ... + messages: list[Incomplete] + initial_lineno: int | 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, 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: 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: ... + self, match: Match[str], context: Unused, next_state: _NextState + ) -> 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], ...]