In short: class attributes cannot have doc strings in the way that classes and functions have.

To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.

Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.

Answer from ʇsәɹoɈ on Stack Overflow
🌐
Python
docs.python.org › 2.0 › doc › classes.html
4 Document Classes
The manual documents are larger and are used for most of the standard documents. This document class is based on the standard LATEX report class and is formatted very much like a long technical report. The Python Reference Manual is a good example of a manual document, and the Python Library Reference is a large example.
Top answer
1 of 6
135

In short: class attributes cannot have doc strings in the way that classes and functions have.

To avoid confusion, the term property has a specific meaning in python. What you're talking about is what we call class attributes. Since they are always acted upon through their class, I find that it makes sense to document them within the class' doc string. Something like this:

class Albatross(object):
    """A bird with a flight speed exceeding that of an unladen swallow.

    Attributes:
        flight_speed     The maximum speed that such a bird can attain.
        nesting_grounds  The locale where these birds congregate to reproduce.
    """
    flight_speed = 691
    nesting_grounds = "Throatwarbler Man Grove"

I think that's a lot easier on the eyes than the approach in your example. If I really wanted a copy of the attribute values to appear in the doc string, I would put them beside or below the description of each attribute.

Keep in mind that in Python, doc strings are actual members of the objects they document, not merely source code annotations. Since class attribute variables are not objects themselves but references to objects, they have no way of holding doc strings of their own. I guess you could make a case for doc strings on references, perhaps to describe "what should go here" instead of "what is actually here", but I find it easy enough to do that in the containing class doc string.

2 of 6
108

The other answers are very outdated. PEP-257 describes how you can use docstrings for attributes. They come after the attribute, weirdly:

String literals occurring elsewhere in Python code may also act as documentation. They are not recognized by the Python bytecode compiler and are not accessible as runtime object attributes (i.e. not assigned to __doc__), but two types of extra docstrings may be extracted by software tools:

  1. String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called “attribute docstrings”.
class C:
    "class C doc-string"

    a = 1
    "attribute C.a doc-string (1)"

    b = 2
    "attribute C.b doc-string (2)"

It also works for type annotations like this:

class C:
    "class C doc-string"

    a: int
    "attribute C.a doc-string (1)"

    b: str
    "attribute C.b doc-string (2)"

VSCode supports showing these.

🌐
Python
docs.python.org › 2.5 › doc › classes.html
5 Document Classes
December 23, 2008 - The manual documents are larger and are used for most of the standard documents. This document class is based on the standard LaTeX report class and is formatted very much like a long technical report. The Python Reference Manual is a good example of a manual document, and the Python Library Reference is a large example.
🌐
Lsst
developer.lsst.io › v › DM-15183 › python › numpydoc.html
Documenting Python APIs with Docstrings — LSST DM Developer Guide DM-15183 documentation
_`Numpydoc Sections in Docstrings`: https://developer.lsst.io/docs/py_docs.html#py-docstring-sections """ __all__ = ('MODULE_LEVEL_VARIABLE', 'moduleLevelFunction', 'exampleGenerator', 'ExampleClass', 'ExampleError') MODULE_LEVEL_VARIABLE = 12345 """Module level variable documented inline (`int`). The module variable's type is specified in the short summary, as shown above. Module variables (constants) can have extended descriptions, like this paragraph. For a complete list of sections permitted in constant docstrings see `Documenting Constants and Class Attributes`_.
🌐
Lsst
developer.lsst.io › v › DM-7919 › docs › py_docs.html
Documenting Python APIs — LSST DM Developer Guide latest documentation
If a sequence of values is returned, each value may be separately listed, in order: Returns ------- x : `int` Description of x. y : `int` Description of y. If a return type is dict, ensure that the key-value pairs are documented in the description. For generators. ‘Yields’ is used identically to ‘Returns’, but for generators. For classes, methods and functions.
🌐
Programiz
programiz.com › python-programming › docstrings
Python Docstrings (With Examples)
The PEP 257 document provides the standard conventions to write multi-line docstrings for various objects. ... The docstrings for Python Modules should list all the available classes, functions, objects and exceptions that are imported when the module is imported.
🌐
Read the Docs
python-docx.readthedocs.io › en › latest › api › document.html
Document objects — python-docx 1.2.0 documentation
The Paragraph instances in the document, in document order. Note that paragraphs within revision marks such as <w:ins> or <w:del> do not appear in this list.
🌐
Lsst
developer.lsst.io › v › DM-5063 › docs › py_docs.html
Documenting Python Code — LSST DM Developer Guide latest documentation
When describing an argument in ... which is Python-aware in docstrings). For the parameter types, be as precise as possible. Parameters ---------- filename : str Description of `filename`. copy : bool Description of `copy`. dtype : data-type Description of `dtype`. iterable : iterable object Description of `iterable`. shape : int or tuple of int Description of `shape`. files : list of str Description of `files`. For instances of classes, provide the ...
Find elsewhere
🌐
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - <name> may be the name of a Python ... reference to a class or function within a module or module in a package. If <name> contains a '\', it is used as the path to a Python source file to document. If name is 'keywords', 'topics', or 'modules', a listing of these things is ...
🌐
Iram
iram.fr › IRAMFR › GILDAS › doc › html › gildas-python-html › node9.html
The __doc__ attribute
Each Python object (functions, classes, variables,...) provides (if programmer has filled it) a short documentation which describes its features. You can access it with commands like print myobject.__doc__.
🌐
Real Python
realpython.com › documenting-python-code
Documenting Python Code: A Complete Guide – Real Python
July 17, 2026 - Package docstrings should be placed at the top of the package’s __init__.py file. This docstring should list the modules and sub-packages that are exported by the package. Module docstrings are similar to class docstrings. Instead of classes and class methods being documented, it’s now the module and any functions found within.
🌐
Python documentation
docs.python.org › 3 › tutorial › classes.html
9. Classes — Python 3.14.7 documentation
However, aliasing has a possibly surprising effect on the semantics of Python code involving mutable objects such as lists, dictionaries, and most other types. This is usually used to the benefit of the program, since aliases behave like pointers in some respects. For example, passing an object is cheap since only a pointer is passed by the implementation; and if a function modifies an object passed as an argument, the caller will see the change — this eliminates the need for two different argument passing mechanisms as in Pascal. Before introducing classes, I first have to tell you something about Python’s scope rules.
🌐
GeeksforGeeks
geeksforgeeks.org › python-docstrings
Python Docstrings - GeeksforGeeks
August 2, 2024 - Whereas Python Docstrings as mentioned above provides a convenient way of associating documentation with Python modules, functions, classes, and methods. ... Python was created by Guido van Rossum in 1991 and further developed by the Python Software Foundation. It was designed with focus on code readability and its syntax allows us to express concepts in fewer lines of code.Key Features of PythonPython’s simple and readable syntax makes it beginner-frien ... Printing a list in Python is a common task when we need to visualize the items in the list.
🌐
GitHub
github.com › microsoft › pylance-release › issues › 1576
Class attribute documentation? · Issue #1576 · microsoft/pylance-release
July 20, 2021 - Discussed in microsoft/vscode-python#16736 Originally posted by Holt59 July 19, 2021 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:...
Author: microsoft
🌐
PyPI
pypi.org › project › class-doc
class-doc
JavaScript is disabled in your browser · Please enable JavaScript to proceed · A required part of this site couldn’t load. This may be due to a browser extension, network issues, or browser settings. Please check your connection, disable any ad blockers, or try using a different browser
🌐
Noirlab
datalab.noirlab.edu › docs › manual › DevGuide › DocumentingPythonAPIswithDocstrings › DocumentingPythonAPIswithDocstrings.html
3.2. Documenting Python APIs with Docstrings — Data Lab documentation
_`Numpydoc Sections in Docstrings`: https://developer.lsst.io/docs/py_docs.html#py-docstring-sections """ __all__ = ('MODULE_LEVEL_VARIABLE', 'moduleLevelFunction', 'exampleGenerator', 'ExampleClass', 'ExampleError') MODULE_LEVEL_VARIABLE = 12345 """Module level variable documented inline (`int`). The module variable's type is specified in the short summary, as shown above. Module variables (constants) can have extended descriptions, like this paragraph. For a complete list of sections permitted in constant docstrings see `Documenting Constants and Class Attributes`_.
🌐
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_google.html
Example Google Style Python Docstrings — napoleon 0.7 documentation
The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself. Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it. Note: Do not include the `self` parameter in the ``Args`` section. Args: param1 (str): Description of `param1`. param2 (:obj:`int`, optional): Description of `param2`. Multiple lines are supported. param3 (:obj:`list...
🌐
SourceForge
epydoc.sourceforge.net › manual-docstring.html
Python Docstrings - Epydoc
class A: x = 22 """Docstring for class variable A.x""" def __init__(self, a): self.y = a """Docstring for instance variable A.y · Variables may also be documented using comment docstrings.
🌐
Medium
medium.com › @syedar.sohail › docstring-and-why-is-it-important-python-classes-modules-and-functions-95fee5247ff5
Docstring and why is it important ? — Python Classes, Modules and Functions | by Sohail | Medium
October 30, 2022 - When the complexity of code increases, we are pushed to make our own classes that is okay but what if we wrote 1000 lines of code and we have given it to our colleague or shared the files privately or to a group in a organisation who wants to use our classes. Well, they may spend a lot of time figuring out what our class attributes might do, so to tackle this problem Python has something called ‘Docstrings’ to help us out.
🌐
TestDriven.io
testdriven.io › blog › documenting-python
Documenting Python Code and Projects | TestDriven.io
February 9, 2023 - Using docstrings, you can document it like so: """ The temperature module: Manipulate your temperature easily Easily calculate daily average temperature """ from typing import List class HighTemperature: """Class representing very high temperatures""" def __init__(self, value: float): """ :param value: value of temperature """ self.value = value def daily_average(temperatures: List[float]) -> float: """ Get average daily temperature Calculate average temperature from multiple measurements :param temperatures: list of temperatures :return: average temperature """ return sum(temperatures)/len(temperatures)