[docutils] Impove main stubs

[donbarbos]

No description provided.

[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/docfields.py: note: In member "_transform_step_1" of class "DocFieldTransformer":
+ sphinx/util/docfields.py:461:41: error: Incompatible types in assignment (expression has type "document | Any | None", variable has type "document")  [assignment]
+ sphinx/util/docutils.py: note: In member "write" of class "SphinxFileOutput":
+ sphinx/util/docutils.py:469:16: error: Call to untyped function "write" in typed context  [no-untyped-call]
+ sphinx/util/docutils.py: note: At top level:
+ sphinx/util/docutils.py:914: error: Unused "type: ignore" comment  [unused-ignore]
+ sphinx/util/docutils.py: note: In function "_get_settings":
+ sphinx/util/docutils.py:914:12: error: Call to untyped function "get_default_values" in typed context  [no-untyped-call]
+ sphinx/util/docutils.py:914:12: note: Error code "no-untyped-call" not covered by "type: ignore" comment
+ sphinx/ext/inheritance_diagram.py: note: In member "run" of class "InheritanceDiagram":
+ sphinx/ext/inheritance_diagram.py:432:21: error: Item "None" of "document | None" has no attribute "reporter"  [union-attr]

[felixfontein]

The types for source_path and destination_path are wrong. I think this is a misunderstanding with the docstring of source_path in publish_programmatically(): while that one lists FileInput and StringInput, it does so to say which types are expected if source_class is one of these two types. It does not say that source_path is one of these two types. set_source is passed on to Publisher.set_source(), which has type source_path: StrPath | None. So the correct type should be StrPath | None, not FileInput | StringInput | None.

The same is true for destination_path, and the parameters of the same name for all other publish_* functions.

[donbarbos]

big thanks to you, I noticed that source_path is passed to the open builtin function which takes FileDescriptorOrPath, so maybe that would be a more appropriate type?

[felixfontein]

I would stick to the types that docutils itself (indirectly, through Publisher.set_source()/Publisher.set_destination()) specifies.