-
-
Notifications
You must be signed in to change notification settings - Fork 41
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feature: A way to get docstrings, ... of InitVar parameters of a dataclass #286
Comments
Hi @has2k1, thanks for the report 🙂 I'd be more to open to a fundamental change that adds docstrings to parameters and returned/received/yielded values. This would play well with PEP 727 and our griffe-typingdoc extension supporting it, or with potential successors of this PEP. Adding a new kind of objects would be a bad design choice IMO. This would open the door to many more different kinds of objects, complicating the API a lot. That's a no-go to me 😊 |
I think for parameters it would not be a fundamental change. Ignoring PEP 727 (but knowing that it could bring proper runtime docstrings to all parameters), this could be as small as giving |
This change gives the Parameter class the following attributes / propeties: - docstring - lineno - endlineno - parent - lines - linescollections - source Currenlty these values are only populated for dataclasses, and they are None for regular classes and functions. This makes it possible to accesss this information for all dataclass parameters, especially those set as `InitVar` where it was not possible to get it since they are not members (attributes) of the class. Issue mkdocstrings#286: mkdocstrings#286 Related to mkdocstrings#252: mkdocstrings#252
This change gives the Parameter class the `docstring` and `function` attributes. The docstring value is only populated for dataclasses. This makes it possible to access this information for all dataclass parameters, especially those set as `InitVar` where it was not possible to get it since they are not members (attributes) of the class. This slot can also be used to support things like PEP 727 (with extensions). In the future, we might add such a docstring slot to yielded, received and returned values too. Issue-286: #286 Related-to-mkdocstrings/griffe#252: #252 PR-288: #288 Co-authored-by: Timothée Mazzucotelli <[email protected]>
History
PR #252 removed
InitVar
parameters from the list of dataclass members (and attributes). This was correct.New Problem
There is no way to get access to the docstrings of the
InitVar
parameters. Class parameters (dc.Parameter
) do not have docstrings, only the core objects (dc.Object
) do and now classes only keep track of those objects that are members (dc.Class.members
).Brainstorming a solution
To be useful, the type of
InitVar
parameters should be derived fromdc.Object
. Then they have.docstring
,.lines
,.lineno
, e.t.c.But none of the current subclasses
[Alias, Attribute, Class, Function, Module]
is suitable.Possible options are:
InitVar
InitVariable
InitParameter
ClassParameter
DataclassParameter
With this kind of solution, the new class category would have to be used for one of:
Option 2. seems like the better choice, but some (most) dataclass parameters are also attributes and that would complicate the solution.
That leaves option 1.
Then where should these "InitVar" objects be stored?
Maybe have them back in
dc.Class.members
. This shouldn't be the problem if they are not of typedc.Attribute
and therefore do not show up indc.Class.attributes
. This would effectively makedc.Class.members
a lookup for all objects statically defined in the class namespace.The text was updated successfully, but these errors were encountered: