Skip to content

Conversation

@dependabot
Copy link
Contributor

@dependabot dependabot bot commented on behalf of github Jun 9, 2025

Bumps types-docutils from 0.21.0.20250525 to 0.21.0.20250604.

Commits

Dependabot compatibility score

You can trigger a rebase of this PR by commenting @dependabot rebase.


Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

  • @dependabot rebase will rebase this PR
  • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
  • @dependabot merge will merge this PR after your CI passes on it
  • @dependabot squash and merge will squash and merge this PR after your CI passes on it
  • @dependabot cancel merge will cancel a previously requested merge and block automerging
  • @dependabot reopen will reopen this PR if it is closed
  • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
  • @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
  • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
  • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
  • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

Note
Automatic rebases have been disabled on this pull request as it has been open for over 30 days.

@dependabot dependabot bot added dependencies Pull requests that update a dependency file python Pull requests that update Python code labels Jun 9, 2025
@AA-Turner
Copy link
Member

sphinx/util/docutils.py: note: In member "get_source_info" of class "SphinxDirective":
sphinx/util/docutils.py:488:16: error: Incompatible return value type (got "tuple[str, int] | tuple[None, None]", expected "tuple[str, int]")  [return-value]
sphinx/directives/__init__.py: note: In member "run" of class "DefaultRole":
sphinx/directives/__init__.py:332:24: error: Argument 2 to "role" has incompatible type "_RstLanguageModule"; expected "_LanguageModule"  [arg-type]
tests/test_util/test_util_docutils_sphinx_directive.py: note: In function "make_directive_and_state":
tests/test_util/test_util_docutils_sphinx_directive.py:29:19: error: Incompatible types in assignment (expression has type "object", variable has type "Reporter")  [assignment]
tests/test_util/test_util_docutils_sphinx_directive.py:60:23: error: Argument "state_machine" to "SphinxDirective" has incompatible type "StateMachine[list[str]]"; expected "RSTStateMachine"  [arg-type]
sphinx/directives/patches.py:33: error: Unused "type: ignore" comment  [unused-ignore]
sphinx/directives/patches.py: note: In member "run" of class "Figure":
sphinx/directives/patches.py:42:20: error: Incompatible return value type (got "Sequence[Node]", expected "list[Node]")  [return-value]
sphinx/directives/patches.py: note: At top level:
sphinx/directives/patches.py:59: error: Unused "type: ignore" comment  [unused-ignore]
sphinx/directives/patches.py: note: In member "run" of class "CSVTable":
sphinx/directives/patches.py:82:16: error: Call to untyped function "run" in typed context  [no-untyped-call]
sphinx/directives/other.py: note: In member "run" of class "Include":
sphinx/directives/other.py:409:13: error: Cannot assign to a method  [method-assign]
sphinx/directives/other.py:409:47: error: Incompatible types in assignment (expression has type "Callable[[list[str], str], None]", variable has type "Callable[[list[str] | StringList, str], None]")  [assignment]
sphinx/directives/code.py: note: In member "run" of class "CodeBlock":
sphinx/directives/code.py:146:74: error: Argument "location" to "dedent_lines" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
sphinx/directives/code.py: note: In member "run" of class "LiteralInclude":
sphinx/directives/code.py:462:48: error: Argument "location" to "read" of "LiteralIncludeReader" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
Found 12 errors in 6 files (checked 399 source files)

Bumps [types-docutils](https://github.com/typeshed-internal/stub_uploader) from 0.21.0.20250525 to 0.21.0.20250604.
- [Commits](https://github.com/typeshed-internal/stub_uploader/commits)

---
updated-dependencies:
- dependency-name: types-docutils
  dependency-version: 0.21.0.20250604
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <[email protected]>
@dependabot dependabot bot force-pushed the dependabot/pip/types-docutils-0.21.0.20250604 branch from 4956361 to 746e956 Compare June 11, 2025 15:01
@adamtheturtle
Copy link
Contributor

I've resolved a few issues here but I'm happy if someone else wants to make further progress.

@dependabot @github
Copy link
Contributor Author

dependabot bot commented on behalf of github Jul 8, 2025

A newer version of types-docutils exists, but since this PR has been edited by someone other than Dependabot I haven't updated it. You'll get a PR for the updated version as normal once this PR is merged.

@adamtheturtle
Copy link
Contributor

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/transforms/__init__.py: note: In member "apply" of class "ExtraTranslatableNodes":
sphinx/transforms/__init__.py:284:13: error: Unsupported target for indexed assignment ("Node")  [index]
sphinx/transforms/__init__.py: note: In member "apply" of class "SphinxSmartQuotes":
sphinx/transforms/__init__.py:373:9: error: Cannot assign to class variable "smartquotes_action" via instance  [misc]
sphinx/transforms/__init__.py: note: In member "get_tokens" of class "SphinxSmartQuotes":
sphinx/transforms/__init__.py:400:9: error: Argument 1 of "get_tokens" is incompatible with supertype "docutils.transforms.universal.SmartQuotes"; supertype defines the argument type as "Iterable[Node]"  [override]
sphinx/transforms/__init__.py:400:9: note: This violates the Liskov substitution principle
sphinx/transforms/__init__.py:400:9: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides
sphinx/transforms/__init__.py:401: error: Bracketed expression "[...]" is not valid as a type  [valid-type]
sphinx/transforms/__init__.py:401: note: Did you mean "List[...]"?
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: In member "get_source_info" of class "SphinxDirective":
sphinx/util/docutils.py:504:16: error: Incompatible return value type (got "tuple[str, int] | tuple[None, None]", expected "tuple[str, int]")  [return-value]
sphinx/directives/__init__.py: note: In member "run" of class "DefaultRole":
sphinx/directives/__init__.py:332:24: error: Argument 2 to "role" has incompatible type "_RstLanguageModule"; expected "_LanguageModule"  [arg-type]
sphinx/writers/html5.py: note: In member "visit_reference" of class "HTML5Translator":
sphinx/writers/html5.py:350:57: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
sphinx/writers/html5.py: note: In member "visit_comment" of class "HTML5Translator":
sphinx/writers/html5.py:364:5: error: Signature of "visit_comment" incompatible with supertype "docutils.writers._html_base.HTMLTranslator"  [override]
sphinx/writers/html5.py:364:5: note:      Superclass:
sphinx/writers/html5.py:364:5: note:          def visit_comment(self, node: comment, sub: Callable[[str, str], str] = ...) -> None
sphinx/writers/html5.py:364:5: note:      Subclass:
sphinx/writers/html5.py:364:5: note:          def visit_comment(self, node: Element) -> None
sphinx/writers/html5.py: note: In member "visit_admonition" of class "HTML5Translator":
sphinx/writers/html5.py:376:73: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
sphinx/writers/html5.py: note: In member "visit_download_reference" of class "HTML5Translator":
sphinx/writers/html5.py:727:61: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
sphinx/writers/html5.py:734:61: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
sphinx/writers/html5.py: note: In member "visit_abbreviation" of class "HTML5Translator":
sphinx/writers/html5.py:911:60: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
sphinx/writers/html5.py: note: In member "visit_table" of class "HTML5Translator":
sphinx/writers/html5.py:936:71: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]
tests/test_util/test_util_docutils_sphinx_directive.py: note: In function "make_directive_and_state":
tests/test_util/test_util_docutils_sphinx_directive.py:61:23: error: Argument "state_machine" to "SphinxDirective" has incompatible type "StateMachine[list[str]]"; expected "RSTStateMachine"  [arg-type]
sphinx/io.py:35:24: error: Missing type parameters for generic type "Reader"  [type-arg]
sphinx/writers/xml.py: note: In member "translate" of class "XMLWriter":
sphinx/writers/xml.py:33:9: error: Incompatible types in assignment (expression has type "NodeVisitor", variable has type "XMLTranslator")  [assignment]
sphinx/directives/patches.py: note: In member "run" of class "CSVTable":
sphinx/directives/patches.py:83:16: error: Call to untyped function "run" in typed context  [no-untyped-call]
sphinx/directives/other.py: note: In member "run" of class "Include":
sphinx/directives/other.py:408:13: error: Cannot assign to a method  [method-assign]
sphinx/directives/other.py:408:47: error: Incompatible types in assignment (expression has type "Callable[[list[str], str], None]", variable has type "Callable[[list[str] | StringList, str], None]")  [assignment]
sphinx/directives/code.py: note: In member "run" of class "CodeBlock":
sphinx/directives/code.py:146:74: error: Argument "location" to "dedent_lines" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
sphinx/directives/code.py: note: In member "run" of class "LiteralInclude":
sphinx/directives/code.py:462:48: error: Argument "location" to "read" of "LiteralIncludeReader" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
sphinx/builders/xml.py: note: In member "_translate" of class "XMLBuilder":
sphinx/builders/xml.py:90:34: error: Incompatible types in assignment (expression has type "NodeVisitor", variable has type "XMLTranslator")  [assignment]
sphinx/transforms/i18n.py: note: In member "apply" of class "PreserveTranslatableMessages":
sphinx/transforms/i18n.py:112:43: error: Only concrete class can be given where "type[translatable]" is expected  [type-abstract]
sphinx/builders/linkcheck.py: note: In member "run" of class "HyperlinkCollector":
sphinx/builders/linkcheck.py:216:37: error: Argument 1 to "find_uri" of "HyperlinkCollector" has incompatible type "Node"; expected "Element"  [arg-type]
sphinx/builders/linkcheck.py:217:36: error: Argument 2 to "_add_uri" of "HyperlinkCollector" has incompatible type "Node"; expected "Element"  [arg-type]
Found 27 errors in 14 files (checked 403 source files)

It looks like:

sphinx/writers/html5.py:376:73: error: Argument 4 to "starttag" of "HTMLTranslator" has incompatible type "**dict[str, str]"; expected "bool"  [arg-type]

and similar may be legitimate bugs. I plan to investigate.

@danieleades
Copy link
Contributor

that's all the mypy issues 'resolved' but a few are a little hacky, and some others will require upstream changes to resolve. Please review carefully. Very open to suggestions.

Haven't looked at the pyright issues yet. some deprecation warnings for older docutils interfaces. at what point do we want to bite the bullet and drop support for older docutils and remove the shims?

@AA-Turner
Copy link
Member

AA-Turner commented Dec 1, 2025

at what point do we want to bite the bullet and drop support for older docutils and remove the shims?

Sphinx 9.1 will drop support for Docutils 0.20 (see #12555 for previous bump).

A

@danieleades
Copy link
Contributor

at what point do we want to bite the bullet and drop support for older docutils and remove the shims?

Sphinx 9.1 will drop support for Docutils 0.20 (see #12555 for previous bump).

A

i take it we'll need proper solutions for all those deprecation warnings before that happens?

some of these warnings are from the shims themselves. Others are places where there are no shims and the deprecation will cause a breakage once it lands:

uv run pyright
/home/danieleades/code/sphinx/sphinx/domains/c/__init__.py
  /home/danieleades/code/sphinx/sphinx/domains/c/__init__.py:534:24 - error: Operator "-" not supported for "None" (reportOptionalOperand)
/home/danieleades/code/sphinx/sphinx/domains/cpp/__init__.py
  /home/danieleades/code/sphinx/sphinx/domains/cpp/__init__.py:652:24 - error: Operator "-" not supported for "None" (reportOptionalOperand)
/home/danieleades/code/sphinx/sphinx/ext/intersphinx/_resolve.py
  /home/danieleades/code/sphinx/sphinx/ext/intersphinx/_resolve.py:542:24 - error: Operator "-" not supported for "None" (reportOptionalOperand)
/home/danieleades/code/sphinx/sphinx/io.py
  /home/danieleades/code/sphinx/sphinx/io.py:20:35 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
/home/danieleades/code/sphinx/sphinx/transforms/i18n.py
  /home/danieleades/code/sphinx/sphinx/transforms/i18n.py:33:35 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/transforms/i18n.py:62:15 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
/home/danieleades/code/sphinx/sphinx/transforms/post_transforms/code.py
  /home/danieleades/code/sphinx/sphinx/transforms/post_transforms/code.py:95:24 - error: Operator "+" not supported for "None" (reportOptionalOperand)
/home/danieleades/code/sphinx/sphinx/util/docutils.py
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:15:31 - error: The class "OptionParser" is deprecated
    The `frontend.OptionParser` class will be replaced by a subclass of `argparse.ArgumentParser` in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:40:35 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:819:27 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:912:6 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:918:25 - error: The class "OptionParser" is deprecated
    The `frontend.OptionParser` class will be replaced by a subclass of `argparse.ArgumentParser` in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:927:44 - error: The function "set_classes" is deprecated
    Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead. (reportDeprecated)
  /home/danieleades/code/sphinx/sphinx/util/docutils.py:933:9 - error: The function "set_classes" is deprecated
    Deprecated and will be removed in Docutils 2.0, Use `roles.normalize_options()` instead. (reportDeprecated)
/home/danieleades/code/sphinx/tests/test_markup/test_markup.py
  /home/danieleades/code/sphinx/tests/test_markup/test_markup.py:26:35 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
  /home/danieleades/code/sphinx/tests/test_markup/test_markup.py:32:44 - error: The class "Values" is deprecated
    The `frontend.Values` class will be removed in Docutils 2.0 or later. (reportDeprecated)
16 errors, 0 warnings, 0 informations

@AA-Turner
Copy link
Member

AA-Turner commented Dec 1, 2025

i take it we'll need proper solutions for all those deprecation warnings before that happens?

some of these warnings are from the shims themselves. Others are places where there are no shims and the deprecation will cause a breakage once it lands

I haven't looked in detail, but I'd suggest we (a) ensure we're using shims/wrappers consistently throughout and then (b) suppress the deprecation warning once, within the shim. Can we make this work?

A

@danieleades
Copy link
Contributor

/home/danieleades/code/sphinx/sphinx/util/docutils.py:40:35 - error: The class "Values" is deprecated
The frontend.Values class will be removed in Docutils 2.0 or later. (reportDeprecated)

@AA-Turner this deprecation warning doesn't indicate a migration path, so it's not clear what the shim would be. Unclear if docutils will expose an argparse equivalent, or if the expectation is that we stop relying on this low-level interface entirely. A migration guide would be handy...

@AA-Turner
Copy link
Member

For docutils.frontend.Values I think we can just suppress the deprecation warnings throughout. When optparse was deprecated we were going to move to argparse but now it has been un-deprecated the future is less clear here.

A

@danieleades
Copy link
Contributor

For docutils.frontend.Values I think we can just suppress the deprecation warnings throughout. When optparse was deprecated we were going to move to argparse but now it has been un-deprecated the future is less clear here.

A

so docutils is planning to move from exposing optparse types to exposing argparse types?

a better solution would be for docutils to find a way to avoid exposing either interface directly. It's a leaky abstraction. Possibly through a wrapper or a protocol

@adamtheturtle
Copy link
Contributor

@adamtheturtle what is the status of this?

Thanks for taking over. I got to the point where I was struggling without adding any more type: ignores and I paused. Thank you for taking over.

@AA-Turner
Copy link
Member

so docutils is planning to move from exposing optparse types to exposing argparse types?

It was (I made the relevant changes). Unsure if we still will, though. As such for now I think suppressing the warnings is the best bet, especially given we constrain Docutils on the upper-bound.

a better solution would be for docutils to find a way to avoid exposing either interface directly. It's a leaky abstraction. Possibly through a wrapper or a protocol

Agreed.

A

@danieleades
Copy link
Contributor

@adamtheturtle what is the status of this?

Thanks for taking over. I got to the point where I was struggling without adding any more type: ignores and I paused. Thank you for taking over.

do you plan to pick it back up to address the pyright errors?

I don't want to steal your thunder!

@AA-Turner AA-Turner removed dependencies Pull requests that update a dependency file python Pull requests that update Python code labels Dec 2, 2025
@AA-Turner
Copy link
Member

ping @adamtheturtle

@adamtheturtle
Copy link
Contributor

@danieleades if you're happy to do it, please do. I have enough thunder ;)

@danieleades
Copy link
Contributor

@AA-Turner @adamtheturtle i've just suppressed the pyright warnings for now. Possibly not the best long term solution

@AA-Turner AA-Turner merged commit 71cc5d8 into master Dec 10, 2025
57 of 59 checks passed
@AA-Turner AA-Turner deleted the dependabot/pip/types-docutils-0.21.0.20250604 branch December 10, 2025 15:41
@AA-Turner
Copy link
Member

Thanks @adamtheturtle @danieleades

A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants