Class attribute documentation?

[Holt59]

I'd like to know how I can get class attribute documentation on hover/completion, similar to what I would get with the docstring of a property:

class A:

    def __init__(self):
        self._foo = 33
        self.bar = 45
    
    @property
    def foo(self) -> int:
        """
        Returns:
            Foo documentation.
        """
        return self._foo

How can I get proper documentation (on hover/completion) for bar without using a property?

Note: I'm asking here since I don't know if it is something specific to this extension or to the server (I'm using Pylance).

[brettcannon]

How would you expect to write documentation for the bar attribute without using @property? Python doesn't have a way to attach documentation to attributes naturally, so I'm not sure how you would even express it so that Pylance could provide the information to you.

[Holt59]

PEP 257 says

String literals occurring immediately after a simple assignment at the top level of a module, class, or init method are called "attribute docstrings".

This is clarified in PEP 258 - Attribute Docstrings, although that one was rejected but is still mentioned in PEP 257...

So something like

def __init__(self):
    self.foo = 33
    """Description of foo."""

This could also be extracted from the class docstring, although if I'm correct Pylance does not parse the docstring as of now?

The rationale behind this is to avoid having to write properties for each attribute. Since the introduction of Final, I'd rather mark my attribute as Final and let mypy checks for wrong assignments than use property (I don't really need the runtime check).

[brettcannon]

Huh, I must have always glossed over that part of PEP 257 (attribute docstrings are not common and PEP 257 is historically used for docstring formatting and not where docstrings can appear).

I'll forward this on to the Pylance team as a feature request.

[brettcannon]

microsoft/pylance-release#1576