Title: Make dataclass attribute docstrings accessible
Type: enhancement Stage: resolved
Components: Documentation Versions:
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: 4-launchpad-kalvdans-no-ip-org, John Parejko2, docs@python, eric.smith, taleinat
Priority: normal Keywords:

Created on 2019-10-08 00:24 by John Parejko2, last changed 2021-06-15 15:14 by 4-launchpad-kalvdans-no-ip-org. This issue is now closed.

Messages (3)
msg354154 - (view) Author: John Parejko (John Parejko2) Date: 2019-10-08 00:24
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.

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."""
msg354192 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2019-10-08 11:56
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

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.
msg354507 - (view) Author: Tal Einat (taleinat) * (Python committer) Date: 2019-10-11 22:09
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.
Date User Action Args
2021-06-15 15:14:214-launchpad-kalvdans-no-ip-orgsetnosy: + 4-launchpad-kalvdans-no-ip-org
2019-10-11 22:09:28taleinatsetstatus: open -> closed

nosy: + taleinat
messages: + msg354507

resolution: rejected
stage: resolved
2019-10-08 11:56:49eric.smithsetmessages: + msg354192
2019-10-08 03:41:04xtreaksetnosy: + eric.smith
2019-10-08 00:24:53John Parejko2create