Move the 3k reST doc tree in place.

1 files changed, 330 insertions, 0 deletions

diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
new file mode 100644
index 0000000..c5857ba
--- /dev/null
+++ b/Doc/library/weakref.rst
@@ -0,0 +1,330 @@
+
+:mod:`weakref` --- Weak references
+==================================
+
+.. module:: weakref
+   :synopsis: Support for weak references and weak dictionaries.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
+.. moduleauthor:: Martin von Löwis <martin@loewis.home.cs.tu-berlin.de>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+.. versionadded:: 2.1
+
+The :mod:`weakref` module allows the Python programmer to create :dfn:`weak
+references` to objects.
+
+.. % When making changes to the examples in this file, be sure to update
+.. % Lib/test/test_weakref.py::libreftest too!
+
+In the following, the term :dfn:`referent` means the object which is referred to
+by a weak reference.
+
+A weak reference to an object is not enough to keep the object alive: when the
+only remaining references to a referent are weak references, garbage collection
+is free to destroy the referent and reuse its memory for something else.  A
+primary use for weak references is to implement caches or mappings holding large
+objects, where it's desired that a large object not be kept alive solely because
+it appears in a cache or mapping.  For example, if you have a number of large
+binary image objects, you may wish to associate a name with each.  If you used a
+Python dictionary to map names to images, or images to names, the image objects
+would remain alive just because they appeared as values or keys in the
+dictionaries.  The :class:`WeakKeyDictionary` and :class:`WeakValueDictionary`
+classes supplied by the :mod:`weakref` module are an alternative, using weak
+references to construct mappings that don't keep objects alive solely because
+they appear in the mapping objects.  If, for example, an image object is a value
+in a :class:`WeakValueDictionary`, then when the last remaining references to
+that image object are the weak references held by weak mappings, garbage
+collection can reclaim the object, and its corresponding entries in weak
+mappings are simply deleted.
+
+:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
+in their implementation, setting up callback functions on the weak references
+that notify the weak dictionaries when a key or value has been reclaimed by
+garbage collection.  Most programs should find that using one of these weak
+dictionary types is all they need -- it's not usually necessary to create your
+own weak references directly.  The low-level machinery used by the weak
+dictionary implementations is exposed by the :mod:`weakref` module for the
+benefit of advanced uses.
+
+Not all objects can be weakly referenced; those objects which can include class
+instances, functions written in Python (but not in C), methods (both bound and
+unbound), sets, frozensets, file objects, generators, type objects, DBcursor
+objects from the :mod:`bsddb` module, sockets, arrays, deques, and regular
+expression pattern objects.
+
+.. versionchanged:: 2.4
+   Added support for files, sockets, arrays, and patterns.
+
+Several builtin types such as :class:`list` and :class:`dict` do not directly
+support weak references but can add support through subclassing::
+
+   class Dict(dict):
+       pass
+
+   obj = Dict(red=1, green=2, blue=3)   # this object is weak referencable
+
+Extension types can easily be made to support weak references; see
+:ref:`weakref-support`.
+
+
+.. class:: ref(object[, callback])
+
+   Return a weak reference to *object*.  The original object can be retrieved by
+   calling the reference object if the referent is still alive; if the referent is
+   no longer alive, calling the reference object will cause :const:`None` to be
+   returned.  If *callback* is provided and not :const:`None`, and the returned
+   weakref object is still alive, the callback will be called when the object is
+   about to be finalized; the weak reference object will be passed as the only
+   parameter to the callback; the referent will no longer be available.
+
+   It is allowable for many weak references to be constructed for the same object.
+   Callbacks registered for each weak reference will be called from the most
+   recently registered callback to the oldest registered callback.
+
+   Exceptions raised by the callback will be noted on the standard error output,
+   but cannot be propagated; they are handled in exactly the same way as exceptions
+   raised from an object's :meth:`__del__` method.
+
+   Weak references are hashable if the *object* is hashable.  They will maintain
+   their hash value even after the *object* was deleted.  If :func:`hash` is called
+   the first time only after the *object* was deleted, the call will raise
+   :exc:`TypeError`.
+
+   Weak references support tests for equality, but not ordering.  If the referents
+   are still alive, two references have the same equality relationship as their
+   referents (regardless of the *callback*).  If either referent has been deleted,
+   the references are equal only if the reference objects are the same object.
+
+   .. versionchanged:: 2.4
+      This is now a subclassable type rather than a factory function; it derives from
+      :class:`object`.
+
+
+.. function:: proxy(object[, callback])
+
+   Return a proxy to *object* which uses a weak reference.  This supports use of
+   the proxy in most contexts instead of requiring the explicit dereferencing used
+   with weak reference objects.  The returned object will have a type of either
+   ``ProxyType`` or ``CallableProxyType``, depending on whether *object* is
+   callable.  Proxy objects are not hashable regardless of the referent; this
+   avoids a number of problems related to their fundamentally mutable nature, and
+   prevent their use as dictionary keys.  *callback* is the same as the parameter
+   of the same name to the :func:`ref` function.
+
+
+.. function:: getweakrefcount(object)
+
+   Return the number of weak references and proxies which refer to *object*.
+
+
+.. function:: getweakrefs(object)
+
+   Return a list of all weak reference and proxy objects which refer to *object*.
+
+
+.. class:: WeakKeyDictionary([dict])
+
+   Mapping class that references keys weakly.  Entries in the dictionary will be
+   discarded when there is no longer a strong reference to the key.  This can be
+   used to associate additional data with an object owned by other parts of an
+   application without adding attributes to those objects.  This can be especially
+   useful with objects that override attribute accesses.
+
+   .. note::
+
+      Caution:  Because a :class:`WeakKeyDictionary` is built on top of a Python
+      dictionary, it must not change size when iterating over it.  This can be
+      difficult to ensure for a :class:`WeakKeyDictionary` because actions performed
+      by the program during iteration may cause items in the dictionary to vanish "by
+      magic" (as a side effect of garbage collection).
+
+:class:`WeakKeyDictionary` objects have the following additional methods.  These
+expose the internal references directly.  The references are not guaranteed to
+be "live" at the time they are used, so the result of calling the references
+needs to be checked before being used.  This can be used to avoid creating
+references that will cause the garbage collector to keep the keys around longer
+than needed.
+
+
+.. method:: WeakKeyDictionary.iterkeyrefs()
+
+   Return an iterator that yields the weak references to the keys.
+
+   .. versionadded:: 2.5
+
+
+.. method:: WeakKeyDictionary.keyrefs()
+
+   Return a list of weak references to the keys.
+
+   .. versionadded:: 2.5
+
+
+.. class:: WeakValueDictionary([dict])
+
+   Mapping class that references values weakly.  Entries in the dictionary will be
+   discarded when no strong reference to the value exists any more.
+
+   .. note::
+
+      Caution:  Because a :class:`WeakValueDictionary` is built on top of a Python
+      dictionary, it must not change size when iterating over it.  This can be
+      difficult to ensure for a :class:`WeakValueDictionary` because actions performed
+      by the program during iteration may cause items in the dictionary to vanish "by
+      magic" (as a side effect of garbage collection).
+
+:class:`WeakValueDictionary` objects have the following additional methods.
+These method have the same issues as the :meth:`iterkeyrefs` and :meth:`keyrefs`
+methods of :class:`WeakKeyDictionary` objects.
+
+
+.. method:: WeakValueDictionary.itervaluerefs()
+
+   Return an iterator that yields the weak references to the values.
+
+   .. versionadded:: 2.5
+
+
+.. method:: WeakValueDictionary.valuerefs()
+
+   Return a list of weak references to the values.
+
+   .. versionadded:: 2.5
+
+
+.. data:: ReferenceType
+
+   The type object for weak references objects.
+
+
+.. data:: ProxyType
+
+   The type object for proxies of objects which are not callable.
+
+
+.. data:: CallableProxyType
+
+   The type object for proxies of callable objects.
+
+
+.. data:: ProxyTypes
+
+   Sequence containing all the type objects for proxies.  This can make it simpler
+   to test if an object is a proxy without being dependent on naming both proxy
+   types.
+
+
+.. exception:: ReferenceError
+
+   Exception raised when a proxy object is used but the underlying object has been
+   collected.  This is the same as the standard :exc:`ReferenceError` exception.
+
+
+.. seealso::
+
+   :pep:`0205` - Weak References
+      The proposal and rationale for this feature, including links to earlier
+      implementations and information about similar features in other languages.
+
+
+.. _weakref-objects:
+
+Weak Reference Objects
+----------------------
+
+Weak reference objects have no attributes or methods, but do allow the referent
+to be obtained, if it still exists, by calling it::
+
+   >>> import weakref
+   >>> class Object:
+   ...     pass
+   ...
+   >>> o = Object()
+   >>> r = weakref.ref(o)
+   >>> o2 = r()
+   >>> o is o2
+   True
+
+If the referent no longer exists, calling the reference object returns
+:const:`None`::
+
+   >>> del o, o2
+   >>> print r()
+   None
+
+Testing that a weak reference object is still live should be done using the
+expression ``ref() is not None``.  Normally, application code that needs to use
+a reference object should follow this pattern::
+
+   # r is a weak reference object
+   o = r()
+   if o is None:
+       # referent has been garbage collected
+       print "Object has been deallocated; can't frobnicate."
+   else:
+       print "Object is still live!"
+       o.do_something_useful()
+
+Using a separate test for "liveness" creates race conditions in threaded
+applications; another thread can cause a weak reference to become invalidated
+before the weak reference is called; the idiom shown above is safe in threaded
+applications as well as single-threaded applications.
+
+Specialized versions of :class:`ref` objects can be created through subclassing.
+This is used in the implementation of the :class:`WeakValueDictionary` to reduce
+the memory overhead for each entry in the mapping.  This may be most useful to
+associate additional information with a reference, but could also be used to
+insert additional processing on calls to retrieve the referent.
+
+This example shows how a subclass of :class:`ref` can be used to store
+additional information about an object and affect the value that's returned when
+the referent is accessed::
+
+   import weakref
+
+   class ExtendedRef(weakref.ref):
+       def __init__(self, ob, callback=None, **annotations):
+           super(ExtendedRef, self).__init__(ob, callback)
+           self.__counter = 0
+           for k, v in annotations.iteritems():
+               setattr(self, k, v)
+
+       def __call__(self):
+           """Return a pair containing the referent and the number of
+           times the reference has been called.
+           """
+           ob = super(ExtendedRef, self).__call__()
+           if ob is not None:
+               self.__counter += 1
+               ob = (ob, self.__counter)
+           return ob
+
+
+.. _weakref-example:
+
+Example
+-------
+
+This simple example shows how an application can use objects IDs to retrieve
+objects that it has seen before.  The IDs of the objects can then be used in
+other data structures without forcing the objects to remain alive, but the
+objects can still be retrieved by ID if they do.
+
+.. % Example contributed by Tim Peters.
+
+::
+
+   import weakref
+
+   _id2obj_dict = weakref.WeakValueDictionary()
+
+   def remember(obj):
+       oid = id(obj)
+       _id2obj_dict[oid] = obj
+       return oid
+
+   def id2obj(oid):
+       return _id2obj_dict[oid]
+