shallow/deep copy; mutable values; clarify PEP 603

Author: vstinner

peps/pep-0814.rst

@@ -80,6 +80,12 @@ Construction
 * ``frozendict(collection, **kwargs)`` combines the two previous
   constructions.
 
+Keys must be hashable and so immutable, but values can be mutable.
+Using immutable values creates a hashtable ``frozendict``.
+
+Creating a ``frozendict`` from a ``dict``, ``frozendict(dict)``, has a
+complexity of *O*\ (*n*): items are copied (shallow copy).
+
 The insertion order is preserved.
 
 
@@ -155,6 +161,29 @@ creates a new ``frozendict``::
 See also :pep:`584` "Add Union Operators To dict".
 
 
+Copy
+----
+
+``frozencopy.copy()`` returns a shallow copy. In CPython, it simply
+returns the same ``frozendict`` (new reference).
+
+Use ``copy.deepcopy()`` to get a deep copy.
+
+Example::
+
+    >>> import copy
+    >>> d = frozendict(x=[])
+    >>> shallow_copy = d.copy()
+    >>> deep_copy = copy.deepcopy(d)
+    >>> d['x'].append(4)
+    >>> d
+    frozendict({'x': [4]})
+    >>> shallow_copy  # modified!
+    frozendict({'x': [4]})
+    >>> deep_copy     # unchanged
+    frozendict({'x': []})
+
+
 Typing
 ------
 
@@ -311,12 +340,10 @@ Relationship to PEP 603 frozenmap
   * ``excluding(key)``
   * ``union(mapping=None, **kw)``
 
-==========  ==============  ==============
-Complexity  ``frozenmap``   ``frozendict``
-==========  ==============  ==============
-Lookup      *O*\ (log *n*)  *O*\ (1)
-Copy        *O*\ (1)        *O*\ (*n*)
-==========  ==============  ==============
+  These methods to mutate a ``frozenmap`` have a complexity of *O*\ (1).
+
+* A mapping lookup (``mapping[key]``) has a complexity of *O*\ (log *n*)
+  with ``frozenmap`` and a complexity of *O*\ (1) with ``frozendict``.
 
 
 Reference Implementation