I propose there is already a viable option in typing.Annotated.
Example:
@dataclass
class InventoryItem:
"""Class for keeping track of an item in inventory."""
name: Annotated[str, "Short name of the item."]
unit_price: Annotated[float, "Price per unit in dollar."]
...
I've been using this in production code for about a year (with code
that generates OpenAPI document), with additional validation
constraints, and it's proving to be quite usable.
Paul
On Wed, 2021-12-08 at 11:50 +0000, tmkehrenb...@gmail.com wrote:
> 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 -- python-ideas@python.org
> To unsubscribe send an email to python-ideas-le...@python.org
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-ideas@python.org/message/VV5MOSIRVSTRDTA5NFVVUXGD2JFBERRS/
> Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/IC7B7DMUO2WRF3IUSLN4GAJJ65E3MOSQ/
Code of Conduct: http://python.org/psf/codeofconduct/
