[Zodb-checkins] CVS: Zope3/src/ZODB - Connection.py:1.140

Jeremy Hylton jeremy at zope.com
Tue Mar 16 11:18:25 EST 2004


Update of /cvs-repository/Zope3/src/ZODB
In directory cvs.zope.org:/tmp/cvs-serv10285

Modified Files:
	Connection.py 
Log Message:
Add rST version of epydoc markup.


=== Zope3/src/ZODB/Connection.py 1.139 => 1.140 ===
--- Zope3/src/ZODB/Connection.py:1.139	Sat Mar 13 02:48:11 2004
+++ Zope3/src/ZODB/Connection.py	Tue Mar 16 11:18:20 2004
@@ -81,6 +81,7 @@
     that you will need to use.
     
     Synchronization
+    ---------------
 
     A Connection instance is not thread-safe.  It is designed to
     support a thread model where each thread has its own transaction.
@@ -102,30 +103,22 @@
 
     XXX Mention the database pool.
 
-    The Connection plays several different roles.
+    :Groups:
+    
+      - `User Methods`: root, get, add, close, db, sync, isReadOnly,
+        cacheGC, cacheFullSweep, cacheMinimize, getVersion,
+        modifiedInVersion
+      - `Experimental Methods`: setLocalTransaction, getTransaction,
+        onCloseCallbacks
+      - `Transaction Data Manager Methods`: tpc_begin, tpc_vote,
+        tpc_finish, tpc_abort, sortKey, abort, commit, commit_sub,
+        abort_sub
+      - `Database Invalidation Methods`: invalidate, _setDB
+      - `IPersistentDataManager Methods`: setstate, register,
+        setklassstate
+      - `Other Methods`: oldstate, exchange, getDebugInfo, setDebugInfo,
+        getTransferCounts
 
-    It provides a user-visible interface for accessing objects.  These
-    methods are designed for use by application code: root(), get(),
-    add(), close(), db(), sync(), isReadOnly(), cacheGC(),
-    cacheMinimize(), getVersion(), modifiedInVersion().
-
-    The Connection also interacts with the transaction manager to
-    store changes and make changes by other clients visible.  These
-    methods participate in that collaoration: tpc_begin(), tpc_vote(),
-    tpc_finish(), tpc_abort(), sortKey(), abort(), commit(),
-    commit_sub(), abort_sub().
-
-    The Connection normally used the standard get_transaction()
-    mechanism for finding the current Transaction.  The experimental
-    setLocalTransaction() and getLocationTransaction() methods can be
-    used to provide a fixed Transaction.
-
-    The Connection also implements the IPersistentDataManager
-    interface, which provides methods for persistent objects to load
-    their state and register changes.  The methods are setstate(),
-    register(), setklassstate().
-
-    $Id$
     """
 
     _tmp = None
@@ -239,12 +232,18 @@
         Applications seldom need to call this method, because objects
         are loaded transparently during attribute lookup.
 
-        get() raises KeyError if oid does not exist.  It is possible
-        that an object does not exist as of the current transaction,
-        but existed in the past.  It may even exist again in the future, if
-        the transaction that removed it is undone.
-        
-        get() raises RuntimeError if the connectio is closed.
+        :return: persistent object corresponding to `oid`
+
+        :Parameters:
+          - `oid`: an object id
+
+        :Exceptions:
+
+          - `KeyError`: if oid does not exist.  It is possible that an
+            object does not exist as of the current transaction, but
+            existed in the past.  It may even exist again in the
+            future, if the transaction that removed it is undone.
+          - `RuntimeError`:  if the connection is closed.
         """
         if self._storage is None:
             # XXX Should this be a ZODB-specific exception?
@@ -286,12 +285,14 @@
         must implement the IPersistent interface and must not
         already be associated with a Connection.
 
-        add() raises TypeError if obj is not a persistent object.
+        :Parameters:
+          - `obj`: a Persistent object
 
-        add() raises InvalidObjectReference if obj is already associated
-        with another connection.
-
-        add() raises RuntimeError if the connection is closed.
+        :Exceptions:
+          - `TypeError`: if obj is not a persistent object.
+          - `InvalidObjectReference`: if obj is already associated
+            with another connection.
+          - `RuntimeError`: if the connection is closed.
         """
         if self._storage is None:
             # XXX Should this be a ZODB-specific exception?
@@ -327,6 +328,9 @@
         was closed will be processed.
 
         If resetCaches() was called, the cache will be cleared.
+        
+        :Parameters:
+          - `odb`: that database that owns the Connection
         """
 
         # XXX Why do we go to all the trouble of setting _db and
@@ -395,8 +399,8 @@
         it into a ghost.  It is possible for individual objects to
         remain active.
 
-        The dt argument is provided only for backwards compatibility.
-        It is ignored.
+        :Parameters:
+          - `dt`: ignored.  It is provided only for backwards compatibility.
         """
         if dt is not None:
             warnings.warn("The dt argument to cacheMinimize is ignored.",
@@ -418,6 +422,9 @@
 
         The callable, f, will be called at most once, the next time
         the Connection is closed.
+
+        :Parameters:
+          - `f`: object that will be called on `close`
         """
         if self.__onCloseCallbacks is None:
             self.__onCloseCallbacks = []
@@ -593,8 +600,10 @@
 
         The DB calls this method, even when the Connection is closed.
 
-        tid is the storage-level id of the transaction that committed.
-        oids is a set of oids, represented as a dict with oids as keys.
+        :Parameters:
+          - `tid`: the storage-level id of the transaction that committed
+          - `oids`: oids is a set of oids, represented as a dict with oids
+            as keys. 
         """
         self._inv_lock.acquire()
         try:
@@ -768,12 +777,19 @@
     def oldstate(self, obj, tid):
         """Return copy of obj that was written by tid.
 
-        obj is a persistent object from this Connection.  An earlier
-        version of obj's state will be loaded using tid, the id of a
-        transaction that wrote an earlier revision.
+        XXX The returned object does not have the typical metdata
+        (_p_jar, _p_oid, _p_serial) set.  I'm not sure how references
+        to other peristent objects are handled.
 
-        oldstate() raises KeyError if tid does not exist or if tid deleted
-        a revision of obj.
+        :return: a persistent object
+        
+        :Parameters:
+          - `obj`: a persistent object from this Connection.
+          - `tid`: id of a transaction that wrote an earlier revision.
+
+        :Exceptions:
+          - `KeyError`: if tid does not exist or if tid deleted a revision
+            of obj.
         """
         assert obj._p_jar is self
         p = self._storage.loadSerial(obj._p_oid, tid)




More information about the Zodb-checkins mailing list