gh-91330: Tests and docs for dataclass descriptor-typed fields (GH-94424)

Co-authored-by: Łukasz Langa <lukasz@langa.pl>

1 files changed, 51 insertions, 0 deletions

diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst
index ec50696..4364ac3 100644
--- a/Doc/library/dataclasses.rst
+++ b/Doc/library/dataclasses.rst
@@ -749,3 +749,54 @@ mutable types as default values for fields::
    ``dict``, or ``set``, unhashable objects are now not allowed as
    default values.  Unhashability is used to approximate
    mutability.
+
+Descriptor-typed fields
+-----------------------
+
+Fields that are assigned :ref:`descriptor objects <descriptors>` as their
+default value have the following special behaviors:
+
+* The value for the field passed to the dataclass's ``__init__`` method is
+  passed to the descriptor's ``__set__`` method rather than overwriting the
+  descriptor object.
+* Similarly, when getting or setting the field, the descriptor's
+  ``__get__`` or ``__set__`` method is called rather than returning or
+  overwriting the descriptor object.
+* To determine whether a field contains a default value, ``dataclasses``
+  will call the descriptor's ``__get__`` method using its class access
+  form (i.e. ``descriptor.__get__(obj=None, type=cls)``.  If the
+  descriptor returns a value in this case, it will be used as the
+  field's default. On the other hand, if the descriptor raises
+  :exc:`AttributeError` in this situation, no default value will be
+  provided for the field.
+
+::
+
+  class IntConversionDescriptor:
+    def __init__(self, *, default):
+      self._default = default
+
+    def __set_name__(self, owner, name):
+      self._name = "_" + name
+
+    def __get__(self, obj, type):
+      if obj is None:
+        return self._default
+
+      return getattr(obj, self._name, self._default)
+
+    def __set__(self, obj, value):
+      setattr(obj, self._name, int(value))
+
+  @dataclass
+  class InventoryItem:
+    quantity_on_hand: IntConversionDescriptor = IntConversionDescriptor(default=100)
+
+  i = InventoryItem()
+  print(i.quantity_on_hand)   # 100
+  i.quantity_on_hand = 2.5    # calls __set__ with 2.5
+  print(i.quantity_on_hand)   # 2
+
+Note that if a field is annotated with a descriptor type, but is not assigned
+a descriptor object as its default value, the field will act like a normal
+field.