On Wed, Dec 8, 2021 at 8:41 AM Steven D'Aprano <st...@pearwood.info> wrote:
> On Wed, Dec 08, 2021 at 11:50:55AM -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.
>
> ...
>
> Rather than implicitly linking a bare string to the following (or
> previous?) attribute, this would explicitly link them by putting them on
> the same line (at least for short docstrings).
>
> Full declaration syntax becomes:
>
> name : Type = value : docstring_expression
>
> with the various parts being optional. Example:
>
>
> @dataclass
> class InventoryItem:
> """Class for keeping track of an item in inventory."""
>
> name: str : "Short name of the item"
> unit_price: float : "Price per unit in dollar."
> quantity_on_hand: int = 0 : (
> "Available quantity currently in the warehouse.")
>
>
> The docstring expression could evaluate to any value, not necessarily a
> string, but conventionally one would use a string, and I expect style
> guides would discourage or ban non-strings. (But see below for a
> possible objection.)
>
> Aside from the name, each part of the syntax is optional:
>
> # Type hint only.
> name: Type
>
> # Assignment only.
> name = value
>
> # Declare a type hint, and a docstring.
> name: Type : docstring
>
> # Assign a value, and a docstring, with no type hint.
> name = value : docstring
>
> # And all three: type hint, value and docstring.
> name: Type = value : docstring
>
>
> If this makes sense, one might even have an attribute with no type hint
> or value, only a docstring:
>
> name : : docstring
>
> which would assign the docstring to `__attrdoc__` but otherwise have no
> effect.
>
> ...
>
>
> --
> Steve
>
IMO this is a much better idea than the OP's, or the similar d-string idea
I had come up with.
Here's an example of the kind of thing I imagine doing with this feature.
If I were doing a set of engineering calculations, I might get started by
writing pseudocode (but using the new docstrings) like this:
#### cantilevered_beam.py #####
"""Checking cantilevered beam designs."""
# material properties
E_s : float : "elastic modulus of steel"
F_y: float : "strength of steel"
# beam properties
I_beam : float : "moment of inertia of beam"
S_beam : float : "section modulus of beam"
L_beam : float : "cantilever length"
phi_M : float : "moment limit of beam"
# loads
P_u : float : "applied ultimate force"
M_u : float : "applied ultimate bending moment"
# deflections
delta_max : float : "maximum beam deflection"
delta_limit : float : "beam deflection limit"
check : bool : "Is the beam OK? - OK (true) or No Good (false)"
### end of module ####
This code doesn't yet do anything, but there is a ton of information being
shared here- information that can be used to write code later, quickly. It
is a very nice module template that could be used over and over again
(writing out the details of actual projects later).
Of course you could write pseudocode containing all of this information
today with regular strings. But the difference is that, if this were to be
a language feature, the information is going to be available
programmatically BEFORE actually implementing anything at all.
If I were in a jupyter notebook, I could write something like this (you
could so similar things a REPL):
[CELL 1]
import cantilevered_beam
print("\n".join(f"{name}:\t{docstring}" for name, docstring in
cantilevered_beam.__attrdoc__.items()))
...and it would nicely output all the documentation written in the template
module above for my reference, and in the next cell I would interactively
compose code like this (probably copying and pasting from above, and then
typing over the type-hints and docstrings):
[CELL 2]
#### my_cantilevered_beam.py #####
"""A check for a cantilevered beam design."""
# material properties
E_s = 29_000 # ksi
F_y = 50 # ksi
# beam properties
I_beam = 1_830 # in^4 for W 24x68 beam
S_beam = 154 # in^3 for W 24x68 beam
L_beam = 190.25 # inches
phi_M = 0.9 * F_y * S_beam # kip-in
P_u = 4.947 # kips
M_u = P_u * L_beam # kip-in
delta_max = P_u * L_beam**3 / (48 * E_s * I_beam) # inches
delta_limit = 1 # inches
check = True if M_u <= phi_M and delta_max <= delta_limit else False
Could I accomplish something similar today using regular strings? Sure. But
it seems to me that having an official way to document attributes/members
has been an oft requested feature, and I really like imaging the kinds of
things I would be inclined to do with it if it were supported in the
language (rather than something I was off doing on my own as a
low-experience programmer, and wondering if it was dumb or a mistake).
---
Ricky.
"I've never met a Kentucky man who wasn't either thinking about going home
or actually going home." - Happy Chandler
_______________________________________________
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/ZWPANBHRLWAVW64V7FTLXKUPMT6BHNPR/
Code of Conduct: http://python.org/psf/codeofconduct/
