Make dataclass attribute docstrings accessible

[parejkoj]

BPO	38401
Nosy	@taleinat, @ericvsmith, @parejkoj

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-10-11.22:09:28.836>
created_at = <Date 2019-10-08.00:24:53.020>
labels = ['type-feature', 'docs']
title = 'Make dataclass attribute docstrings accessible'
updated_at = <Date 2021-12-29.12:47:39.954>
user = 'https://github.com/parejkoj'

bugs.python.org fields:

activity = <Date 2021-12-29.12:47:39.954>
actor = 'egebes'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-10-11.22:09:28.836>
closer = 'taleinat'
components = ['Documentation']
creation = <Date 2019-10-08.00:24:53.020>
creator = 'John Parejko2'
dependencies = []
files = []
hgrepos = []
issue_num = 38401
keywords = []
message_count = 5.0
messages = ['354154', '354192', '354507', '405772', '409304']
nosy_count = 7.0
nosy_names = ['taleinat', 'eric.smith', 'docs@python', 'John Parejko2', '4-launchpad-kalvdans-no-ip-org', 'pabouk', 'egebes']
pr_nums = []
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38401'
versions = []

[parejkoj]

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."""

[ericvsmith]

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.

[taleinat]

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.

[pabouk]

Note that John Parejko is right that the active PEP-257 clearly specifies attribute docstrings. Here is the excerpt:

String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method are called "attribute docstrings".

They are being supported by various software like Sphinx, vim, VS Codes's Pylance.

[egebes]

There is some confusion in the answers that I want to clear up:

"Attribute docstrings" were suggested in PEP-224 in August 2000 and rejected March 2001: https://www.python.org/dev/peps/pep-0224/

taleinat mentioned already PEP-258 from May 2001, which also contained "attribute docstrings" and was as well rejected.

At the same time - May 2001 - the well-known PEP-257 about docstring conventions came up and was accepted. It also mentions "attribute docstrings", but in a kind of restricted way (highlighting *** by me):

String literals occurring elsewhere in Python code ***may also act as documentation***. They are ***not recognized*** by the Python bytecode compiler and are ***not accessible*** as runtime object attributes (i.e. not assigned to __doc__), ...
Please see PEP-258, "Docutils Design Specification" [2], for a detailed description of attribute and additional docstrings.

The reference to the rejected PEP-258 does in my opinion not make the concept of "attribute docstrings" invalid, but indeed the restrictive wording (highlighted *** in the quote) defines their status, and it helps to explain the situation:

• Attribute docstrings are not supported by Python itself (no doc etc.) -> that's why it is hard to add support for dataclass documentation in help as John Parejko suggested.

• It is totally fine to use attribute docstrings, since PEP-257 explicitly mentions them. Various tools support them.

• There is - as far as I can see it - no clear notion to differentiate between "official" docstrings and "inofficial" ones (attribute docstrings, additional docstrings). All of them are docstrings in the broader sense, though most times only the "official" ones are meant, and many don't even know about the "inofficial" ones.