follows a field with a default value. This is true whether this
occurs in a single class, or as a result of class inheritance.
-.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING)
+.. function:: field(*, default=MISSING, default_factory=MISSING, init=True, repr=True, hash=None, compare=True, metadata=None, kw_only=MISSING, doc=None)
For common and simple use cases, no other functionality is
required. There are, however, some dataclass features that
.. versionadded:: 3.10
+ - ``doc``: optional docstring for this field.
+
+ .. versionadded:: 3.13
+
If the default value of a field is specified by a call to
:func:`!field`, then the class attribute for this field will be
replaced by the specified *default* value. If *default* is not
'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
if metadata is None else
types.MappingProxyType(metadata))
self.kw_only = kw_only
+ self.doc = doc
self._field_type = None
@recursive_repr()
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}'
')')
# 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
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 an optional docstring for this field.
It is an error to specify both default and default_factory.
"""
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):
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)
return False
-def _add_slots(cls, is_frozen, weakref_slot):
+def _create_slots(defined_fields, inherited_slots, field_names, 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.
+ seen_docs = False
+ slots = {}
+ 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 ()
+ )
+ ):
+ doc = getattr(defined_fields.get(slot), 'doc', None)
+ if doc is not None:
+ seen_docs = True
+ slots.update({slot: doc})
+
+ # We only return dict if there's at least one doc member,
+ # otherwise we return tuple, which is the old default format.
+ if seen_docs:
+ return slots
+ return tuple(slots)
+
+
+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, and the @dataclass decorator is called
# after the class is created.
inherited_slots = set(
itertools.chain.from_iterable(map(_get_slots, cls.__mro__[1:-1]))
)
- # 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(
- 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 ()
- )
- ),
+
+ cls_dict["__slots__"] = _create_slots(
+ defined_fields, inherited_slots, field_names, weakref_slot,
)
for field_name in field_names:
x: int = field(default=1, default_factory=int)
def test_field_repr(self):
- int_field = field(default=1, init=True, repr=False)
+ int_field = field(default=1, init=True, repr=False, doc='Docstring')
int_field.name = "id"
repr_output = repr(int_field)
expected_output = "Field(name='id',type=None," \
"init=True,repr=False,hash=None," \
"compare=True,metadata=mappingproxy({})," \
f"kw_only={MISSING!r}," \
+ "doc='Docstring'," \
"_field_type=None)"
self.assertEqual(repr_output, expected_output)
j: str
h: str
- self.assertEqual(Base.__slots__, ('y', ))
+ self.assertEqual(Base.__slots__, ('y',))
@dataclass(slots=True)
class Derived(Base):
k: str
h: str
- self.assertEqual(Derived.__slots__, ('z', ))
+ self.assertEqual(Derived.__slots__, ('z',))
@dataclass
class AnotherDerived(Base):
self.assertNotIn('__slots__', AnotherDerived.__dict__)
+ def test_slots_with_docs(self):
+ class Root:
+ __slots__ = {'x': 'x'}
+
+ @dataclass(slots=True)
+ class Base(Root):
+ y1: int = field(doc='y1')
+ y2: int
+
+ self.assertEqual(Base.__slots__, {'y1': 'y1', 'y2': None})
+
+ @dataclass(slots=True)
+ class Child(Base):
+ z1: int = field(doc='z1')
+ z2: int
+
+ self.assertEqual(Child.__slots__, {'z1': 'z1', 'z2': None})
+
def test_cant_inherit_from_iterator_slots(self):
class Root:
projects / thirdparty / Python / cpython.git / commitdiff
