[Zope3-checkins] CVS: ZODB4/src/zodb - interfaces.py:1.13

[Jeremy Hylton]

Update of /cvs-repository/ZODB4/src/zodb
In directory cvs.zope.org:/tmp/cvs-serv22615/zodb

Modified Files:
	interfaces.py 
Log Message:
Improve docstrings for the interfaces.
Fix IDatabase to reflect actual method name.


=== ZODB4/src/zodb/interfaces.py 1.12 => 1.13 ===
--- ZODB4/src/zodb/interfaces.py:1.12	Thu Mar  6 15:04:13 2003
+++ ZODB4/src/zodb/interfaces.py	Thu Mar  6 16:02:27 2003
@@ -13,6 +13,16 @@
 ##############################################################################
 """ZODB database interfaces and exceptions
 
+The Zope Object Database (ZODB) manages persistent objects using
+pickle-based object serialization.  The database has a pluggable
+storage backend.
+
+The IAppDatabase, IAppConnection, and ITransaction interfaces describe
+the public APIs of the database.
+
+The IDatabase, IConnection, and ITransactionAttrs interfaces describe
+private APIs used by the implementation.
+
 $Id$
 """
 
@@ -221,7 +231,17 @@
     """
 
 class IAppDatabase(Interface):
-    """Interface exported by database to applications."""
+    """Interface exported by database to applications.
+
+    The database contains a graph of objects reachable from the
+    distinguished root object.  The root object is a mapping object
+    that can contain arbitrary application data.
+
+    There is only rudimentary support for using more than one database
+    in a single application.  The persistent state of an object in one
+    database can not contain a direct reference to an object in
+    another database.
+    """
 
     def open(version="", transaction=None, temporary=False, force=False,
              waitflag=True):
@@ -245,7 +265,18 @@
         """Undo changes caused by transaction txnid."""
 
 class IAppConnection(Interface):
-    """Interface exported by database connection to applications."""
+    """Interface exported by database connection to applications.
+
+    Each database connection provides an independent copy of the
+    persistent object space.  ZODB supports multiple threads by
+    providing each thread with a separate connection.
+
+    Connections are synchronized through database commits and explicit
+    sync() calls.  Changes to the object space are only made visible
+    when a transaction commits.  When a connection commits its
+    changes, they become visible to other connections.  Changes made
+    by other connections are also become visible at this time.
+    """
 
     def root():
         """Return the root of the database."""
@@ -268,7 +299,7 @@
     def invalidate(oids, conn=None, version=""):
         pass
 
-    def connectionClose(conn):
+    def _closeConnection(conn):
         pass