Skip to content

[docutils] Impove main stubs #14107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
Jul 7, 2025
Merged

[docutils] Impove main stubs #14107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
25ae6d3
draft: impove `docutils`
donBarbos May 17, 2025
650cef0
fix more
donBarbos May 18, 2025
0f2bceb
Add more writers
donBarbos May 21, 2025
9bd977a
Update parsers
donBarbos May 21, 2025
3aaedb2
Update readers
donBarbos May 22, 2025
c9becf4
Improve utils
donBarbos May 22, 2025
c4cd6c1
Merge branch 'main' into improve-docutils
donBarbos May 22, 2025
d611093
Draft: reset to preves commit
donBarbos May 22, 2025
d08322d
Merge remote-tracking branch 'origin/main' into improve-docutils
donBarbos May 22, 2025
34a8211
Revert adding my files
donBarbos May 22, 2025
afab428
Merge branch 'main' into improve-docutils
donBarbos Jun 7, 2025
d45624d
Correct core changes
donBarbos Jun 7, 2025
cb7a2dd
Remove new dirs for writers
donBarbos Jun 7, 2025
ace1914
Remove `transforms` changes
donBarbos Jun 8, 2025
50b9f51
Revert few changes
donBarbos Jun 8, 2025
a6a1fce
Update
donBarbos Jun 8, 2025
9b6e8ac
Merge branch 'main' into improve-docutils
srittau Jul 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions stubs/docutils/@tests/stubtest_allowlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,3 @@
docutils.frontend.ConfigParser.__getattr__
docutils.frontend.ConfigParser.read
docutils.frontend.OptionParser.__getattr__
docutils.io.FileOutput.__getattr__
docutils.io.FileOutput.__init__
docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__
docutils.nodes.Element.tagname # class variable is overridden in __init__ method
docutils.nodes.NodeVisitor.depart_\w+ # Methods are discovered dynamically on commonly-used subclasses
Expand Down
10 changes: 5 additions & 5 deletions stubs/docutils/docutils/__init__.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
from typing import Any, ClassVar, NamedTuple
from typing import Any, ClassVar, Final, NamedTuple
from typing_extensions import Self

from docutils.transforms import Transform

__docformat__: str
__version__: str
__docformat__: Final = "reStructuredText"
__version__: Final[str]

class _VersionInfo(NamedTuple):
major: int
Expand All @@ -19,8 +19,8 @@ class VersionInfo(_VersionInfo):
cls, major: int = 0, minor: int = 0, micro: int = 0, releaselevel: str = "final", serial: int = 0, release: bool = True
) -> Self: ...

__version_info__: VersionInfo
__version_details__: str
__version_info__: Final[VersionInfo]
__version_details__: Final[str]

class ApplicationError(Exception): ...
class DataError(ApplicationError): ...
Expand Down
149 changes: 85 additions & 64 deletions stubs/docutils/docutils/core.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,50 @@
from _typeshed import Incomplete
from typing import Final
from typing_extensions import deprecated

from docutils import SettingsSpec
from docutils.writers import _WriterParts
from docutils.frontend import OptionParser
from docutils.io import FileInput, Input, Output, StringInput
from docutils.parsers import Parser
from docutils.readers import Reader
from docutils.utils import SystemMessage
from docutils.writers import Writer, _WriterParts

__docformat__: str
__docformat__: Final = "reStructuredText"

class Publisher:
document: Incomplete
reader: Incomplete
parser: Incomplete
writer: Incomplete
source: Incomplete
document: Incomplete | None
reader: Reader[Incomplete]
parser: Parser
writer: Writer[Incomplete]
source: Input[Incomplete]
source_class: Incomplete
destination: Incomplete
destination: Output | None
destination_class: Incomplete
settings: Incomplete
settings: dict[str, Incomplete]
def __init__(
self,
reader=None,
parser=None,
writer=None,
source=None,
reader: Reader[Incomplete] | None = None,
parser: Parser | None = None,
writer: Writer[Incomplete] | None = None,
source: Input[Incomplete] | None = None,
source_class=...,
destination=None,
destination: Output | None = None,
destination_class=...,
settings=None,
settings: dict[str, Incomplete] | None = None,
) -> None: ...
def set_reader(self, reader_name, parser, parser_name) -> None: ...
def set_writer(self, writer_name) -> None: ...
def set_components(self, reader_name, parser_name, writer_name) -> None: ...
def setup_option_parser(self, usage=None, description=None, settings_spec=None, config_section=None, **defaults): ...
def set_reader(self, reader_name: str, parser: Parser | None, parser_name: str | None) -> None: ...
def set_writer(self, writer_name: str) -> None: ...
def set_components(self, reader_name: str, parser_name: str, writer_name: str) -> None: ...
@deprecated("Publisher.setup_option_parser is deprecated, and will be removed in Docutils 0.21.")
def setup_option_parser(
self,
usage: str | None = None,
description: str | None = None,
settings_spec: SettingsSpec | None = None,
config_section: str | None = None,
**defaults,
) -> OptionParser: ...
def get_settings(
self,
usage: str | None = None,
Expand All @@ -40,52 +55,58 @@ class Publisher:
): ...
def process_programmatic_settings(self, settings_spec, settings_overrides, config_section) -> None: ...
def process_command_line(
self, argv=None, usage=None, description=None, settings_spec=None, config_section=None, **defaults
self,
argv: list[str] | None = None,
usage=None,
description: str | None = None,
settings_spec=None,
config_section=None,
**defaults,
) -> None: ...
def set_io(self, source_path=None, destination_path=None) -> None: ...
def set_source(self, source=None, source_path=None) -> None: ...
def set_destination(self, destination=None, destination_path=None) -> None: ...
def apply_transforms(self) -> None: ...
def publish(
self,
argv=None,
usage=None,
description=None,
argv: list[str] | None = None,
usage: str | None = None,
description: str | None = None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = False,
): ...
def debugging_dumps(self) -> None: ...
def prompt(self) -> None: ...
def report_Exception(self, error) -> None: ...
def report_SystemMessage(self, error) -> None: ...
def report_UnicodeError(self, error) -> None: ...
def report_Exception(self, error: BaseException) -> None: ...
def report_SystemMessage(self, error: SystemMessage) -> None: ...
def report_UnicodeError(self, error: UnicodeEncodeError) -> None: ...

default_usage: str
default_description: str
default_usage: Final[str]
default_description: Final[str]

def publish_cmdline(
reader=None,
reader: Reader[Incomplete] | None = None,
reader_name: str = "standalone",
parser=None,
parser: Parser | None = None,
parser_name: str = "restructuredtext",
writer=None,
writer: Writer[Incomplete] | None = None,
writer_name: str = "pseudoxml",
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = True,
argv=None,
usage=...,
description=...,
argv: list[str] | None = None,
usage: str = ...,
description: str = ...,
): ...
def publish_file(
source=None,
source_path=None,
source_path: FileInput | StringInput | None = None,
destination=None,
destination_path=None,
destination_path: FileInput | StringInput | None = None,
reader=None,
reader_name: str = "standalone",
parser=None,
Expand All @@ -95,13 +116,13 @@ def publish_file(
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = False,
): ...
def publish_string(
source,
source_path=None,
destination_path=None,
source_path: FileInput | StringInput | None = None,
destination_path: FileInput | StringInput | None = None,
reader=None,
reader_name: str = "standalone",
parser=None,
Expand All @@ -111,14 +132,14 @@ def publish_string(
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = False,
): ...
def publish_parts(
source,
source_path=None,
source_path: FileInput | StringInput | None = None,
Copy link

@felixfontein felixfontein Jul 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

source_class=...,
destination_path=None,
destination_path: FileInput | StringInput | None = None,
reader=None,
reader_name: str = "standalone",
parser=None,
Expand All @@ -127,13 +148,13 @@ def publish_parts(
writer_name: str = "pseudoxml",
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
settings_overrides: dict[str, Incomplete] | None = None,
config_section: str | None = None,
enable_exit_status: bool = False,
) -> _WriterParts: ...
def publish_doctree(
source,
source_path=None,
source_path: FileInput | StringInput | None = None,
source_class=...,
reader=None,
reader_name: str = "standalone",
Expand All @@ -142,18 +163,18 @@ def publish_doctree(
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = False,
): ...
def publish_from_doctree(
document,
destination_path=None,
destination_path: FileInput | StringInput | None = None,
writer=None,
writer_name: str = "pseudoxml",
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = False,
): ...
def publish_cmdline_to_binary(
Expand All @@ -166,34 +187,34 @@ def publish_cmdline_to_binary(
settings=None,
settings_spec=None,
settings_overrides=None,
config_section=None,
config_section: str | None = None,
enable_exit_status: bool = True,
argv=None,
usage=...,
description=...,
argv: list[str] | None = None,
usage: str = ...,
description: str = ...,
destination=None,
destination_class=...,
): ...
def publish_programmatically(
source_class,
source_class: type[FileInput],
source,
source_path,
source_path: FileInput | StringInput,
destination_class,
destination,
destination_path,
destination_path: FileInput | StringInput,
reader,
reader_name,
reader_name: str,
parser,
parser_name,
parser_name: str,
writer,
writer_name,
writer_name: str,
settings,
settings_spec,
settings_overrides,
config_section,
enable_exit_status,
): ...
def rst2something(writer, documenttype, doc_path: str = "") -> None: ...
config_section: str,
enable_exit_status: bool,
) -> tuple[str | bytes | None, Publisher]: ...
def rst2something(writer: str, documenttype: str, doc_path: str = "") -> None: ...
def rst2html() -> None: ...
def rst2html4() -> None: ...
def rst2html5() -> None: ...
Expand Down
47 changes: 46 additions & 1 deletion stubs/docutils/docutils/examples.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,46 @@
def __getattr__(name: str): ... # incomplete module
from _typeshed import Incomplete
from typing import Literal, overload
from typing_extensions import TypeAlias

from docutils.core import Publisher
from docutils.io import FileInput, StringInput
from docutils.nodes import document
from docutils.writers import _WriterParts

_HTMLHeaderLevel: TypeAlias = Literal[1, 2, 3, 4, 5, 6]

def html_parts(
input_string: str,
source_path=None,
destination_path=None,
input_encoding: str = "unicode",
doctitle: bool = True,
initial_header_level: _HTMLHeaderLevel = 1,
) -> _WriterParts: ...
@overload
def html_body(
input_string: str,
source_path=None,
destination_path=None,
input_encoding: str = "unicode",
output_encoding: Literal["unicode"] = "unicode",
doctitle: bool = True,
initial_header_level: _HTMLHeaderLevel = 1,
) -> str: ...
@overload
def html_body(
input_string: str,
source_path=None,
destination_path=None,
input_encoding: str = "unicode",
output_encoding: str = "unicode",
doctitle: bool = True,
initial_header_level: _HTMLHeaderLevel = 1,
) -> str | bytes: ...
def internals(
input_string,
source_path: FileInput | StringInput | None = None,
destination_path: FileInput | StringInput | None = None,
input_encoding: str = "unicode",
settings_overrides: dict[str, Incomplete] | None = None,
) -> tuple[document | None, Publisher]: ...
Loading