[Zodb-checkins] CVS: ZODB3/Doc/guide - zodb.tex:1.6
prog-zodb.tex:1.4 links.tex:1.4 chatter.py:1.3
Jeremy Hylton
jeremy at zope.com
Thu Oct 2 14:18:00 EDT 2003
Update of /cvs-repository/ZODB3/Doc/guide
In directory cvs.zope.org:/tmp/cvs-serv18770/Doc/guide
Modified Files:
zodb.tex prog-zodb.tex links.tex chatter.py
Log Message:
Merge changes from Zope-2_7-branch to the trunk.
=== ZODB3/Doc/guide/zodb.tex 1.5 => 1.6 ===
--- ZODB3/Doc/guide/zodb.tex:1.5 Thu May 1 16:16:06 2003
+++ ZODB3/Doc/guide/zodb.tex Thu Oct 2 14:17:29 2003
@@ -1,7 +1,7 @@
\documentclass{howto}
\title{ZODB/ZEO Programming Guide}
-\release{0.1}
+\release{0.2}
\date{\today}
\author{A.M.\ Kuchling}
@@ -23,9 +23,6 @@
\input{prog-zodb}
\input{zeo}
\input{transactions}
-%\input{storages}
-%\input{indexing}
-%\input{admin}
\input{modules}
\appendix
=== ZODB3/Doc/guide/prog-zodb.tex 1.3 => 1.4 ===
--- ZODB3/Doc/guide/prog-zodb.tex:1.3 Fri Oct 4 20:37:12 2002
+++ ZODB3/Doc/guide/prog-zodb.tex Thu Oct 2 14:17:29 2003
@@ -9,36 +9,28 @@
\subsection{Installing ZODB}
-The ZODB forms part of Zope, but it's difficult and somewhat painful
-to extract the bits from Zope needed to support just the ZODB.
-Therefore I've assembled a distribution containing only the packages
-required to use the ZODB and ZEO, so you can install it and start
-programming right away.
-
-To download the distribution, go to my ZODB page at
-\url{http://www.amk.ca/zodb/}.
-The distribution is still experimental, so don't be surprised if the
-installation process runs into problems. Please inform me of any
-difficulties you encounter.
+ZODB is packaged using the standard distutils tools.
\subsubsection{Requirements}
-You will need Python 2.1 or higher. The code is packaged using
-Distutils. So it is simply a matter of untarring or unzipping the
-release package, and then running \code{python setup.py install}.
+You will need Python 2.2 or higher. Since the code is packaged using
+distutils, it is simply a matter of untarring or unzipping the release
+package, and then running \code{python setup.py install}.
You'll need a C compiler to build the packages, because there are
-various C extension modules. At the moment no one is making Windows
-binaries available, so you'll need a Windows development environment
-to build ZODB.
+various C extension modules. Binary installers are provided for
+Windows users.
\subsubsection{Installing the Packages}
Download the ZODB tarball containing all the packages for both ZODB
-and ZEO from \url{http://www.zope.org/Products/StandaloneZODB}. See
+and ZEO from \url{http://www.zope.org/Products/ZODB3.2}. See
the \file{README.txt} file in the top level of the release directory
for details on building, testing, and installing.
+You can find information about ZODB and the most current releases in
+the ZODB Wiki at \url{http://www.zope.org/Wikis/ZODB}.
+
\subsection{How ZODB Works}
The ZODB is conceptually simple. Python classes subclass a
@@ -59,8 +51,10 @@
software offers protection against such corruption by supporting four
useful properties, Atomicity, Consistency, Isolation, and Durability.
In computer science jargon these four terms are collectively dubbed
-the ACID properties, forming an acronym from their names. The
-definitions of the ACID properties are:
+the ACID properties, forming an acronym from their names.
+
+The ZODB provides all of the ACID properties. Definitions of the
+ACID properties are:
\begin{itemize}
@@ -73,18 +67,13 @@
partially-applied modification put the database into an inconsistent
state.
-\item[Consistency] means that the data cannot be placed into a
-logically invalid state; sanity checks can be written and enforced.
-Usually this is done by defining a database schema, and requiring
-the data always matches the schema. There are two typical
-approaches to consistency. One is to enforce rules about the types
-of objects and attribute; for example, enforce that the
-\code{order_number} attribute is always an integer, and not a
-string, tuple, or other object. Another is to guarantee consistency
-across data structures; for example, that any object with an
-\code{order_number} attribute must also appear in the
-\code{orders_table} object. In general, atomicity and isolation make
-it possible for applications to provide consistency.
+\item[Consistency] means that each transaction executes a valid
+transformation of the database state. Some databases, but not ZODB,
+provide a variety of consistency checks in the database or language;
+for example, a relational database constraint columns to be of
+particular types and can enforce relations across tables. Viewed more
+generally, atomicity and isolation make it possible for applications
+to provide consistency.
\item[Isolation] means that two programs or threads running in two
different transactions cannot see each other's changes until they
@@ -95,10 +84,6 @@
\end{itemize}
-The ZODB provides 3 of the ACID properties. Only Consistency is not
-supported; the ZODB has no notion of a database schema, and therefore
-has no way of enforcing consistency with a schema.
-
\subsection{Opening a ZODB}
There are 3 main interfaces supplied by the ZODB:
@@ -132,9 +117,9 @@
\end{itemize}
Preparing to use a ZODB requires 3 steps: you have to open the
-\class{Storage}, then create a \class{DB} instance that uses the \class{Storage}, and then get
-a \class{Connection} from the \class{DB instance}. All this is only a few lines of
-code:
+\class{Storage}, then create a \class{DB} instance that uses the
+\class{Storage}, and then get a \class{Connection} from the \class{DB
+instance}. All this is only a few lines of code:
\begin{verbatim}
from ZODB import FileStorage, DB
@@ -189,7 +174,7 @@
retrieve the primary root object of the ZODB using the \method{root()}
method of the \class{Connection} instance. The root object behaves
like a Python dictionary, so you can just add a new key/value pair for
-your application's root object. We'll insert a \class{BTree} object
+your application's root object. We'll insert an \class{OOBTree} object
that will contain all the \class{User} objects. (The
\class{BTree} module is also included as part of Zope.)
@@ -199,8 +184,8 @@
# Ensure that a 'userdb' key is present
# in the root
if not dbroot.has_key('userdb'):
- import BTree
- dbroot['userdb'] = BTree.BTree()
+ from BTrees.OOBTree import OOBTree
+ dbroot['userdb'] = OOBTree()
userdb = dbroot['userdb']
\end{verbatim}
@@ -426,13 +411,11 @@
them all, short of writing a generalized object traversal function
that would walk over every single object in a ZODB, checking each one
to see if it's an instance of \class{User}.
-\footnote{XXX is there a convenience method for walking the object graph hiding
-somewhere inside DC's code? Should there be a utility method for
-doing this? Should I write one and include it in this section?}
+
Some OODBs support a feature called extents, which allow quickly
finding all the instances of a given class, no matter where they are
in the object graph; unfortunately the ZODB doesn't offer extents as a
feature.
-XXX Rest of section not written yet: __getstate__/__setstate__
+% XXX Rest of section not written yet: __getstate__/__setstate__
=== ZODB3/Doc/guide/links.tex 1.3 => 1.4 ===
--- ZODB3/Doc/guide/links.tex:1.3 Fri Oct 4 20:37:12 2002
+++ ZODB3/Doc/guide/links.tex Thu Oct 2 14:17:29 2003
@@ -25,7 +25,4 @@
\\
\url{http://www.zope.org/Members/bwarsaw/ipc10-slides}
-Download link for ZEO: \\
-\url{http://www.zope.org/Products/ZEO/}
-
=== ZODB3/Doc/guide/chatter.py 1.2 => 1.3 ===
--- ZODB3/Doc/guide/chatter.py:1.2 Mon Feb 11 18:33:40 2002
+++ ZODB3/Doc/guide/chatter.py Thu Oct 2 14:17:29 2003
@@ -16,8 +16,8 @@
add_message(message) -- add a message to the channel
new_messages() -- return new messages since the last call to
this method
-
-
+
+
"""
def __init__(self, name):
@@ -27,15 +27,15 @@
self.name = name
- # Internal attribute: _messages holds all the chat messages.
+ # Internal attribute: _messages holds all the chat messages.
self._messages = BTree.BTree()
-
+
def new_messages(self):
"Return new messages."
# self._v_last_time is the time of the most recent message
- # returned to the user of this class.
+ # returned to the user of this class.
if not hasattr(self, '_v_last_time'):
self._v_last_time = 0
@@ -48,7 +48,7 @@
self._v_last_time = T2
return new
-
+
def add_message(self, message):
"""Add a message to the channel.
message -- text of the message to be added
@@ -82,7 +82,7 @@
print 'Creating chat_sessions B-tree'
root['chat_sessions'] = BTree.BTree()
get_transaction().commit()
-
+
sessions = root['chat_sessions']
# Get a session object corresponding to the channel name, creating
@@ -94,7 +94,7 @@
session = sessions[ channelname ]
return session
-
+
if __name__ == '__main__':
if len(sys.argv) != 2:
@@ -119,6 +119,5 @@
print msg
# Wait for a few seconds
- pause = random.randint( 1, 4 )
+ pause = random.randint( 1, 4 )
time.sleep( pause )
-
More information about the Zodb-checkins
mailing list