I think it's an interesting idea. I made the same or at least similar suggestion in the previous thread, but it didn't receive any responses. I assume this is because people weren't very interested (but I also understand people are busy).
Here's that message: https://mail.python.org/archives/list/python-ideas@python.org/message/SJEPCZOLSRZSVQENIKOVWVCJXTF4Z2WT/ --- Ricky. "I've never met a Kentucky man who wasn't either thinking about going home or actually going home." - Happy Chandler On Wed, Dec 8, 2021 at 6:56 AM <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/R6XERPYJTYCLA7ONR4NP72KJZLLX7ARQ/ Code of Conduct: http://python.org/psf/codeofconduct/
