How to document class attributes in Python?

👻 Check our latest review to choose the best laptop for Machine Learning engineers and Deep learning tasks!

I"m writing a lightweight class whose attributes are intended to be publicly accessible, and only sometimes overridden in specific instantiations. There"s no provision in the Python language for creating docstrings for class attributes, or any sort of attributes, for that matter. What is the expected and supported way, should there be one, to document these attributes? Currently I"m doing this sort of thing:

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

    Attributes:
    """

    flight_speed = 691
    __doc__ += """
        flight_speed (691)
          The maximum speed that such a bird can attain.
    """

    nesting_grounds = "Raymond Luxury-Yacht"
    __doc__ += """
        nesting_grounds ("Raymond Luxury-Yacht")
          The locale where these birds congregate to reproduce.
    """

    def __init__(self, **keyargs):
        """Initialize the Albatross from the keyword arguments."""
        self.__dict__.update(keyargs)

This will result in the class"s docstring containing the initial standard docstring section, as well as the lines added for each attribute via augmented assignment to __doc__.

Although this style doesn"t seem to be expressly forbidden in the docstring style guidelines, it"s also not mentioned as an option. The advantage here is that it provides a way to document attributes alongside their definitions, while still creating a presentable class docstring, and avoiding having to write comments that reiterate the information from the docstring. I"m still kind of annoyed that I have to actually write the attributes twice; I"m considering using the string representations of the values in the docstring to at least avoid duplication of the default values.

Is this a heinous breach of the ad hoc community conventions? Is it okay? Is there a better way? For example, it"s possible to create a dictionary containing values and docstrings for the attributes and then add the contents to the class __dict__ and docstring towards the end of the class declaration; this would alleviate the need to type the attribute names and values twice. edit: this last idea is, I think, not actually possible, at least not without dynamically building the entire class from data, which seems like a really bad idea unless there"s some other reason to do that.

I"m pretty new to python and still working out the details of coding style, so unrelated critiques are also welcome.

👻 Read also: what is the best laptop for engineering students?

How to document class attributes in Python? __del__: Questions

import time
time.sleep(5)   # Delays for 5 seconds. You can also use a float value.

import time
while True:
    print("This prints once a minute.")
    time.sleep(60) # Delay for 1 minute (60 seconds).

from time import sleep
sleep(0.1) # Time in seconds

How to document class attributes in Python? __del__: Questions

We hope this article has helped you to resolve the problem. Apart from How to document class attributes in Python?, check other __del__-related topics.

Want to excel in Python? See our review of the best Python online courses 2023. If you are interested in Data Science, check also how to learn programming in R.

By the way, this material is also available in other languages:

• Italiano How to document class attributes in Python?
• Deutsch How to document class attributes in Python?
• Français How to document class attributes in Python?
• Español How to document class attributes in Python?
• Türk How to document class attributes in Python?
• Русский How to document class attributes in Python?
• Português How to document class attributes in Python?
• Polski How to document class attributes in Python?
• Nederlandse How to document class attributes in Python?
• 中文 How to document class attributes in Python?
• 한국어 How to document class attributes in Python?
• 日本語 How to document class attributes in Python?
• हिन्दी How to document class attributes in Python?