classification
Title: Assorted weakref docs improvements
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ncoghlan, pitrou, python-dev, sbt
Priority: normal Keywords:

Created on 2013-09-19 08:03 by ncoghlan, last changed 2013-09-22 19:13 by sbt. This issue is now closed.

Messages (6)
msg198046 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-09-19 08:03
I was just looking at weakref.finalize objects trying to figure out if they solve a problem I'm thinking about (they do), and I couldn't figure out from the class documentation ([1]) whether or not I needed to take care of keeping the object returned from weakref.finalize alive.

I don't (the module keeps finalizers alive automatically), but this critical piece of information is only mentioned in the example much further down in the documentation ([2]).

[1] http://docs.python.org/dev/library/weakref#weakref.finalize
[2] http://docs.python.org/dev/library/weakref#finalizer-objects

The 3.4 What's New should also explicitly mention weakref.finalize as an alternative to __del__ methods (perhaps as a comment in the section on PEP 422, perhaps just in the weakref section)
msg198047 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-09-19 08:25
Changing the title, since I spotted a few other problems as well.

The weakref docs still refer to module globals being set to None during shutdown. That is no longer the case. There are also some assumptions about cycles with __del__ methods not being garbage collected, which is no longer true given PEP 442's improvements to module finalization.

I also realised that the introduction of weakref.finalize and the elimination of the "set globals to None" hack gives Python relatively straightforward module destructors [1]:

    import weakref, sys
    mod = sys.modules[__name__]
    def del_this():
        # implicit ref to the module globals from the function body
    weakref.finalize(mod, del_this)

[1] https://mail.python.org/pipermail/import-sig/2013-September/000748.html
msg198057 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-09-19 11:31
Doc patches certainly welcome :-)
msg198067 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-09-19 13:09
I was initially thinking to myself "I have a source checkout right
here, I should just fix it, even though I'm at work and want to go
home"... and then I realised the potential scope of the fixes needed,
given the longstanding misbehaviours these docs assume still exist :)

(I also just realised the clone on my work system is ridiculously
stale, so even updating it will likely take a while at this point)
msg198263 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-09-22 11:27
New changeset caa16423b324 by Nick Coghlan in branch 'default':
Close #19047: weakref doc cleanups
http://hg.python.org/cpython/rev/caa16423b324
msg198296 - (view) Author: Richard Oudkerk (sbt) * (Python committer) Date: 2013-09-22 19:13
Thanks for the doc cleanup -- I am rather busy right now.

Note that stuff does still get replaced by None at shutdown, and this can still produce errors, even if they are much harder to trigger.  If I run the following program

    import _weakref
    import collections

    a = "hello"

    class Foo(object):
        def __del__(self):
            print(a)

    collections.foo = Foo()
    _weakref.foo = Foo()

then depending on the initial hashseed I get a reproducible error:

    $ PYTHONHASHSEED=7 python-release /tmp/bad.py
    Exception ignored in: <bound method Foo.__del__ of <__main__.Foo object at 0xb733db8c>>
    Traceback (most recent call last):
      File "/tmp/bad.py", line 8, in __del__
    TypeError: 'NoneType' object is not callable

(Personally I would like to see a flag set late during shutdown which blocks __del__ methods from running.)
History
Date User Action Args
2013-09-22 19:13:00sbtsetmessages: + msg198296
2013-09-22 11:27:42python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg198263

resolution: fixed
stage: needs patch -> resolved
2013-09-19 13:09:06ncoghlansetmessages: + msg198067
2013-09-19 11:31:36pitrousetnosy: + pitrou, sbt
messages: + msg198057
2013-09-19 08:25:12ncoghlansetmessages: + msg198047
title: Clarify weakref.finalize objects are kept alive automatically -> Assorted weakref docs improvements
2013-09-19 08:03:54ncoghlancreate