Better support for finalization with weakrefs

Doc/library/weakref.rst

 :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>
 
@@ skipping 40 matching lines @@
 :class:`finalize` provides a straight forward way to register a
 cleanup function to be called when an object is garbage collected.
 This is simpler to use than setting up a callback function on a raw
 weak reference.
 
 Most programs should find that using one of these weak container types
 or :class:`finalize` is all they need -- it's not usually necessary to
 create your own weak references directly.  The low-level machinery is
 exposed by the :mod:`weakref` module for the benefit of advanced uses.
 
-.. note::
-
-   Weak references to an object are cleared before the object's :meth:`__del__`
-   is called, to ensure that the weak reference callback (if any) finds the
-   object still alive.
-
 Not all objects can be weakly referenced; those objects which can include class
 instances, functions written in Python (but not in C), instance methods, sets,
 frozensets, some :term:`file objects <file object>`, :term:`generator`\s, type
 objects, sockets, arrays, deques, regular expression pattern objects, and code
 objects.
 
 .. versionchanged:: 3.2
    Added support for thread.lock, threading.Lock, and code objects.
 
 Several built-in types such as :class:`list` and :class:`dict` do not directly
@@ skipping 125 matching lines @@
 
    Return an iterable of the weak references to the values.
 
 
 .. class:: WeakSet([elements])
 
    Set class that keeps weak references to its elements.  An element will be
    discarded when no strong reference to it exists any more.
 
 
-.. class:: finalize(obj, func, *args, **kwds)
+.. class:: finalize(obj, func, *args, **kwargs)
 
    Return a callable finalizer object which will be called when *obj*
    is garbage collected.  When the finalizer is called, if it is alive
    then it is marked as dead and the result of evaluating ``func(*arg,
-   **kwds)`` is returned.  If it is dead then :const:`None` is
+   **kwargs)`` is returned.  If it is dead then :const:`None` is
    returned instead.
 
-   It is important to ensure that *func*, *args* and *kwds* do not own
+   It is important to ensure that *func*, *args* and *kwargs* do not own
    any references to *obj*, either directly or indirectly, since
    otherwise *obj* will never be garbage collected.  In particular,
    *func* must not be a bound method of *obj*.
 
    Exceptions raised by finalizer callbacks during garbage collection
    will be shown on the standard error output, but cannot be
    propagated.  They are handled in the same way as exceptions raised
    from an object's :meth:`__del__` method or a weak reference's
    callback.
 
    When the program exits, each remaining live finalizer is called
    unless its :attr:`atexit` attribute has been set to false.  They
    are called in reverse order of creation.
 
    A finalizer will never invoke its callback during the later part of
    the interpreter shutdown when module globals are liable to have
    been replaced by :const:`None`.
 
    .. method:: __call__()
 
       If *self* is alive then mark it as dead and return the result of
-      calling ``func(*args, **kwds)``.  If *self* is dead then return
+      calling ``func(*args, **kwargs)``.  If *self* is dead then return
       :const:`None`.
 
    .. method:: detach()
 
       If *self* is alive then mark it as dead and return the tuple
-      ``(obj, func, args, kwds)``.  If *self* is dead then return
+      ``(obj, func, args, kwargs)``.  If *self* is dead then return
       :const:`None`.
 
    .. method:: peek()
 
       If *self* is alive then return the tuple ``(obj, func, args,
-      kwds)``.  If *self* is dead then return :const:`None`.
+      kwargs)``.  If *self* is dead then return :const:`None`.
 
    .. attribute:: alive
 
       Property which is true if the finalizer is alive, false otherwise.
 
    .. attribute:: atexit
 
       A writable boolean property which by default is true.  When the
       program exits, it calls all remaining live finalizers for which
       :attr:`.atexit` is true.  They are called in reverse order of
@@ skipping 172 matching lines @@
     >>> del obj                 # callback not called because finalizer dead
 
 You can unregister a finalizer using its :meth:`~finalize.detach`
 method.  This kills the finalizer and returns the arguments passed to
 the constructor when it was created.
 
     >>> obj = Object()
     >>> f = weakref.finalize(obj, callback, 1, 2, z=3)
     >>> f.detach()                                           #doctest:+ELLIPSIS
     (<__main__.Object object ...>, <function callback ...>, (1, 2), {'z': 3})
-    >>> newobj, func, args, kwds = _
+    >>> newobj, func, args, kwargs = _
     >>> assert not f.alive
     >>> assert newobj is obj
-    >>> assert func(*args, **kwds) == 6
+    >>> assert func(*args, **kwargs) == 6
     CALLBACK
 
 Unless you set the :attr:`~finalize.atexit` attribute to
 :const:`False`, a finalizer will be called when the program exit if it
 is still alive.  For instance
 
     >>> obj = Object()
     >>> weakref.finalize(obj, print, "obj dead or exiting")  #doctest:+ELLIPSIS
     <finalize object at ...; for 'Object' at ...>
     >>> exit()                                               #doctest:+SKIP
@@ skipping 22 matching lines @@
         def detach(self):
             if not self._finalizer.detach():
                 raise IOError("already closed or detached")
             return self._fd
 
         def fileno(self):
             if not self._finalizer.alive:
                 raise IOError("already closed or detached")
             return self._fd
 
         __index__ = __int__ = fileno

[asvetlov, 2012/08/20 08:30:32]

I think this line isn't required for docs

 
         @property
         def closed(self):
             return not self._finalizer.alive