[issue38401] Make dataclass attribute docstrings accessible
New submission from John Parejko <parejkoj@uw.edu>: Dataclasses provide a very straightforward way to specify structured data. One can trivally document a dataclass's attributes via triple-quoted attribute docstrings per PEP 257. However, those docstrings are not accessible to pydoc, so they are lost to users of the dataclass. For example, the attribute docstrings in the below dataclass should be available when looking at `help(SpectralData)`, but that help command does not show the docstrings. ``` @dataclasses.dataclass class SpectralData: """Class to hold data and metadata from a fiber spectrograph.""" wavelength: astropy.units.Quantity """The wavelength array produced by the instrument.""" spectrum: np.ndarray """The flux array in instrumental units.""" duration: float """The duration of the exposure in seconds.""" ``` ---------- assignee: docs@python components: Documentation messages: 354154 nosy: John Parejko2, docs@python priority: normal severity: normal status: open title: Make dataclass attribute docstrings accessible type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________
Change by Karthikeyan Singaravelan <tir.karthi@gmail.com>: ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________
Eric V. Smith <eric@trueblade.com> added the comment: Note that those strings are not docstrings, per se. They're just strings, and aren't available in the class definition for the dataclass decorator to see. It's really no different from: class X: x: int 3 That 3 just gets evaluated and thrown away, like the strings in your example. To change this is beyond the scope of dataclasses, and would need to be a language change. I can't think of a good way to attach the string to the annotation before it (I'm assuming this would only work with annotations, but maybe you have other ideas). You might want to bring this up on python-ideas to get some more feedback. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________
Tal Einat <taleinat@gmail.com> added the comment: Thanks for this suggestion John! Unfortunately, only the first string literal in the example is a doc-string, and the rest indeed are not. (PEP-258 suggested adding such doc-strings, but it was rejected.) There is currently no standard way to attach a doc-string to a field in dataclasses, nor in attrs on which dataclasses was mostly based. However, both libraries support custom field meta-data, using which one could add such per-field documentation. So if one really needs something like this, it is possible to work up a custom solution. Eric is correct that this is far from a straightforward suggestion, which would require a significant language change to implement. Due to the depth of the change required, it would need to be discussed on Python-ideas mailing list first. Please bring this up there if you'd like to pursue this further. I'm closing this as "rejected" for now since I believe the likelihood of pursuing this to be very small, but this can be re-opened later if further discussion warrants it. ---------- nosy: +taleinat resolution: -> rejected stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________
participants (4)
-
Eric V. Smith -
John Parejko
-
Karthikeyan Singaravelan
-
Tal Einat