Add a Sphinx extension to document cached properties of slots classes

[clayote]

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

• Do not open pull requests from your main branch – use a separate branch!
  • There's a ton of footguns waiting if you don't heed this warning. You can still go back to your project, create a branch from your main branch, push it, and open the pull request from the new branch.
  • This is not a pre-requisite for your pull request to be accepted, but you have been warned.
• Added tests for changed code.
  Our CI fails if coverage is not 100%.
• Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi).
  • ...and used in the stub test file typing-examples/baseline.py or, if necessary, typing-examples/mypy.py.
  • If they've been added to attr/__init__.pyi, they've also been re-imported in attrs/__init__.pyi.
• Updated documentation for changed code.
  • New functions/classes have to be added to docs/api.rst by hand.
  • Changes to the signatures of @attr.s() and @attrs.define() have to be added by hand too.
  • Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    The next version is the second number in the current release + 1.
    The first number represents the current year.
    So if the current version on PyPI is 22.2.0, the next version is gonna be 22.3.0.
    If the next version is the first in the new year, it'll be 23.1.0.
    • If something changed that affects both attrs.define() and attr.s(), you have to add version directives to both.
• Documentation in .rst and .md files is written using semantic newlines.
• Changes (and possible deprecations) have news fragments in changelog.d.
• Consider granting push permissions to the PR branch, so maintainers can fix minor issues themselves without pestering you.

[clayote]

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]

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

[clayote]

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

[hynek]

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]

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

[clayote]

Looks like a misconfigured test to me

[sscherfke]

@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]

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

[clayote]

@AdrianSosic Please do

[clayote]

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

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

[hynek]

Hey I'm sorry for not turning up earlier, and I'm extra sorry if my innocent question for a test on the other PR lead us to this +340 diff that also contains a whole Sphinx extension.

I will not maintain a Sphinx extension, but if you want to, we can let yours live within the python-attrs organization. However, shouldn't it be something that could be fixed in Sphinx proper?

Either way, your changes to the very heart of attrs and its behavior is just too deep and far-reaching for a too narrow of a use-case.

I should've stopped you earlier and I've also amended our contribution guidelines to avoid this situation in the future in #1528.

I'm very sorry, I feel bad about how all this went down.

[clayote]

I will not maintain a Sphinx extension, but if you want to, we can let yours live within the python-attrs organization. However, shouldn't it be something that could be fixed in Sphinx proper?

Mostly! I did a little more experimentation, and it turns out that, if my PR to Sphinx is merged, I can write the extension with no changes to attr._make at all. Any assistance getting that merged would be appreciated.

There still needs to be a Sphinx extension to reconstruct the cached_property object. The new extension doesn't need to be a part of this organization.

[clayote]

Well, that extension does work, but it relies on the current way that cached properties get made on slotted classes. If the _make_cached_property_getattr utility function were to change slightly, the extension would break.

@hynek would you be open to putting the cached property functions in the public API somewhere, perhaps __attrs_attrs__?