PEP 814: Minor tweaks

peps/pep-0814.rst

@@ -6,6 +6,8 @@ Status: Draft
 Type: Standards Track
 Created: 12-Nov-2025
 Python-Version: 3.15
+Post-History: `13-Nov-2025 <https://discuss.python.org/t/104854>`__
+
 
 Abstract
 ========
@@ -92,8 +94,8 @@ protocol, so all expected methods of iteration are supported::
 Iterating on ``frozendict``, as on ``dict``, uses the insertion order.
 
 
-Hashing
--------
+Hashing and Comparison
+----------------------
 
 ``frozendict`` instances can be hashable just like tuple objects::
 
@@ -114,6 +116,41 @@ Equality test does not depend on the items' order either. Example::
     >>> a == b
     True
 
+It's possible to compare ``frozendict`` to ``dict``. Example::
+
+    >>> frozendict(x=1, y=2) == dict(x=1, y=2)
+    True
+
+
+Union operators
+---------------
+
+It's possible to join two ``frozendict``, or one ``frozendict`` with a
+``dict``, with the merge (``|``) operator. Example::
+
+    >>> frozendict(x=1) | frozendict(y=1)
+    frozendict({'x': 1, 'y': 1})
+    >>> frozendict(x=1) | dict(y=1)
+    frozendict({'x': 1, 'y': 1})
+
+If some keys are in common, the values of the right operand are taken::
+
+    >>> frozendict(x=1, y=2) | frozendict(y=5)
+    frozendict({'x': 1, 'y': 5})
+
+The update operator `|=` does not modify a ``frozendict`` in-place, but
+creates a new ``frozendict``::
+
+    >>> d = frozendict(x=1)
+    >>> copy = d
+    >>> d |= frozendict(y=2)
+    >>> d
+    frozendict({'x': 1, 'y': 2})
+    >>> copy   # left unchanged
+    frozendict({'x': 1})
+
+See also :pep:`584` "Add Union Operators To dict".
+
 
 Typing
 ------
@@ -138,10 +175,12 @@ C API
 
 Add the following APIs:
 
-* ``PyFrozenDict_Type``
-* ``PyFrozenDict_New(collection)`` function
+* ``PyAnyDict_Check(op)`` macro
+* ``PyAnyDict_CheckExact(op)`` macro
 * ``PyFrozenDict_Check()`` macro
 * ``PyFrozenDict_CheckExact()`` macro
+* ``PyFrozenDict_New(collection)`` function
+* ``PyFrozenDict_Type``
 
 Even if ``frozendict`` is not a ``dict`` subclass, it can be used with
 ``PyDict_GetItemRef()`` and similar "PyDict_Get" functions.