bpo-32216: Update dataclasses documentation (#6913)

Doc/library/dataclasses.rst

@@ -117,50 +117,46 @@ Module-level decorators, classes, and functions
      :meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`, then
      :exc:`ValueError` is raised.
 
-   - ``unsafe_hash``: If ``False`` (the default), the :meth:`__hash__` method
+   - ``unsafe_hash``: If ``False`` (the default), a :meth:`__hash__` method
      is generated according to how ``eq`` and ``frozen`` are set.
 
-     If ``eq`` and ``frozen`` are both true, :func:`dataclass` will
-     generate a :meth:`__hash__` method for you.  If ``eq`` is true
-     and ``frozen`` is false, :meth:`__hash__` will be set to
-     ``None``, marking it unhashable (which it is, since it is
-     mutable).  If ``eq`` is false, :meth:`__hash__` will be left
-     untouched meaning the :meth:`__hash__` method of the superclass
-     will be used (if the superclass is :class:`object`, this means it will
-     fall back to id-based hashing).
-
-     Although not recommended, you can force :func:`dataclass` to
-     create a :meth:`__hash__` method with ``unsafe_hash=True``. This
-     might be the case if your class is logically immutable but can
-     nonetheless be mutated. This is a specialized use case and should
-     be considered carefully.
-
-     If a class already has an explicitely defined :meth:`__hash__`
-     the behavior when adding :meth:`__hash__` is modified.  An
-     expicitely defined :meth:`__hash__` is defined when:
-
-       - :meth:`__eq__` is defined in the class and :meth:`__hash__` is defined
-         with any value other than ``None``.
-
-       - :meth:`__eq__` is defined in the class and any non-``None``
-         :meth:`__hash__` is defined.
-
-       - :meth:`__eq__` is not defined on the class, and any :meth:`__hash__` is
-         defined.
-
-     If ``unsafe_hash`` is true and an explicitely defined :meth:`__hash__`
-     is present, then :exc:`ValueError` is raised.
-
-     If ``unsafe_hash`` is false and an explicitely defined :meth:`__hash__`
-     is present, then no :meth:`__hash__` is added.
-
-     See the Python documentation for more information.
+     :meth:`__hash__` is used by built-in :meth:`hash()`, and when objects are
+     added to hashed collections such as dictionaries and sets.  Having a
+     :meth:`__hash__` implies that instances of the class are immutable.
+     Mutability is a complicated property that depends on the programmer's
+     intent, the existence and behavior of :meth:`__eq__`, and the values of
+     the ``eq`` and ``frozen`` flags in the :func:`dataclass` decorator.
+
+     By default, :func:`dataclass` will not implicitly add a :meth:`__hash__`
+     method unless it is safe to do so.  Neither will it add or change an
+     existing explicitly defined :meth:`__hash__` method.  Setting the class
+     attribute ``__hash__ = None`` has a specific meaning to Python, as
+     described in the :meth:`__hash__` documentation.
+
+     If :meth:`__hash__` is not explicit defined, or if it is set to ``None``,
+     then :func:`dataclass` *may* add an implicit :meth:`__hash__` method.
+     Although not recommended, you can force :func:`dataclass` to create a
+     :meth:`__hash__` method with ``unsafe_hash=True``. This might be the case
+     if your class is logically immutable but can nonetheless be mutated.
+     This is a specialized use case and should be considered carefully.
+
+     Here are the rules governing implicit creation of a :meth:`__hash__`
+     method.  Note that you cannot both have an explicit :meth:`__hash__`
+     method in your dataclass and set ``unsafe_hash=True``; this will result
+     in a :exc:`TypeError`.
+
+     If ``eq`` and ``frozen`` are both true, by default :func:`dataclass` will
+     generate a :meth:`__hash__` method for you.  If ``eq`` is true and
+     ``frozen`` is false, :meth:`__hash__` will be set to ``None``, marking it
+     unhashable (which it is, since it is mutable).  If ``eq`` is false,
+     :meth:`__hash__` will be left untouched meaning the :meth:`__hash__`
+     method of the superclass will be used (if the superclass is
+     :class:`object`, this means it will fall back to id-based hashing).
 
    - ``frozen``: If true (the default is False), assigning to fields will
-     generate an exception.  This emulates read-only frozen instances.
-     If either :meth:`__getattr__` or :meth:`__setattr__` is defined in
-     the class, then :exc:`ValueError` is raised.  See the discussion
-     below.
+     generate an exception.  This emulates read-only frozen instances.  If
+     :meth:`__setattr__` or :meth:`__delattr__` is defined in the class, then
+     :exc:`TypeError` is raised.  See the discussion below.
 
    ``field``\s may optionally specify a default value, using normal
    Python syntax::
@@ -182,17 +178,17 @@ Module-level decorators, classes, and functions
 .. function:: field(*, default=MISSING, default_factory=MISSING, repr=True, hash=None, init=True, compare=True, metadata=None)
 
    For common and simple use cases, no other functionality is
-   required.  There are, however, some Data Class features that
+   required.  There are, however, some dataclass features that
    require additional per-field information.  To satisfy this need for
    additional information, you can replace the default field value
    with a call to the provided :func:`field` function.  For example::
 
      @dataclass
      class C:
-         l: List[int] = field(default_factory=list)
+         mylist: List[int] = field(default_factory=list)
 
      c = C()
-     c.l += [1, 2, 3]
+     c.mylist += [1, 2, 3]
 
    As shown above, the ``MISSING`` value is a sentinel object used to
    detect if the ``default`` and ``default_factory`` parameters are
@@ -222,7 +218,7 @@ Module-level decorators, classes, and functions
      generated equality and comparison methods (:meth:`__eq__`,
      :meth:`__gt__`, et al.).
 
-   - ``hash``: This can be a bool or ``None``.  If True, this field is
+   - ``hash``: This can be a bool or ``None``.  If true, this field is
      included in the generated :meth:`__hash__` method.  If ``None`` (the
      default), use the value of ``compare``: this would normally be
      the expected behavior.  A field should be considered in the hash
@@ -283,17 +279,16 @@ Module-level decorators, classes, and functions
 
 .. function:: fields(class_or_instance)
 
-   Returns a tuple of :class:`Field` objects
-   that define the fields for this Data Class.  Accepts either a Data
-   Class, or an instance of a Data Class.  Raises :exc:`ValueError` if
-   not passed a Data Class or instance of one.  Does not return
-   pseudo-fields which are ``ClassVar`` or ``InitVar``.
+   Returns a tuple of :class:`Field` objects that define the fields for this
+   dataclass.  Accepts either a dataclass, or an instance of a dataclass.
+   Raises :exc:`TypeError` if not passed a dataclass or instance of one.
+   Does not return pseudo-fields which are ``ClassVar`` or ``InitVar``.
 
 .. function:: asdict(instance, *, dict_factory=dict)
 
-   Converts the Data Class ``instance`` to a dict (by using the
-   factory function ``dict_factory``).  Each Data Class is converted
-   to a dict of its fields, as ``name: value`` pairs.  Data Classes, dicts,
+   Converts the dataclass ``instance`` to a dict (by using the
+   factory function ``dict_factory``).  Each dataclass is converted
+   to a dict of its fields, as ``name: value`` pairs.  dataclasses, dicts,
    lists, and tuples are recursed into.  For example::
 
      @dataclass
@@ -303,21 +298,21 @@ Module-level decorators, classes, and functions
 
      @dataclass
      class C:
-          l: List[Point]
+          mylist: List[Point]
 
      p = Point(10, 20)
      assert asdict(p) == {'x': 10, 'y': 20}
 
      c = C([Point(0, 0), Point(10, 4)])
-     assert asdict(c) == {'l': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
+     assert asdict(c) == {'mylist': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
 
-   Raises :exc:`TypeError` if ``instance`` is not a Data Class instance.
+   Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
 
 .. function:: astuple(*, tuple_factory=tuple)
 
-   Converts the Data Class ``instance`` to a tuple (by using the
-   factory function ``tuple_factory``).  Each Data Class is converted
-   to a tuple of its field values.  Data Classes, dicts, lists, and
+   Converts the dataclass ``instance`` to a tuple (by using the
+   factory function ``tuple_factory``).  Each dataclass is converted
+   to a tuple of its field values.  dataclasses, dicts, lists, and
    tuples are recursed into.
 
    Continuing from the previous example::
@@ -325,11 +320,11 @@ Module-level decorators, classes, and functions
      assert astuple(p) == (10, 20)
      assert astuple(c) == ([(0, 0), (10, 4)],)
 
-   Raises :exc:`TypeError` if ``instance`` is not a Data Class instance.
+   Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
 
 .. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
 
-   Creates a new Data Class with name ``cls_name``, fields as defined
+   Creates a new dataclass with name ``cls_name``, fields as defined
    in ``fields``, base classes as given in ``bases``, and initialized
    with a namespace as given in ``namespace``.  ``fields`` is an
    iterable whose elements are each either ``name``, ``(name, type)``,
@@ -341,7 +336,7 @@ Module-level decorators, classes, and functions
    This function is not strictly required, because any Python
    mechanism for creating a new class with ``__annotations__`` can
    then apply the :func:`dataclass` function to convert that class to
-   a Data Class.  This function is provided as a convenience.  For
+   a dataclass.  This function is provided as a convenience.  For
    example::
 
      C = make_dataclass('C',
@@ -369,14 +364,14 @@ Module-level decorators, classes, and functions
    specify fields, raises :exc:`TypeError`.
 
    The newly returned object is created by calling the :meth:`__init__`
-   method of the Data Class.  This ensures that
+   method of the dataclass.  This ensures that
    :meth:`__post_init__`, if present, is also called.
 
    Init-only variables without default values, if any exist, must be
    specified on the call to :func:`replace` so that they can be passed to
    :meth:`__init__` and :meth:`__post_init__`.
 
-   It is an error for :func:`changes` to contain any fields that are
+   It is an error for ``changes`` to contain any fields that are
    defined as having ``init=False``.  A :exc:`ValueError` will be raised
    in this case.
 
@@ -408,7 +403,7 @@ The generated :meth:`__init__` code will call a method named
 :meth:`__post_init__`, if :meth:`__post_init__` is defined on the
 class.  It will normally be called as ``self.__post_init__()``.
 However, if any ``InitVar`` fields are defined, they will also be
-passed to :meth:`__post_init` in the order they were defined in the
+passed to :meth:`__post_init__` in the order they were defined in the
 class.  If no :meth:`__init__` method is generated, then
 :meth:`__post_init__` will not automatically be called.
 
@@ -435,7 +430,7 @@ One of two places where :func:`dataclass` actually inspects the type
 of a field is to determine if a field is a class variable as defined
 in :pep:`526`.  It does this by checking if the type of the field is
 ``typing.ClassVar``.  If a field is a ``ClassVar``, it is excluded
-from consideration as a field and is ignored by the Data Class
+from consideration as a field and is ignored by the dataclass
 mechanisms.  Such ``ClassVar`` pseudo-fields are not returned by the
 module-level :func:`fields` function.
 
@@ -450,7 +445,7 @@ field.  As it is not a true field, it is not returned by the
 module-level :func:`fields` function.  Init-only fields are added as
 parameters to the generated :meth:`__init__` method, and are passed to
 the optional :meth:`__post_init__` method.  They are not otherwise used
-by Data Classes.
+by dataclasses.
 
 For example, suppose a field will be initialzed from a database, if a
 value is not provided when creating the class::
@@ -475,7 +470,7 @@ Frozen instances
 
 It is not possible to create truly immutable Python objects.  However,
 by passing ``frozen=True`` to the :meth:`dataclass` decorator you can
-emulate immutability.  In that case, Data Classes will add
+emulate immutability.  In that case, dataclasses will add
 :meth:`__setattr__` and :meth:`__delattr__` methods to the class.  These
 methods will raise a :exc:`FrozenInstanceError` when invoked.
 
@@ -486,9 +481,9 @@ must use :meth:`object.__setattr__`.
 Inheritance
 -----------
 
-When the Data Class is being created by the :meth:`dataclass` decorator,
+When the dataclass is being created by the :meth:`dataclass` decorator,
 it looks through all of the class's base classes in reverse MRO (that
-is, starting at :class:`object`) and, for each Data Class that it finds,
+is, starting at :class:`object`) and, for each dataclass that it finds,
 adds the fields from that base class to an ordered mapping of fields.
 After all of the base class fields are added, it adds its own fields
 to the ordered mapping.  All of the generated methods will use this
@@ -520,7 +515,7 @@ Default factory functions
    zero arguments when a default value for the field is needed.  For
    example, to create a new instance of a list, use::
 
-     l: list = field(default_factory=list)
+     mylist: list = field(default_factory=list)
 
    If a field is excluded from :meth:`__init__` (using ``init=False``)
    and the field also specifies ``default_factory``, then the default
@@ -532,7 +527,7 @@ Mutable default values
 ----------------------
 
    Python stores default member variable values in class attributes.
-   Consider this example, not using Data Classes::
+   Consider this example, not using dataclasses::
 
      class C:
          x = []
@@ -549,7 +544,7 @@ Mutable default values
    Note that the two instances of class ``C`` share the same class
    variable ``x``, as expected.
 
-   Using Data Classes, *if* this code was valid::
+   Using dataclasses, *if* this code was valid::
 
      @dataclass
      class D:
@@ -571,9 +566,9 @@ Mutable default values
    This has the same issue as the original example using class ``C``.
    That is, two instances of class ``D`` that do not specify a value for
    ``x`` when creating a class instance will share the same copy of
-   ``x``.  Because Data Classes just use normal Python class creation
-   they also share this problem.  There is no general way for Data
-   Classes to detect this condition.  Instead, Data Classes will raise a
+   ``x``.  Because dataclasses just use normal Python class creation
+   they also share this behavior.  There is no general way for Data
+   Classes to detect this condition.  Instead, dataclasses will raise a
    :exc:`TypeError` if it detects a default parameter of type ``list``,
    ``dict``, or ``set``.  This is a partial solution, but it does protect
    against many common errors.
@@ -586,3 +581,12 @@ Mutable default values
          x: list = field(default_factory=list)
 
      assert D().x is not D().x
+
+Exceptions
+----------
+
+.. exception:: FrozenInstanceError
+
+   Raised when an implicitly defined :meth:`__setattr__` or
+   :meth:`__delattr__` is called on a dataclass which was defined with
+   ``frozen=True``.