Union operators

Author: vstinner

peps/pep-0814.rst

@@ -122,6 +122,36 @@ It's possible to compare ``frozendict`` to ``dict``. Example::
     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
 ------