[Zodb-checkins] SVN: ZODB/trunk/src/scripts/fsrefs.py Forward-port docstring fix from Zope 2.7 branch, by way of 3.3 branch.

[Tim Peters]

Log message for revision 26412:
Forward-port docstring fix from Zope 2.7 branch, by way of 3.3 branch.

Repaired massive lies I introduced about whether fsrefs requires
application code to be available.  Noted that fsrefs also partly
verifies the sanity of the .fs.index file.




-=-
Modified: ZODB/trunk/src/scripts/fsrefs.py
===================================================================
--- ZODB/trunk/src/scripts/fsrefs.py	2004-07-11 01:49:50 UTC (rev 26411)
+++ ZODB/trunk/src/scripts/fsrefs.py	2004-07-11 01:52:00 UTC (rev 26412)
@@ -20,13 +20,14 @@
 
 fsrefs.py checks object sanity by trying to load the current revision of
 every object O in the database, and also verifies that every object
-directly reachable from each such O exists in the database.  Note that
-application code implementing objects (or at least defining their classes)
-must be available, an d on PYTHONPATH, for fsrefs to work, because objects
-are actually loaded. On a ZEO server, all the application code typically
-isn't present, so it may be difficult to run fsrefs usefully on a ZEO
-server.
+directly reachable from each such O exists in the database.
 
+It's hard to explain exactly what it does because it relies on undocumented
+features in Python's cPickle module:  many of the crucial steps of loading
+an object are taken, but application objects aren't actually created.  This
+saves a lot of time, and allows fsrefs to be run even if the code
+implementing the object classes isn't available.
+
 A read-only connection to the specified FileStorage is made, but it is not
 recommended to run fsrefs against a live FileStorage.  Because a live
 FileStorage is mutating while fsrefs runs, it's not possible for fsrefs to
@@ -36,10 +37,7 @@
 fsrefs doesn't normally produce any output.  If an object fails to load, the
 oid of the object is given in a message saying so, and if -v was specified
 then the traceback corresponding to the load failure is also displayed
-(this is the only effect of the -v flag, and is usually very helpful; -v is
-recommended for normal use).  Note that, as mentioned above, a common
-problem is to get a "failed to load" message simply because the module
-containing the class of the object isn't on PYTHONPATH.
+(this is the only effect of the -v flag).
 
 Two other kinds of errors are also detected, one strongly related to
 "failed to load", when an object O loads OK, and directly refers to a
@@ -57,6 +55,10 @@
    not be produced; a message saying that P can't be loaded will be
    produced when fsrefs later tries to load P, though.
 
+fsrefs also (indirectly) checks that the .index file is sane, because
+fsrefs uses the index to get its idea of what constitutes "all the objects
+in the database".
+
 Note these limitations:  because fsrefs only looks at the current revision
 of objects, it does not attempt to load objects in versions, or non-current
 revisions of objects; therefore fsrefs cannot find problems in versions or