Summary

Modernize autodoc_utils.

Review Request #14479 — Created June 27, 2025 and submitted July 7, 2025, 3:29 p.m.

Information

Owner

david

Repository

beanbag-docutils

Branch

master

Bugs

Depends On

Reviewers

Groups

beanbag-misc

People

Description

This change modernizes out autodoc_utils Sphinx extension in preparation
for adding new features to better deal with TypedDicts.

Testing Done

Ran unit tests.

Commits

Summary	ID
Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	5094ab32c155384c3486f4da79d6833f94403c94

Issues

Description	From	Last Updated
The trick to avoiding the warnings that you're having to ignore here is to do: try: ... except ImportError: if …	chipx86	July 3, 2025, 9:33 a.m.
Probably should capitalize "Returns". Also, "Returns-like", since it's more than "Returns".	chipx86	July 3, 2025, 9:33 a.m.
What's this for? We should document every # type: ignore so it's clear.	chipx86	July 3, 2025, 9:40 a.m.
What's this for?	chipx86	July 3, 2025, 9:37 a.m.
No need for these parens now.	chipx86	July 3, 2025, 9:37 a.m.
Why this? Let's document these. Here and below.	chipx86	July 3, 2025, 9:38 a.m.
I don't think the r is needed.	chipx86	July 3, 2025, 9:39 a.m.
Why this?	chipx86	July 3, 2025, 9:39 a.m.
undefined name 'Sequence' Column: 29 Error code: F821	reviewbot	July 3, 2025, 9:45 a.m.
undefined name 'Sequence' Column: 28 Error code: F821	reviewbot	July 3, 2025, 9:45 a.m.
undefined name 'Sequence' Column: 34 Error code: F821	reviewbot	July 3, 2025, 9:45 a.m.
Space after "type:". I guess either works? But that's how it's documented and commonly used.	chipx86	July 7, 2025, 3:04 p.m.

flake8 passed.

JSHint passed.

Commits:

	Summary	ID
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	d68419172949552ab941a402e03421a0dec75c96
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	b4971b4916c64e29493527531c24596c2e606bfc

Diff:

Revision 2 (+458 -308)

Show changes

	beanbag_docutils/sphinx/ext/autodoc_utils.py
	beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)

The issue has been resolved. Show all issues

The trick to avoiding the warnings that you're having to ignore here is to do:

try:
    ...
except ImportError:
    if TYPE_CHECKING:
        assert False
    else:
        ...


This ensures that the type checker only ever considers the first import and not whatever we have to patch in after. It also avoids the issue of ignoring the true imports and only considering the fallbacks (which shouldn't be the primary reference point for the type).
The way that's structured is very specific. It'll ensure that the type checker does not consider any code paths involving the fallbacks, either within this try/except or later where they're used. Just doing assert not TYPE_CHECKING or if not TYPE_CHECKING: won't give the same result.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Probably should capitalize "Returns".
Also, "Returns-like", since it's more than "Returns".
```

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)

The issue has been resolved. Show all issues

What's this for?

We should document every # type: ignore so it's clear.

david July 3, 2025, 9:40 a.m.

Type checker noise: Operator ">=" not supported for types "tuple[Literal[7], Literal[4]]" and "tuple[Literal[5], Literal[1]]"

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
What's this for?
```
1. david July 3, 2025, 9:40 a.m.
  Fixed by annotating extra_returns_sections

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)

The issue has been resolved. Show all issues

No need for these parens now.

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Why this? Let's document these. Here and below.
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
I don't think the r is needed.
```
beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py (Diff revision 2)
The issue has been resolved. Show all issues
```
Why this?
```

Commits:

	Summary	ID
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	b4971b4916c64e29493527531c24596c2e606bfc
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	a0c5155e91e0fc1a39d5223e8018e1cbde8b83f1

Diff:

Revision 3 (+500 -332)

Show changes

	beanbag_docutils/sphinx/ext/autodoc_utils.py
	beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 3)
The issue has been dropped. Show all issues
```
undefined name 'Sequence'

Column: 29
Error code: F821
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 3)
The issue has been dropped. Show all issues
```
undefined name 'Sequence'

Column: 28
Error code: F821
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 3)
The issue has been dropped. Show all issues
```
undefined name 'Sequence'

Column: 34
Error code: F821
```

Commits:

	Summary	ID
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	a0c5155e91e0fc1a39d5223e8018e1cbde8b83f1
	Modernize autodoc_utils. This change modernizes out autodoc_utils Sphinx extension in preparation for adding new features to better deal with TypedDicts. Testing Done: Ran unit tests.	5094ab32c155384c3486f4da79d6833f94403c94

Diff:

Revision 4 (+500 -332)

Show changes

	beanbag_docutils/sphinx/ext/autodoc_utils.py
	beanbag_docutils/sphinx/ext/tests/test_autodoc_utils.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Ship it!

```
Awesome.
```
beanbag_docutils/sphinx/ext/autodoc_utils.py (Diff revision 4)
The issue has been resolved. Show all issues
```
Space after "type:".
I guess either works? But that's how it's documented and commonly used.
```

Status:: Completed
Change Summary:: Pushed to master (947550c)