Changed to reflect unsafe_hash and the other discussions on python-dev.

pep-0557.rst

@@ -6,7 +6,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 02-Jun-2017
 Python-Version: 3.7
-Post-History: 08-Sep-2017, 25-Nov-2017, 30-Nov-2017, 01-Dec-2017, 02-Dec-2017, 06-Jan-2018
+Post-History: 08-Sep-2017, 25-Nov-2017, 30-Nov-2017, 01-Dec-2017, 02-Dec-2017, 06-Jan-2018, 04-Mar-2018
 Resolution: https://mail.python.org/pipermail/python-dev/2017-December/151034.html
 
 Notice for Reviewers
@@ -170,7 +170,7 @@ The ``dataclass`` decorator is typically used with no parameters and
 no parentheses.  However, it also supports the following logical
 signature::
 
-  def dataclass(*, init=True, repr=True, eq=True, order=False, hash=None, frozen=False)
+  def dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
 
 If ``dataclass`` is used just as a simple decorator with no
 parameters, it acts as if it has the default values documented in this
@@ -184,7 +184,7 @@ signature.  That is, these three uses of ``@dataclass`` are equivalent::
   class C:
       ...
 
-  @dataclass(init=True, repr=True, eq=True, order=False, hash=None, frozen=False)
+  @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False)
   class C:
       ...
 
@@ -200,10 +200,15 @@ The parameters to ``dataclass`` are:
   are not included.  For example:
   ``InventoryItem(name='widget', unit_price=3.0, quantity_on_hand=10)``.
 
-- ``eq``: If true (the default), ``__eq__`` and ``__ne__`` methods
-  will be generated.  These compare the class as if it were a tuple of
-  its fields, in order.  Both instances in the comparison must be of
-  the identical type.
+  If the class already defines ``__repr__``, this parameter is
+  ignored.
+
+- ``eq``: If true (the default), an ``__eq__`` method will be
+  generated.  This method compares the class as if it were a tuple of its
+  fields, in order.  Both instances in the comparison must be of the
+  identical type.
+
+  If the class already defines ``__eq__``, this parameter is ignored.
 
 - ``order``: If true (the default is False), ``__lt__``, ``__le__``,
   ``__gt__``, and ``__ge__`` methods will be generated.  These compare
@@ -211,9 +216,11 @@ The parameters to ``dataclass`` are:
   instances in the comparison must be of the identical type.  If
   ``order`` is true and ``eq`` is false, a ``ValueError`` is raised.
 
-- ``hash``: Either a bool or ``None``.  If ``None`` (the default), the
-  ``__hash__`` method is generated according to how ``eq`` and
-  ``frozen`` are set.
+  If the class already defines any of ``__lt__``, ``__le__``,
+  ``__gt__``, or ``__ge__``, then ``ValueError`` is raised.
+
+- ``unsafe_hash``: If ``False`` (the default), the ``__hash__`` method
+  is generated according to how ``eq`` and ``frozen`` are set.
 
   If ``eq`` and ``frozen`` are both true, Data Classes will generate a
   ``__hash__`` method for you.  If ``eq`` is true and ``frozen`` is
@@ -224,15 +231,36 @@ The parameters to ``dataclass`` are:
   to id-based hashing).
 
   Although not recommended, you can force Data Classes to create a
-  ``__hash__`` method with ``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.
+  ``__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 ``__hash__`` the
+  behavior when adding ``__hash__`` is modified.  An expicitely
+  defined ``__hash__`` is defined when:
+
+    - ``__eq__`` is defined in the class and ``__hash__`` is defined
+      with any value other than ``None``.
+
+    - ``__eq__`` is defined in the class and any non-``None``
+      ``__hash__`` is defined.
+
+    - ``__eq__`` is not defined on the class, and any ``__hash__`` is
+      defined.
+
+  If ``unsafe_hash`` is true and an explicitely defined ``__hash__``
+  is present, then ``ValueError`` is raised.
+
+  If ``unsafe_hash`` is false and an explicitely defined ``__hash__``
+  is present, then no ``__hash__`` is added.
 
   See the Python documentation [#]_ for more information.
 
 - ``frozen``: If true (the default is False), assigning to fields will
   generate an exception.  This emulates read-only frozen instances.
-  See the discussion below.
+  If either ``__getattr__`` or ``__setattr__`` is defined in the
+  class, then ``ValueError`` is raised.  See the discussion below.
 
 ``field``\s may optionally specify a default value, using normal
 Python syntax::
@@ -533,7 +561,7 @@ Module level helper functions
 
 - ``fields(class_or_instance)``: Returns a tuple of ``Field`` objects
   that define the fields for this Data Class.  Accepts either a Data
-  Class, or an instance of a Data Class.  Raises `ValueError` if not
+  Class, or an instance of a Data Class.  Raises ``ValueError`` if not
   passed a Data Class or instance of one.  Does not return
   pseudo-fields which are ``ClassVar`` or ``InitVar``.