Add a Sphinx extension to document cached properties of slots classes by clayote · Pull Request #1519 · python-attrs/attrs

clayote · 2026-02-21T18:10:58Z

Summary

This is a small extension for Sphinx, the documentation generator that attrs uses. Where cached properties on slots classes were missing previously (#1325), this extension restores them.

I added a dictionary to slotted class objects, __attrs_cached_properties__, where they keep the cached property objects for Sphinx.

I wrapped the __slots__ tuple itself in a custom collections.abc.Sequence that acts exactly like its tuple, but isn't considered one for the purposes of isinstance(), because, currently, I have to do that in order to make Sphinx use the extension on slots. I have a PR for Sphinx open to make that unnecessary.

To use the extension, add "attrs.sphinx_cached_property" to extensions in your Sphinx conf.py.

Pull Request Check List

clayote · 2026-02-21T18:34:23Z

I wrote a test for this, but it won't run in CI currently, because that test requires Sphinx to be installed. That's why the pre-commit check is failing.

clayote · 2026-02-22T04:44:21Z

I need to make sure the :members: directive works, too...

clayote · 2026-02-22T05:11:55Z

I haven't a clue what's going on with those interrogate failures! It seems to be related to coverage somehow? @hynek ?

hynek · 2026-02-22T08:33:46Z

I haven't a clue what's going on with those interrogate failures! It seems to be related to coverage somehow? @hynek ?

on a quick look I see two tests without docstrings

clayote · 2026-02-22T22:01:30Z

Checks are passing, I think it's ready @hynek

clayote · 2026-02-22T22:17:07Z

Looks like a misconfigured test to me

sscherfke · 2026-02-22T22:21:14Z

@clayote Your actions create a lot of noise and many notifications. It would be helpful if you did more work offline and and only post updates and questions when really needed. This would make it easier for reviewers/maintainers to help you.

AdrianSosic · 2026-02-24T07:41:34Z

@clayote: feel free to ping me when it's ready for me to test 👌🏼

clayote · 2026-02-24T07:42:41Z

@AdrianSosic Please do

clayote · 2026-02-24T07:43:49Z

Huh, I guess I'd better write documentation for the extension.

It's not part of the API, really? Where should it go...

changelog.d/1519.change.md

webknjaz · 2026-02-25T07:36:57Z

src/attr/_make.py



+class _TupleProxy(Sequence):
+    __slots__ = ("_tup",)


A docstring must be the first node in the class definition for it to end up in __doc__. Otherwise, it's a docstring of the __slots__ attribute which most tools don't parse as such (I only know of Sphinx). Though, looking at the text, it seems you meant it to be a class docstring...

@clayote did you mark this as resolved by accident?

tests/test_slots.py

Sphinx looks at the cached properties first for these...

… there

Overkill? Yeah, whatever

@webknjaz

Thanks @webknjaz Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

@webknjaz

Now that the `test` dependency group includes `docs`, the mark does nothing. Thanks @webknjaz

@webknjaz

Thanks @webknjaz

@webknjaz

Thanks @webknjaz

for more information, see https://pre-commit.ci

webknjaz · 2026-03-07T08:53:53Z

src/attrs/sphinx_cached_property.py

+    return props[name]
+
+
+def setup(app: Sphinx):


Suggested change

def setup(app: Sphinx):

def setup(app: Sphinx) -> dict[str, bool | str]:

webknjaz · 2026-03-07T08:54:44Z

src/attrs/sphinx_cached_property.py

+
+def get_cached_property_for_member_descriptor(
+    cls: type, name: str, default=None
+):


Suggested change

):

) -> str:

?

webknjaz · 2026-03-07T08:55:36Z

tests/index.txt

Maybe scope this all in a subdir?

clayote force-pushed the sphinx-attr-getter-ext branch 2 times, most recently from 6fce05b to 365bc5c Compare February 21, 2026 18:27

clayote marked this pull request as ready for review February 21, 2026 18:51

clayote force-pushed the sphinx-attr-getter-ext branch 4 times, most recently from 1daa5c1 to b21e641 Compare February 22, 2026 03:04

clayote marked this pull request as draft February 22, 2026 04:43

clayote marked this pull request as ready for review February 22, 2026 08:30

clayote force-pushed the sphinx-attr-getter-ext branch from c824181 to 672bfb7 Compare February 22, 2026 22:04

clayote force-pushed the sphinx-attr-getter-ext branch from 5858047 to a31031b Compare February 23, 2026 13:44

webknjaz reviewed Feb 25, 2026

View reviewed changes

clayote requested a review from webknjaz February 25, 2026 18:58

clayote force-pushed the sphinx-attr-getter-ext branch 7 times, most recently from b679a23 to 43c0e16 Compare March 5, 2026 02:59

clayote and others added 24 commits March 6, 2026 13:37

Fix pyproject.toml

fc5fa55

Add a test for Sphinx's autodoc :members:

9e38b57

Sphinx looks at the cached properties first for these...

Add a weird hack to make Sphinx pretend slots for cached props aren't…

b300d17

… there

Add __eq__ and __ne__ to _TupleProxy

cb6303a

Write docstrings for tests

cd82290

Add docstring to sphinx_cached_property.py

01a7175

"Implement" _TupleProxy.__hash__

179d4f3

Make the tests dependency group depend on the docs one

36d55e8

Overkill? Yeah, whatever

Add test_tuple_proxy

c9f1ee8

Delete _TupleProxy.__ne__

de84719

Add equality assertion to test_tuple_proxy

50620ce

Put some stuff in the tuples for test_tuple_proxy

640396f

Test hashes in test_tuple_proxy

09a1e34

Document sphinx_cached_property in how-does-it-work.md

d2fd6f5

Remove the :mod: role from "Sphinx" in how-does-it-work.md

2fe7543

Improve module docstring in sphinx_cached_property.py

1f5f244

Update changelog.d/1519.change.md

987e7cc

Thanks @webknjaz Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

Remove @need_sphinx from test_slots.py

4ff3583

Now that the `test` dependency group includes `docs`, the mark does nothing. Thanks @webknjaz

Use pytest's tmp_path fixture for Sphinx tests

6ed25f3

Thanks @webknjaz

Make Sphinx tests more elegant with read_text

64b28ba

Thanks @webknjaz

Use shutil to make Sphinx tests more elegant in test_slots.py

e8e60d6

Remove the now-pointless import guard around Sphinx in test_slots.py

9a02092

Report attrs version in attrs.sphinx_cached_property

ec89dd2

Add docstrings to sphinx_cached_property.py

fdccaa5

clayote force-pushed the sphinx-attr-getter-ext branch from 6fe52c2 to fdccaa5 Compare March 6, 2026 00:37

Include Sphinx &c in uv.lock

64e8291

clayote force-pushed the sphinx-attr-getter-ext branch from 8c94c7f to 64e8291 Compare March 6, 2026 04:13

[pre-commit.ci] auto fixes from pre-commit.com hooks

6a690d5

for more information, see https://pre-commit.ci

webknjaz reviewed Mar 7, 2026

View reviewed changes

webknjaz requested a review from hynek March 7, 2026 08:56

	def setup(app: Sphinx):
	def setup(app: Sphinx) -> dict[str, bool \| str]:

Uh oh!

Conversation

clayote commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Pull Request Check List

Uh oh!

clayote commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clayote commented Feb 22, 2026

Uh oh!

clayote commented Feb 22, 2026

Uh oh!

hynek commented Feb 22, 2026

Uh oh!

clayote commented Feb 22, 2026

Uh oh!

clayote commented Feb 22, 2026

Uh oh!

sscherfke commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AdrianSosic commented Feb 24, 2026

Uh oh!

clayote commented Feb 24, 2026

Uh oh!

clayote commented Feb 24, 2026

Uh oh!

Uh oh!

webknjaz Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

webknjaz Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

webknjaz Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

webknjaz Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

webknjaz Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

clayote commented Feb 21, 2026 •

edited

Loading

clayote commented Feb 21, 2026 •

edited

Loading

sscherfke commented Feb 22, 2026 •

edited

Loading