PEP 416: add more use cases

pep-0416.txt

@@ -24,15 +24,24 @@ key is always mapped to the same value. However, frozendict values can be
 mutable (not hashable). A frozendict is hashable and so immutable if and only
 if all values are hashable (immutable).
 
-Use cases of frozendict:
+Use cases:
 
- * frozendict can be used to implement a cache
- * hashable frozendict can be used as a key of a mapping or as a member of set
- * frozendict helps optimization because the mapping is constant
+ * frozendict lookup can be done at compile time instead of runtime because the
+   mapping is read-only. frozendict can be used instead of a preprocessor to
+   remove conditional code at compilation, like code specific to a debug build.
+ * hashable frozendict can be used as a key of a mapping or as a member of set.
+   frozendict can be used to implement a cache.
  * frozendict avoids the need of a lock when the frozendict is shared
-   by multiple threads or processes, especially hashable frozendict
- * frozendict helps to implement a security sandbox with read-only objects,
-   e.g. freeze __builtins__ mapping
+   by multiple threads or processes, especially hashable frozendict. It would
+   also help to prohibe coroutines (generators + greenlets) to modify the
+   global state.
+ * frozendict helps to implement read-only object proxies for security modules.
+   For example, it would be possible to use frozendict type for __builtins__
+   mapping or type.__dict__. This is possible because frozendict is compatible
+   with the PyDict C API.
+ * frozendict avoids the need of a read-only proxy in some cases. frozendict is
+   faster than a proxy because getting an item in a frozendict is a fast lookup
+   whereas a proxy requires a function call.
 
 
 Constraints
@@ -56,24 +65,24 @@ Implementation
    PyDict_DelItem() raise a TypeError
 
 
-Recipe: immutable dict
+Recipe: hashable dict
 ======================
 
-An immutable mapping can be implemented using frozendict::
+To ensure that a a frozendict is hashable, values can be checked
+before creating the frozendict::
 
     import itertools
 
-    class immutabledict(frozendict):
-        def __new__(cls, *args, **kw):
-            # ensure that all values are immutable
-            for key, value in itertools.chain(args, kw.items()):
-                if not isinstance(value, (int, float, complex, str, bytes)):
-                    hash(value)
-            # frozendict ensures that all keys are immutable
-            return frozendict.__new__(cls, *args, **kw)
-
-        def __repr__(self):
-            return 'immutabledict' + frozendict.__repr__(self)[10:]
+    def hashabledict(*args, **kw):
+        # ensure that all values are hashable
+        for key, value in itertools.chain(args, kw.items()):
+            if isinstance(value, (int, str, bytes, float, frozenset, complex)):
+                # avoid the compute the hash (which may be slow) for builtin
+                # types known to be hashable for any value
+                continue
+            hash(value)
+            # don't check the key: frozendict already checks the key
+        return frozendict.__new__(cls, *args, **kw)
 
 
 Objections
@@ -107,6 +116,13 @@ Links
  * `The case for immutable dictionaries; and the central misunderstanding of PEP 351 <http://www.cs.toronto.edu/~tijmen/programming/immutableDictionaries.html>`_
  * `Frozen dictionaries (Python recipe 414283) <http://code.activestate.com/recipes/414283-frozen-dictionaries/>`_
    by Oren Tirosh
+ * Python security modules implementing read-only object proxies using a C
+   extension:
+
+   * `pysandbox <https://github.com/haypo/pysandbox/>`_
+   * `mxProxy <http://www.egenix.com/products/python/mxBase/mxProxy/>`_
+   * `zope.proxy <http://pypi.python.org/pypi/zope.proxy>`_
+   * `zope.security <http://pypi.python.org/pypi/zope.security>`_
 
 
 Copyright