What is the best long-term support path for documenting class properties while using autodoc?

[sirosen]

In Python 3.9, we were allowed to stack classmethod with property, before the problems with this pattern were fully realized. Sphinx added support for this to autodoc, but support for these descriptors being composed was pulled in Python 3.10.

As Python 3.9 EOL approaches, it seems appropriate to think of the future of Sphinx support for class properties. There are several third-party implementations, making various tradeoffs, and it's easy to write your own read-only one, e.g.:

# various implementations possible; this is just a sample
class classproperty[T, R]:
    def __init__(self, func: t.Callable[[type[T] | T], R]) -> None:
        self.func = func

    def __get__(self, obj: T | None, cls: type[T]) -> R:
        if obj is None:
            return self.func(cls)
        return self.func(obj)

Because autodoc treats stacked decorators as indicating classproperty-ness, you can make a sphinx-friendly version by detecting whether or not a doc build is running and dispatching between implementations. e.g.,

if _in_sphinx_build():
    def classproperty(func):
        return classmethod(property(func))
else:
    ... # real classproperty here

This works great! But it doesn't seem certain that it will last. classmethod(property(...)) only works in CPython 3.9, no other versions, and probably not at all in other implementations.

Looking at the Python Domain definition, py:property has a :classmethod: option. That seems less likely to be removed -- since various third-party implementations of class properties exist, this is a good way to document them.

So! I'm very curious. What's the best way, long-term, for users of class properties to document them? Right now, I'm considering switching off of the build-detection approach (I'm doing it by checking sys.argv[0], but other methods are possible) and onto an explicit py:property definition.

[AA-Turner]

@sirosen I fear there are few (if any) good methods for properly detecting custom class property decorators. We would need some reliable indicator; I don't want to be in the business of introspecting decorator function/class bodies.

How bad would it be to need to mark classmethod status on the autodoc directive? For example:

.. autoproperty:: stephens_read_only_classproperty
   :classmethod:

The other 'obvious' option is to invent a custom dunder to set, but this equally has several drawbacks.

A

[sirosen]

Yeah, I don't like a custom dunder, and actually I don't like the idea of Sphinx inspecting what I'm doing via some super-secret-handshake protocol.

An explicit marker like .. autoproperty + :classmethod: seems great to me, and it's obvious how that can be composed with .. property as well.

I'll see if I can make a PR to add this (after I wrap up some of my other FOSS adventures! 😁 ), and we can evaluate how it looks.