[Zodb-checkins] SVN: ZODB/trunk/src/persistent/interfaces.py document _p_invalidate()

[Fred L. Drake, Jr.]

Log message for revision 28249:
  document _p_invalidate()

Changed:
  U   ZODB/trunk/src/persistent/interfaces.py

-=-
Modified: ZODB/trunk/src/persistent/interfaces.py
===================================================================
--- ZODB/trunk/src/persistent/interfaces.py	2004-10-26 14:26:33 UTC (rev 28248)
+++ ZODB/trunk/src/persistent/interfaces.py	2004-10-26 14:49:14 UTC (rev 28249)
@@ -140,7 +140,8 @@
           - call _p_deactivate()
           - set _p_changed to None
 
-    There is one way to invalidate an object:  delete its _p_changed
+    There are two ways to invalidate an object: call the
+    _p_invalidate() method (preferred) or delete its _p_changed
     attribute.  This cannot be ignored, and is used when semantics
     require invalidation.  Normally, an invalidated object transitions
     to the ghost state.  However, some objects cannot be ghosts.  When
@@ -226,6 +227,15 @@
         may choose to keep an object in the saved state.
         """
 
+    def _p_invalidate():
+        """Invalidate the object.
+
+        Invalidate the object.  This causes any data to be thrown
+        away, even if the object is inthe changed state.  The object
+        is moved to the ghost state; further accesses will cause
+        object data to be reloaded.
+        """
+
 class IPersistentNoReadConflicts(IPersistent):
     def _p_independent():
         """Hook for subclasses to prevent read conflict errors.