
    weak -- weak dicts and proxy maps

    Module and documentation by Eric S. Tiedemann <est@hyperreal.org>

This module defines two classes with slightly magical properties that
can in some cases improve both the efficiency and the consistency of
programs.


 dict

A dict behaves almost exactly like a dictionary.  The only difference
is that if there are no other references to a value stored in a weak
dict, it's entry in the dict will disappear.

This is why we use the word `weak'.  The link between the dict and the
object is weak in the sense that it doesn't survive the disappearance
of all other references to the object.

One important restriction is that the objects fetched and stored in a
weak dict must have settable attributes.  This is true of your
garden-variety Python class instance.

Another restriction is that the weakness will not survive if the same
object is stored under multiple keys.  This restriction is usually
trivially met in the situations for which weak dicts are appropriate.


 proxymap(basemap)

A proxymap mediates access to basemap via a weak dict.  As values for
given keys are retrieved from the base map, they're entered into the
weak dict.  If no one's using them, they'll disappear.  If part of the
program is using one of those values and it's refetched from the weak
proxy map, the same object in memory will be returned.

This is most interesting when the base map provides access to values
not originally in memory: something in a file system, or something on
the net, or the result of an extensive computation.  Such base maps
might return a different object in memory each time a given key is
fetched.

Weak proxy maps attempt to implement all the standard Python map
operations, but this is subject to the limitations of the particular
map they are wrapping.

Weak proxy maps can enhance efficiency by caching difficult to obtain
values, but they can also enhance consistency as well.  They ensure
that all parts of the program will see the same object for a given
key, even if the base map doesn't ensure that (as shelves, for
example, certainly don't).

Internally, weak proxy maps do their magic by breaking Python's
reference count model.  This local inconsistency can lead to a more
consistent program overall.  This is because it balances out the
non-participation of certain types of data (objects in shelves,
objects from the net, etc) in Python's object identity model.
