PEP 416: Rephrase use cases; add more existing implementations

pep-0416.txt

@@ -25,15 +25,17 @@ hashable. A frozendict is hashable if and only if all values are hashable.
 
 Use cases:
 
- * 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.
+ * Immutable global variable like a default configuration.
+ * Default value of a function parameter. Avoid the issue of mutable default arguments.
+ * Implement a cache: frozendict can be used to store function keywords.
+   frozendict can be used as a key of a mapping or as a member of set.
  * frozendict avoids the need of a lock when the frozendict is shared
    by multiple threads or processes, especially hashable frozendict. It would
    also help to prohibe coroutines (generators + greenlets) to modify the
    global state.
+ * 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.
  * 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
@@ -41,8 +43,6 @@ Use cases:
  * 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.
- * use a frozendict as the default value of function argument: avoid the
-   problem of mutable default argument.
 
 
 Constraints
@@ -137,9 +137,18 @@ Whitelist approach.
    has an implementation issue: it is possible to call again __init__() to
    modify the mapping.
  * PyWebmail contains an ImmutableDict type: `webmail.utils.ImmutableDict
-   <http://pywebmail.cvs.sourceforge.net/viewvc/pywebmail/webmail/webmail/utils/ImmutableDict.py?view=markup>`_.
+   <http://pywebmail.cvs.sourceforge.net/viewvc/pywebmail/webmail/webmail/utils/ImmutableDict.py?revision=1.2&view=markup>`_.
    It is hashable if keys and values are hashable. It is not truly read-only:
    its internal dict is a public attribute.
+ * remember project: `remember.dicts.FrozenDict
+   <https://bitbucket.org/mikegraham/remember/src/tip/remember/dicts.py>`_.
+   It is used to implement a cache: FrozenDict is used to store function callbacks.
+   FrozenDict may be hashable. It has an extra supply_dict() class method to
+   create a FrozenDict from a dict without copying the dict: store the dict as
+   the internal dict. Implementation issue: __init__() can be called to modify
+   the mapping and the hash may differ depending on item creation order. The
+   mapping is not truly read-only: the internal dict is accessible in Python.
+
 
 Blacklist approach: inherit from dict and override write methods to raise an
 exception. It is not truly read-only: it is still possible to call dict methods
@@ -150,11 +159,40 @@ on such "frozen dictionary" to modify it.
    It is hashable if keys and values are hashable. werkzeug project has the
    same code: `werkzeug.datastructures.ImmutableDict
    <https://github.com/mitsuhiko/werkzeug/blob/master/werkzeug/datastructures.py>`_.
+   ImmutableDict is used for global constant (configuration options). The Flask
+   project uses ImmutableDict of werkzeug for its default configuration.
  * SQLAchemy project: `sqlachemy.util.immutabledict
    <http://hg.sqlalchemy.org/sqlalchemy/file/tip/lib/sqlalchemy/util/_collections.py>`_.
-   It is not hashable and has an extra method: union().
+   It is not hashable and has an extra method: union(). immutabledict is used
+   for the default value of parameter of some functions expecting a mapping.
+   Example: mapper_args=immutabledict() in SqlSoup.map().
  * `Frozen dictionaries (Python recipe 414283) <http://code.activestate.com/recipes/414283/>`_
-   by Oren Tirosh. It is hashable if keys and values are hashable.
+   by Oren Tirosh. It is hashable if keys and values are hashable. Included in
+   the following projects:
+
+   * lingospot: `frozendict/frozendict.py
+     <http://code.google.com/p/lingospot/source/browse/trunk/frozendict/frozendict.py>`_
+   * factor-graphics: frozendict type in `python/fglib/util_ext_frozendict.py
+     <https://github.com/ih/factor-graphics/blob/41006fb71a09377445cc140489da5ce8eeb9c8b1/python/fglib/util_ext_frozendict.py>`_
+
+ * The gsakkis-utils project written by George Sakkis includes a frozendict
+   type: `datastructs.frozendict
+   <http://code.google.com/p/gsakkis-utils/source/browse/trunk/datastructs/frozendict.py>`_
+ * characters: `scripts/python/frozendict.py
+   <https://github.com/JasonGross/characters/blob/15a2af5f7861cd33a0dbce70f1569cda74e9a1e3/scripts/python/frozendict.py#L1>`_.
+   It is hashable. __init__() sets __init__ to None.
+ * Old NLTK (1.x): `nltk.util.frozendict
+   <http://nltk.googlecode.com/svn/trunk/nltk-old/src/nltk/util.py>`_. Keys and
+   values must be hashable. __init__() can be called twice to modify the
+   mapping. frozendict is used to "freeze" an object.
+
+Hashable dict: inherit from dict and just add an __hash__ method.
+
+ * `pypy.rpython.lltypesystem.lltype.frozendict
+   <https://bitbucket.org/pypy/pypy/src/1f49987cc2fe/pypy/rpython/lltypesystem/lltype.py#cl-86>`_.
+   It is hashable but don't deny modification of the mapping.
+ * factor-graphics: hashabledict type in `python/fglib/util_ext_frozendict.py
+   <https://github.com/ih/factor-graphics/blob/41006fb71a09377445cc140489da5ce8eeb9c8b1/python/fglib/util_ext_frozendict.py>`_
 
 
 Links