[docutils] Improve types in docutils.io

[ekanshul]

Several attributes and parameters of the docutils.io input/output classes were Incomplete or unannotated although docutils annotates them inline. This types the encoding, error_handler, destination_path and autoclose attributes of Output/FileOutput, the ErrorOutput attributes, the path/encoding/mode parameters of the FileInput and FileOutput constructors, and the read()/write() methods of StringInput, StringOutput and FileOutput, following the annotations in docutils 0.23.

Agent used: Claude Code

[JelleZijlstra]

Are the mypy-primer hits in Sphinx expected?

[JelleZijlstra]

Shouldn't this be SupportsWrite[str] | SupportsWrite[bytes] | Literal[False] to mirror the constructor parameter?

[ekanshul]

Done in 4cec7a9, and dropped the now unused BinaryIO import.

[ekanshul]

Yes, they're expected. docutils 0.23 annotates FileOutput.write(self, data: str | bytes) -> str | bytes (and Output.write/StringOutput.write the same way), which is what this PR copies. SphinxFileOutput.write(self, data: str) -> str in sphinx/util/docutils.py narrows the parameter, so the override error is a true positive by docutils' own annotations, and the unused type: ignore[no-untyped-call] is the super().write(data) call becoming typed. Both look like things to adjust on the Sphinx side (widen the override, drop the ignore) rather than something to avoid here.

[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 member "write" of class "SphinxFileOutput":
+ sphinx/util/docutils.py:457:21: error: Argument 1 of "write" is incompatible with supertype "docutils.io.FileOutput"; supertype defines the argument type as "str | bytes"  [override]
+ sphinx/util/docutils.py:457:21: note: This violates the Liskov substitution principle
+ sphinx/util/docutils.py:457:21: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides
+ sphinx/util/docutils.py: note: At top level:
+ sphinx/util/docutils.py:473: error: Unused "type: ignore" comment  [unused-ignore]
+ sphinx/util/docutils.py: note: In member "write" of class "SphinxFileOutput":
+ sphinx/util/docutils.py:473:16: error: Incompatible return value type (got "str | bytes", expected "str")  [return-value]
+ sphinx/util/docutils.py:473:16: note: Error code "return-value" not covered by "type: ignore[no-untyped-call]" comment