Support field docstrings for dataclasses that use __slots__ #113878
Comments
|
The change is quite simple, it results in: import dataclasses
@dataclasses.dataclass(slots=True)
class A:
a: int
b: int = dataclasses.field(doc='bb')
print(help(A))
The change: diff --git Lib/dataclasses.py Lib/dataclasses.py
index 2fba32b5ffb..356c3df5874 100644
--- Lib/dataclasses.py
+++ Lib/dataclasses.py
@@ -303,11 +303,12 @@ class Field:
'compare',
'metadata',
'kw_only',
+ 'doc',
'_field_type', # Private: not to be used by user code.
)
def __init__(self, default, default_factory, init, repr, hash, compare,
- metadata, kw_only):
+ metadata, kw_only, doc):
self.name = None
self.type = None
self.default = default
@@ -320,6 +321,7 @@ def __init__(self, default, default_factory, init, repr, hash, compare,
if metadata is None else
types.MappingProxyType(metadata))
self.kw_only = kw_only
+ self.doc = doc
self._field_type = None
@_recursive_repr
@@ -335,6 +337,7 @@ def __repr__(self):
f'compare={self.compare!r},'
f'metadata={self.metadata!r},'
f'kw_only={self.kw_only!r},'
+ f'doc={self.doc!r},'
f'_field_type={self._field_type}'
')')
@@ -402,7 +405,7 @@ def __repr__(self):
# so that a type checker can be told (via overloads) that this is a
# function whose type depends on its parameters.
def field(*, default=MISSING, default_factory=MISSING, init=True, repr=True,
- hash=None, compare=True, metadata=None, kw_only=MISSING):
+ hash=None, compare=True, metadata=None, kw_only=MISSING, doc=None):
"""Return an object to identify dataclass fields.
default is the default value of the field. default_factory is a
@@ -414,7 +417,7 @@ def field(*, default=MISSING, default_factory=MISSING, init=True, repr=True,
comparison functions. metadata, if specified, must be a mapping
which is stored but not otherwise examined by dataclass. If kw_only
is true, the field will become a keyword-only parameter to
- __init__().
+ __init__(). doc is a docstring for this field.
It is an error to specify both default and default_factory.
"""
@@ -422,7 +425,7 @@ def field(*, default=MISSING, default_factory=MISSING, init=True, repr=True,
if default is not MISSING and default_factory is not MISSING:
raise ValueError('cannot specify both default and default_factory')
return Field(default, default_factory, init, repr, hash, compare,
- metadata, kw_only)
+ metadata, kw_only, doc)
def _fields_in_init_order(fields):
@@ -1156,7 +1159,7 @@ def _process_class(cls, init, repr, eq, order, unsafe_hash, frozen,
if weakref_slot and not slots:
raise TypeError('weakref_slot is True but slots is False')
if slots:
- cls = _add_slots(cls, frozen, weakref_slot)
+ cls = _add_slots(cls, frozen, weakref_slot, fields)
abc.update_abstractmethods(cls)
@@ -1191,7 +1194,7 @@ def _get_slots(cls):
raise TypeError(f"Slots of '{cls.__name__}' cannot be determined")
-def _add_slots(cls, is_frozen, weakref_slot):
+def _add_slots(cls, is_frozen, weakref_slot, defined_fields):
# Need to create a new class, since we can't set __slots__
# after a class has been created.
@@ -1208,16 +1211,17 @@ def _add_slots(cls, is_frozen, weakref_slot):
)
# The slots for our class. Remove slots from our base classes. Add
# '__weakref__' if weakref_slot was given, unless it is already present.
- cls_dict["__slots__"] = tuple(
- itertools.filterfalse(
+ cls_dict["__slots__"] = {
+ slot: getattr(defined_fields.get(slot), 'doc', None)
+ for slot in itertools.filterfalse(
inherited_slots.__contains__,
itertools.chain(
# gh-93521: '__weakref__' also needs to be filtered out if
# already present in inherited_slots
field_names, ('__weakref__',) if weakref_slot else ()
)
- ),
- )
+ )
+ }
for field_name in field_names:
# Remove our attributes, if present. They'll still beThe only concern I have is that we change how If others are fine with the change, I will add tests with docs and send a PR. |
|
I think this change is okay. I don't think it would be reasonable for anyone to assume that dataclasses' That said, the documentation at https://docs.python.org/3/reference/datamodel.html says of |
|
It would be nice to have the dict case specifically called out in the data model docs. Right now, all we have is the announcement in the 3.8 whatsnew. |
|
Created #114044 for the documentation issue. |
|
One question I have about this feature: should it be an error to specify |
I think it should be ok, some other tool might also use this
As a separate feature, I guess :) |
That makes sense to me. In this regard, it would be a bit like the metadata field but for a dedicated purpose. |
I'm not sure this answers your question, @sobolevn, but: I mean that I'll grant you that this is an unrelated issue. |
|
My typical questions when adding a feature to dataclasses are:
|
|
I don't think
It does not impact |
|
Hi, is there any update on this? I am working on a configuration module that needs to be able to read default values from the dataclass and I'd like to be able to set the docstring for the field as well. |
|
I am waiting on @ericvsmith's review :) |
If using `slots=True`, the `doc` parameter ends up in the `__slots__` dict. The `doc` parameter is also in the corresponding `Field` object.
…ation (pythonGH-134065) (cherry picked from commit 9d73875) Co-authored-by: Victorien <65306057+Viicos@users.noreply.github.com>
Feature or enhancement
Proposal:
A really nice
__slots__feature is the ability to provide a data dictionary in the form of docstrings. That is also available forpropertyobjects. Consider this example:Running
help(Rocket)shows all the field docstrings which is super helpful:It would be nice is the same can be done with dataclasses that define
__slots__:Has this already been discussed elsewhere?
No response given
Links to previous discussion of this feature:
No response
Linked PRs
docparameter todataclasses.field#114051dataclasses.field()documentation #134065versionaddedindataclasses.field()documentation (GH-134065) #134128The text was updated successfully, but these errors were encountered: