Added a utility module for getting object-referrer information.

It isn't actually a script but it is used in the same spirit.  Maybe
it will be a script someday.

src/ZODB/scripts/referrers.py

+##############################################################################
+#
+# Copyright (c) 2005 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Compute a table of object id referrers
+
+$Id$
+"""
+
+from ZODB.serialize import referencesf
+
+def referrers(storage):
+    result = {}
+    for transaction in storage.iterator():
+        for record in transaction:
+            for oid in referencesf(record.data):
+                result.setdefault(oid, []).append((record.oid, record.tid))
+    return result
+
+                
+            

src/ZODB/scripts/referrers.txt

+Getting Object Referrers
+========================
+
+The referrers module provides a way to get object referrers.  It
+provides a referrers method that takes an iterable storage object.  It
+returns a dictionary mapping object ids to lists of referrer object
+versions, which each version is a tuple an object id nd serial
+nummber.
+
+To see how this works, we'll create a small database:
+
+    >>> import transaction
+    >>> from persistent.mapping import PersistentMapping
+    >>> from ZODB.FileStorage import FileStorage
+    >>> from ZODB.DB import DB
+    >>> import os, tempfile
+    >>> dest = tempfile.mkdtemp()
+    >>> fs = FileStorage(os.path.join(dest, 'Data.fs'))
+    >>> db = DB(fs)
+    >>> conn = db.open()
+    >>> conn.root()['a'] = PersistentMapping()
+    >>> conn.root()['b'] = PersistentMapping()
+    >>> transaction.commit()
+    >>> roid = conn.root()._p_oid
+    >>> aoid = conn.root()['a']._p_oid
+    >>> boid = conn.root()['b']._p_oid
+    >>> s1 = conn.root()['b']._p_serial
+
+    >>> conn.root()['a']['b'] = conn.root()['b']
+    >>> transaction.commit()
+    >>> s2 = conn.root()['a']._p_serial
+
+Now we'll get the storage and compute the referrers:
+
+    >>> import ZODB.scripts.referrers
+    >>> referrers = ZODB.scripts.referrers.referrers(fs)
+
+    >>> referrers[boid] == [(roid, s1), (aoid, s2)]
+    True
+

src/ZODB/scripts/tests.py

+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""XXX short summary goes here.
+
+$Id$
+"""
+import unittest
+from zope.testing import doctest
+
+def test_suite():
+    return unittest.TestSuite((
+        doctest.DocFileSuite('referrers.txt'),
+        ))
+