[Zodb-checkins] CVS: ZODB/src/ZODB - Connection.py:1.135 DB.py:1.69
Jeremy Hylton
jeremy at zope.com
Thu Mar 4 14:48:07 EST 2004
Update of /cvs-repository/ZODB/src/ZODB
In directory cvs.zope.org:/tmp/cvs-serv6322/src/ZODB
Modified Files:
Connection.py DB.py
Log Message:
Edit docstrings to remove epydoc markup.
=== ZODB/src/ZODB/Connection.py 1.134 => 1.135 ===
--- ZODB/src/ZODB/Connection.py:1.134 Thu Mar 4 11:15:55 2004
+++ ZODB/src/ZODB/Connection.py Thu Mar 4 14:48:03 2004
@@ -102,20 +102,30 @@
XXX Mention the database pool.
+ The Connection plays several different roles.
+
+ 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$
-
- @group User Methods: root, get, add, close, db, sync, isReadOnly,
- cacheGC, cacheFullSweep, cacheMinimize, getVersion, modifiedInVersion
- @group Experimental Methods: setLocalTransaction, getTransaction,
- onCloseCallbacks
- @group Transaction Data Manager Methods: tpc_begin, tpc_vote,
- tpc_finish, tpc_abort, sortKey, abort, commit, commit_sub,
- abort_sub
- @group Database Invalidation Methods: invalidate, _setDB
- @group IPersistentDataManager Methods: setstate, register,
- setklassstate
- @group Other Methods: oldstate, exchange, getDebugInfo, setDebugInfo,
- getTransferCounts
"""
_tmp = None
@@ -221,7 +231,7 @@
return '<Connection at %08x%s>' % (id(self), ver)
def get(self, oid):
- """Return the persistent object with oid C{oid}.
+ """Return the persistent object with oid 'oid'.
If the object was not in the cache and the object's class is
ghostable, then a ghost will be returned. If the object is
@@ -231,10 +241,12 @@
Applications seldom need to call this method, because objects
are loaded transparently during attribute lookup.
- @return: persistent object
- @rtype: L{IPersistent}
- @raise KeyError: If C{oid} does not exist.
- @raise RuntimeError: If the connection is closed.
+ 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.
"""
if self._storage is None:
# XXX Should this be a ZODB-specific exception?
@@ -262,26 +274,26 @@
__getitem__ = get
def add(self, obj):
- """Add a new object C{obj} to the database and assign it an oid.
+ """Add a new object 'obj' to the database and assign it an oid.
A persistent object is normally added to the database and
assigned an oid when it becomes reachable an object already in
the database. In some cases, it is useful to create a new
- object and uses its oid (C{_p_oid}) in a single transaction.
+ object and uses its oid (_p_oid) in a single transaction.
This method assigns a new oid regardless of whether the object
is reachable.
The object is added when the transaction commits. The object
- must implement the L{IPersistent} interface and must not
- already be associated with a L{Connection}.
+ must implement the IPersistent interface and must not
+ already be associated with a Connection.
+
+ add() raises TypeError if obj is not a persistent object.
- @param obj: the object to add
- @type obj: L{IPersistent}
- @raise TypeError: If C{obj} is not a persistent object.
- @raise InvalidObjectReference: If C{obj} is already associated
- with another connection.
- @raise RuntimeError: If the connection is closed.
+ add() raises InvalidObjectReference if obj is already associated
+ with another connection.
+
+ add() raises RuntimeError if the connection is closed.
"""
if self._storage is None:
# XXX Should this be a ZODB-specific exception?
@@ -312,16 +324,13 @@
return "%s:%s" % (storage_key, id(self))
def _setDB(self, odb):
- """Register C{odb}, the L{DB} that this Connection uses.
+ """Register odb, the DB that this Connection uses.
- This method is called by the L{DB} every time a C{Connection}
- is opened. Any invalidations received while the C{Connection}
+ This method is called by the DB every time a Connection
+ is opened. Any invalidations received while the Connection
was closed will be processed.
- If L{resetCaches} was caused, the cache will be cleared.
-
- @param odb: the database that owns the C{Connection}
- @type L{DB}
+ If resetCaches() was called, the cache will be cleared.
"""
# XXX Why do we go to all the trouble of setting _db and
@@ -391,8 +400,8 @@
it into a ghost. It is possible for individual objects to
remain active.
- @param dt: The dt argument is provided only for backwards
- compatibility. It is ignored.
+ The dt argument is provided only for backwards compatibility.
+ It is ignored.
"""
if dt is not None:
warnings.warn("The dt argument to cacheMinimize is ignored.",
@@ -410,9 +419,9 @@
__onCloseCallbacks = None
def onCloseCallback(self, f):
- """Register a callable C{f} to be called by L{close}.
+ """Register a callable, f, to be called by close().
- The callable C{f} will be called at most once, the next time
+ The callable, f, will be called at most once, the next time
the Connection is closed.
"""
if self.__onCloseCallbacks is None:
@@ -420,15 +429,15 @@
self.__onCloseCallbacks.append(f)
def close(self):
- """Close the C{Connection}.
+ """Close the Connection.
- A closed C{Connection} should not be used by client code. It
+ A closed Connection should not be used by client code. It
can't load or store objects. Objects in the cache are not
- freed, because C{Connections} are re-used and the cache are
+ freed, because Connections are re-used and the cache are
expected to be useful to the next client.
When the Connection is closed, all callbacks registered by
- L{onCloseCallback} are invoked and the cache is scanned for
+ onCloseCallback() are invoked and the cache is scanned for
old objects.
"""
if self._cache is not None:
@@ -605,20 +614,17 @@
return self._storage.isReadOnly()
def invalidate(self, tid, oids):
- """Notify the Connection that C{tid} Invalidated C{oids}.
+ """Notify the Connection that transaction 'tid' invalidated oids.
When the next transaction boundary is reached, objects will be
invalidated. If any of the invalidated objects is accessed by
the current transaction, the revision written before C{tid}
will be used.
- The L{DB} calls this method, even when the C{Connection} is
- closed.
+ The DB calls this method, even when the Connection is closed.
- @param tid: id of transaction that committed
- @type tid: C{string}
- @param oids: set of oids
- @type oids: C{dict} with oids as keys
+ 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.
"""
self._inv_lock.acquire()
try:
@@ -649,10 +655,12 @@
return self._version
def register(self, obj):
- """Register C{obj} with the current transaction manager.
+ """Register obj with the current transaction manager.
A subclass could override this method to customize the default
policy of one transaction manager for each thread.
+
+ obj must be an object loaded from this Connection.
"""
assert obj._p_jar is self
if obj._p_oid is None:
@@ -669,10 +677,9 @@
self.getTransaction().register(obj)
def root(self):
- """Get the database root object.
+ """Return the database root object.
- @return: the database root object
- @rtype: C{persistent.dict.PersistentDict}
+ The root is a PersistentDict.
"""
return self.get(z64)
@@ -799,15 +806,14 @@
raise ReadConflictError(object=obj)
def oldstate(self, obj, tid):
- """Return copy of C{obj} that was written by C{tid}.
+ """Return copy of obj that was written by tid.
- @param obj: the persistent object to retrieve an old revision of
- @type obj: L{IPersistent}
- @param tid: id of transaction that wrote revision
- @type tid: C{string}
+ 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.
- @raise KeyError: If C{tid} does not exist or if C{tid} deleted
- a revision of C{obj}
+ oldstate() raises 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)
=== ZODB/src/ZODB/DB.py 1.68 => 1.69 ===
--- ZODB/src/ZODB/DB.py:1.68 Tue Mar 2 10:36:40 2004
+++ ZODB/src/ZODB/DB.py Thu Mar 4 14:48:04 2004
@@ -29,38 +29,27 @@
class DB(object):
"""The Object Database
- The C{DB} class coordinates the activities of multiple database
- L{Connection} instances. Most of the work is done by the
- C{Connections} created via the L{open} method.
+ The DB class coordinates the activities of multiple database
+ Connection instances. Most of the work is done by the
+ Connections created via the open method.
- The C{DB} instance manages a pool of connections. If a connection
- is closed, it is returned to the pool and its object cache is
+ The DB instance manages a pool of connections. If a connection is
+ closed, it is returned to the pool and its object cache is
preserved. A subsequent call to open() will reuse the connection.
There is a limit to the pool size; if all its connections are in
use, calls to open() will block until one of the open connections
is closed.
- @cvar klass: Class used by L{open} to create database connections
- @type klass: L{Connection} or a subclass
-
- @group User Methods: __init__, open, close, undo, pack, setClassFactory
- @group Inspection Methods: getName, getSize, objectCount,
- getActivityMonitor, setActivityMonitor
- @group Connection Pool Methods: getPoolSize, getVersionPoolSize,
- removeVersionPool, setPoolSize, setVersionPoolSize
- @group Transaction Methods: invalidate
- @group Other Methods: lastTransaction, connectionDebugInfo
- @group Version Methods: modifiedInVersion, abortVersion, commitVersion,
- versionEmpty
- @group Cache Inspection Methods: cacheDetail, cacheExtremeDetail,
- cacheFullSweep, cacheLastGCTime, cacheMinimize, cacheMeanAge,
- cacheMeanDeac, cacheMeanDeal, cacheSize, cacheDetailSize,
- getCacheSize, getVersionCacheSize, setCacheSize, setVersionCacheSize,
- cacheStatistics
- @group Deprecated Methods: getCacheDeactivateAfter,
- setCacheDeactivateAfter,
- getVersionCacheDeactivateAfter, setVersionCacheDeactivateAfter
+ The class variable 'klass' is used by open() to create database
+ connections. It is set to Connection, but a subclass could override
+ it to provide a different connection implementation.
+
+ The database provides a few methods intended for application code
+ -- open, close, undo, pack, setClassFactory -- and a large
+ collection of methods for inspecting the database and its connections'
+ caches.
"""
+
klass = Connection # Class to use for connections
_activity_monitor = None
@@ -74,18 +63,17 @@
):
"""Create an object database.
- @param storage: storage for the database, e.g. C{FileStorage}
- @param pool_size: maximum number of open connections
- @type pool_size: C{int}
- @param cache_size: target size of L{Connection} object cache
- @type cache_size: C{int}
- @param cache_deactivate_after: ignored
- @param version_pool_size: maximum number of connections (per version)
- @type version_pool_size: C{int}
- @param version_cache_size: target size of L{Connection} object
- cache for version connectios
- @type version_cache_size: C{int}
- @param version_cache_deactivate_after: ignored
+ The constructor requires one argument, the storage used by the
+ database, e.g. FileStorage.
+
+ There are several other optional arguments:
+ pool_size: maximum number of open connections
+ cache_size: target size of Connection object cache
+ cache_deactivate_after: ignored
+ version_pool_size: maximum number of connections (per version)
+ version_cache_size: target size of Connection object cache for
+ version connections
+ version_cache_deactivate_after: ignored
"""
# Allocate locks:
l=allocate_lock()
@@ -209,7 +197,8 @@
def cacheDetail(self):
"""Return information on objects in the various caches
- Organized by class."""
+ Organized by class.
+ """
detail = {}
def f(con, detail=detail, have_detail=detail.has_key):
@@ -386,7 +375,7 @@
def open(self, version='', transaction=None, temporary=0, force=None,
waitflag=1, mvcc=True):
- """Return a database L{Connection}
+ """Return a database Connection for use by application code.
The optional version argument can be used to specify that a
version connection is desired.
@@ -396,8 +385,9 @@
terminated. In addition, connections per transaction are
reused, if possible.
- Note that the connection pool is managed as a stack, to increate the
- likelihood that the connection's stack will include useful objects.
+ Note that the connection pool is managed as a stack, to
+ increate the likelihood that the connection's stack will
+ include useful objects.
"""
self._a()
try:
@@ -562,14 +552,16 @@
The cost of this operation varies by storage, but it is
usually an expensive operation.
- @param t: pack time in seconds since the epoch
- @type t: C{float}
- @param days: days to subtract from C{t} to compute pack time
- @type days: C{int}
+ There are two optional arguments that can be used to set the
+ pack time: t, pack time in seconds since the epcoh, and days,
+ the number of days to substract from t or from the current
+ time if t is not specified.
"""
- if t is None: t=time()
- t=t-(days*86400)
- try: self._storage.pack(t,referencesf)
+ if t is None:
+ t = time()
+ t -= days * 86400
+ try:
+ self._storage.pack(t, referencesf)
except:
LOG("ZODB", ERROR, "packing", error=sys.exc_info())
raise
@@ -588,14 +580,11 @@
The database stores objects, but uses Python's standard import
to load the code for those objects. The class factory is used
by the database serialization layer to find the classes. It
- uses L{ZODB.broken.find_global<find_global>} by default.
+ uses ZODB.broken.find_global by default.
This method can be used to override the default class loading
- code. See L{ZODB.broken.find_global<find_global>} for details
- about the contract of C{factory}.
-
- @param factory: A class factory for unpickling
- @type factory: C{function}
+ code. See ZODB.broken.find_global for details
+ about the contract of factory.
"""
self._classFactory = factory
@@ -617,21 +606,20 @@
def cacheStatistics(self): return () # :(
def undo(self, id, transaction=None):
- """Undo a transaction identified by C{id}.
+ """Undo a transaction identified by id.
A transaction can be undone if all of the objects involved in
the transaction were not modified subsequently, if any
modifications can be resolved by conflict resolution, or if
subsequent changes resulted in the same object state.
- The value of C{id} should be generated by calling C{undoLog}
- or C{undoInfo}. The value of C{id} is not the same as a
- transaction id used by other methods; it is unique to C{undo}.
-
- @param id: a storage-specific transaction identifier
- @type id: C{string}
- @param transaction: a transaction context to use
- @type transaction: C{Transaction}
+ The value of id should be generated by calling undoLog()
+ or undoInfo(). The value of id is not the same as a
+ transaction id used by other methods; it is unique to undo().
+
+ In addition, a user can pass the optional argument,
+ transaction, which identifies a transaction context to use for
+ the undo().
"""
if transaction is None:
transaction = get_transaction()
More information about the Zodb-checkins
mailing list