[Zodb-checkins] CVS: ZODB3/ZEO - ClientStorage.py:1.69

[Guido van Rossum]

Update of /cvs-repository/ZODB3/ZEO
In directory cvs.zope.org:/tmp/cvs-serv10368

Modified Files:
	ClientStorage.py 
Log Message:
Add docstrings to every function, class and method in this module.

Also remove unused optional argument 'last' from new_oid() and
'_stuff' from load().


=== ZODB3/ZEO/ClientStorage.py 1.68 => 1.69 === (444/544 lines abridged)
--- ZODB3/ZEO/ClientStorage.py:1.68	Wed Sep 25 18:02:44 2002
+++ ZODB3/ZEO/ClientStorage.py	Tue Oct  1 12:37:03 2002
@@ -11,7 +11,14 @@
 # FOR A PARTICULAR PURPOSE
 #
 ##############################################################################
-"""Network ZODB storage client
+"""The ClientStorage class and the exceptions that it may raise.
+
+Public contents of this module:
+
+ClientStorage -- the main class, implementing the Storage API
+ClientStorageError -- exception raised by ClientStorage
+UnrecognizedResult -- exception raised by ClientStorage
+ClientDisconnected -- exception raised by ClientStorage
 
 $Id$
 """
@@ -45,15 +52,21 @@
     ResolvedSerial = 'rs'
 
 class ClientStorageError(POSException.StorageError):
-    """An error occured in the ZEO Client Storage"""
+    """An error occured in the ZEO Client Storage."""
 
 class UnrecognizedResult(ClientStorageError):
-    """A server call returned an unrecognized result"""
+    """A server call returned an unrecognized result."""
 
 class ClientDisconnected(ClientStorageError, Disconnected):
     """The database storage is disconnected from the storage."""
 
 def get_timestamp(prev_ts=None):
+    """Internal helper to return a unique TimeStamp instance.
+
+    If the optional argument is not None, it must be a TimeStamp; the
+    return value is then guaranteed to be at least 1 microsecond later
+    the argument.
+    """
     t = time.time()
     t = apply(TimeStamp, (time.gmtime(t)[:5] + (t % 60,)))
     if prev_ts is not None:
@@ -61,15 +74,30 @@
     return t
 
 class DisconnectedServerStub:
-    """Raise ClientDisconnected on all attribute access."""
+    """Internal helper class used as a faux RPC stub when disconnected.
+
+    This raises ClientDisconnected on all attribute accesses.

[-=- -=- -=- 444 lines omitted -=- -=- -=-]

 
     def versions(self, max=None):
+        """Storage API: return a sequence of versions in the storage."""
         return self._server.versions(max)
 
-    # below are methods invoked by the StorageServer
+    # Below are methods invoked by the StorageServer
 
     def serialnos(self, args):
+        """Server callback to pass a list of changed (oid, serial) pairs."""
         self._serials.extend(args)
 
     def info(self, dict):
+        """Server callback to update the info dictionary."""
         self._info.update(dict)
 
     def beginVerify(self):
+        """Server callback to signal start of cache validation."""
         self._tfile = tempfile.TemporaryFile(suffix=".inv")
         self._pickler = cPickle.Pickler(self._tfile, 1)
         self._pickler.fast = 1 # Don't use the memo
 
     def invalidateVerify(self, args):
+        """Server callback to invalidate an (oid, version) pair.
+
+        This is called as part of cache validation.
+        """
         # Invalidation as result of verify_cache().
         # Queue an invalidate for the end the verification procedure.
         if self._pickler is None:
@@ -541,6 +737,7 @@
         self._pickler.dump(args)
 
     def endVerify(self):
+        """Server callback to signal end of cache validation."""
         if self._pickler is None:
             return
         self._pickler.dump((0,0))
@@ -558,7 +755,10 @@
         f.close()
 
     def invalidateTrans(self, args):
-        # Invalidation as a result of a transaction.
+        """Server callback to invalidate a list of (oid, version) pairs.
+
+        This is called as the result of a transaction.
+        """
         for oid, version in args:
             self._cache.invalidate(oid, version=version)
             try: