A few weeks ago, I proposed on this mailing list to write docstrings for
class attributes like this:
@dataclass
class A:
x: int
"""Docstring for x."""
The main criticism, I think, was that it is weird to have the docstring
*below* the attribute.
To solve this problem, I propose to introduce a new kind of string: a
d-string ('d' for 'docstring'; alternatively also 'v' because it looks a
bit like a downward arrow, or 'a' for 'attribute docstring'). A d-string
is a normal string, except that it is stored in __attrdoc__ when used
inside a class. It is stored with the name of the variable *below*
it as the key.
Examples:
@dataclass
class InventoryItem:
"""Class for keeping track of an item in inventory."""
d"""Short name of the item."""
name: str
d"""Price per unit in dollar."""
unit_price: float
d"""Available quantity currently in the warehouse."""
quantity_on_hand: int = 0
InventoryItem.__attrdoc__ == {
"name": "Short name of the item.",
"unit_price": "Price per unit in dollar.",
"quantity_on_hand": "Available quantity currently in the warehouse.",
}
----
class HttpRequest(Enum):
"""Types of HTTP requests."""
d"""GET requests are used to retrieve data."""
GET = auto()
d"""POST requests are used to insert/update remote data."""
POST = auto()
HttpRequest.__attrdoc__ == {
"GET": "GET requests are used to retrieve data.",
"POST": "POST requests are used to insert/update remote data.",
}
d-strings can be combined with raw strings by using the prefix rd or dr.
d-strings could also be used to document module-level constants:
# in my_module.py:
d"Number of days in a week."
DAYS_PER_WEEK: Final = 7
my_module.__attrdoc__ == {"DAYS_PER_WEEK": "Number of days in a week."}
-Thomas
_______________________________________________
Python-ideas mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/[email protected]/message/VV5MOSIRVSTRDTA5NFVVUXGD2JFBERRS/
Code of Conduct: http://python.org/psf/codeofconduct/
