improve type annotations in 'docutils.statemachine'

[danieleades]

adds type annotations for docutils.statemachine.

I'm not super confident about the use of the generic _Context for the state machine since the only code examples I can find using this class are in the sphinx repo, and there no context is used (ever).

[danieleades]

@srittau I could really use your eyes on this one! I think i've made good progress, but could use some assistance to get this over the line, if you have the time

[JelleZijlstra]

i tried to simplify some of these type signatures using type aliases, but couldn't get this to work

_Context = TypeVar("_Context")
_TransitionResult: TypeAlias = tuple[_Context, str | None, list[str]]
_TransitionMethod: TypeAlias = Callable[[Match[str], _Context, str], _TransitionResult[_Context]]

mypy and pyright complain about the generics being unbound

That looks right, but you should use the alias as _TransitionResult[_Context] in this case.

[JelleZijlstra]

stubs/docutils/docutils/statemachine.pyi:3: error: Module "typing" has no attribute "TypeAlias"  [attr-defined]
stubs/docutils/docutils/statemachine.pyi:3: note: Use `from typing_extensions import TypeAlias` instead

This probably has something to do with the other errors.

[danieleades]

@JelleZijlstra anything else needed to get this one merged? (it's blocking a couple of other PRs)

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
+ sphinx/util/docutils.py: note: In function "switch_source_input":
+ sphinx/util/docutils.py:386:25: error: Need type annotation for "state_machine"  [var-annotated]
+ sphinx/util/docutils.py:386:25: note: Error code "var-annotated" not covered by "type: ignore" comment
- sphinx/util/docutils.py: note: At top level:
- sphinx/util/docutils.py:383: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:386: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:388: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:393: error: Unused "type: ignore" comment  [unused-ignore]
+ sphinx/util/rst.py: note: In function "append_epilog":
+ sphinx/util/rst.py:109:36: error: Unsupported operand types for + ("None" and "int")  [operator]
+ sphinx/util/rst.py:109:36: note: Left operand is of type "Optional[int]"
- sphinx/parsers.py:64: error: Unused "type: ignore" comment  [unused-ignore]

[srittau]

I spotted one thing. But looks good to go apart from that.

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
+ sphinx/util/docutils.py: note: In function "switch_source_input":
+ sphinx/util/docutils.py:386:25: error: Need type annotation for "state_machine"  [var-annotated]
+ sphinx/util/docutils.py:386:25: note: Error code "var-annotated" not covered by "type: ignore" comment
- sphinx/util/docutils.py: note: At top level:
- sphinx/util/docutils.py:383: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:386: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:388: error: Unused "type: ignore" comment  [unused-ignore]
- sphinx/util/docutils.py:393: error: Unused "type: ignore" comment  [unused-ignore]
+ sphinx/util/rst.py: note: In function "append_epilog":
+ sphinx/util/rst.py:109:36: error: Unsupported operand types for + ("None" and "int")  [operator]
+ sphinx/util/rst.py:109:36: note: Left operand is of type "Optional[int]"
- sphinx/parsers.py:64: error: Unused "type: ignore" comment  [unused-ignore]