[Zodb-checkins] CVS: ZODB3/Doc/zodb - about.html:1.1 blank.gif:1.1 contents.gif:1.1 contents.html:1.1 index.gif:1.1 index.html:1.1 modules.gif:1.1 next.gif:1.1 node2.html:1.1 node3.html:1.1 node5.html:1.1 node6.html:1.1 node7.html:1.1 node8.html:1.1 previous.gif:1.1 pyfav.gif:1.1 up.gif:1.1 zeo.html:1.1 zodb.css:1.1 zodb.html:1.1
Fred L. Drake, Jr.
fred@zope.com
Fri, 17 Jan 2003 16:31:13 -0500
Update of /cvs-repository/ZODB3/Doc/zodb
In directory cvs.zope.org:/tmp/cvs-serv23765/zodb
Added Files:
about.html blank.gif contents.gif contents.html index.gif
index.html modules.gif next.gif node2.html node3.html
node5.html node6.html node7.html node8.html previous.gif
pyfav.gif up.gif zeo.html zodb.css zodb.html
Log Message:
Updated all content in the new location.
=== Added File ZODB3/Doc/zodb/about.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="previous" HREF="node8.html">
<LINK REL="up" HREF="zodb.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="About this document ...">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>About this document ...</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node8.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node8.html">B. GNU Free Documentation</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION000900000000000000000">
About this document ...</A>
</H1>
<strong>ZODB/ZEO Programming Guide</strong>,
January 17, 2003, Release 0.04
<p> This document was generated using the <a
href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
<strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
</p>
<p> <a
href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
<strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
1993, 1994, 1995, 1996, 1997, <a
href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
Drakos</a>, Computer Based Learning Unit, University of
Leeds, and Copyright © 1997, 1998, <a
href="http://www.maths.mq.edu.au/~ross/">Ross
Moore</a>, Mathematics Department, Macquarie University,
Sydney.
</p>
<p> The application of <a
href="http://saftsack.fs.uni-bayreuth.de/~latex2ht/">
<strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
documentation has been heavily tailored by Fred L. Drake,
Jr. Original navigation icons were contributed by Christopher
Petrilli.
</p>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node8.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node8.html">B. GNU Free Documentation</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/blank.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/contents.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/contents.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node2.html">
<LINK REL="previous" HREF="zodb.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node2.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="Contents">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>Contents</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="zodb.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node2.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node2.html">1 Introduction</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<BR>
<BR><H2><A NAME="SECTION000100000000000000000">
Contents</A>
</H2>
<!--Table of Contents-->
<UL CLASS="TofC">
<LI><A href="node2.html">1 Introduction</a>
<UL>
<LI><A href="node2.html#SECTION000210000000000000000">1.1 What is the ZODB?</a>
<LI><A href="node2.html#SECTION000220000000000000000">1.2 OODBs vs. Relational DBs</a>
<LI><A href="node2.html#SECTION000230000000000000000">1.3 What is ZEO?</a>
<LI><A href="node2.html#SECTION000240000000000000000">1.4 About this guide</a>
<LI><A href="node2.html#SECTION000250000000000000000">1.5 Acknowledgements</a>
</ul>
<LI><A href="node3.html">2 ZODB Programming</a>
<UL>
<LI><A href="node3.html#SECTION000310000000000000000">2.1 Installing ZODB</a>
<LI><A href="node3.html#SECTION000320000000000000000">2.2 How ZODB Works</a>
<LI><A href="node3.html#SECTION000330000000000000000">2.3 Opening a ZODB</a>
<LI><A href="node3.html#SECTION000340000000000000000">2.4 Writing a Persistent Class</a>
<LI><A href="node3.html#SECTION000350000000000000000">2.5 Rules for Writing Persistent Classes</a>
<LI><A href="node3.html#SECTION000360000000000000000">2.6 Writing Persistent Classes</a>
</ul>
<LI><A href="zeo.html">3 ZEO</a>
<UL>
<LI><A href="zeo.html#SECTION000410000000000000000">3.1 How ZEO Works</a>
<LI><A href="zeo.html#SECTION000420000000000000000">3.2 Installing ZEO</a>
<LI><A href="zeo.html#SECTION000430000000000000000">3.3 Testing the ZEO Installation</a>
<LI><A href="zeo.html#SECTION000440000000000000000">3.4 ZEO Programming Notes</a>
<LI><A href="zeo.html#SECTION000450000000000000000">3.5 Sample Application: chatter.py</a>
</ul>
<LI><A href="node5.html">4 Transactions and Versioning</a>
<UL>
<LI><A href="node5.html#SECTION000510000000000000000">4.1 Subtransactions</a>
<LI><A href="node5.html#SECTION000520000000000000000">4.2 Undoing Changes</a>
<LI><A href="node5.html#SECTION000530000000000000000">4.3 Versions</a>
<LI><A href="node5.html#SECTION000540000000000000000">4.4 Multithreaded ZODB Programs</a>
</ul>
<LI><A href="node6.html">5 Related Modules</a>
<UL>
<LI><A href="node6.html#SECTION000610000000000000000">5.1 <tt class="module">ZODB.PersistentMapping</tt></a>
<LI><A href="node6.html#SECTION000620000000000000000">5.2 <tt class="module">ZODB.PersistentList</tt></a>
<LI><A href="node6.html#SECTION000630000000000000000">5.3 BTrees Package</a>
</ul>
<LI><A href="node7.html">A. Resources</a>
<LI><A href="node8.html">B. GNU Free Documentation License</a>
<UL>
<LI><A href="node8.html#SECTION000810000000000000000">Preamble</a>
<LI><A href="node8.html#SECTION000820000000000000000">B..1 Applicability and Definitions</a>
<LI><A href="node8.html#SECTION000830000000000000000">B..2 Verbatim Copying</a>
<LI><A href="node8.html#SECTION000840000000000000000">B..3 Copying in Quantity</a>
<LI><A href="node8.html#SECTION000850000000000000000">B..4 Modifications</a>
<LI><A href="node8.html#SECTION000860000000000000000">B..5 Combining Documents</a>
<LI><A href="node8.html#SECTION000870000000000000000">B..6 Collections of Documents</a>
<LI><A href="node8.html#SECTION000880000000000000000">B..7 Aggregation With Independent Works</a>
<LI><A href="node8.html#SECTION000890000000000000000">B..8 Translation</a>
<LI><A href="node8.html#SECTION0008100000000000000000">B..9 Termination</a>
<LI><A href="node8.html#SECTION0008110000000000000000">B..10 Future Revisions of This Licence</a>
<LI><A href="node8.html#SECTION0008120000000000000000">ADDENDUM: How to use this License for your documents</a>
</ul>
<LI><A href="about.html">About this document ...</a>
</ul>
<!--End of Table of Contents-->
<P>
©Copyright 2002 A.M. Kuchling.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the appendix entitled ``GNU
Free Documentation License''.
<P>
<P>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="zodb.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node2.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node2.html">1 Introduction</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/index.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/index.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" href="contents.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="ZODB/ZEO Programming Guide">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>ZODB/ZEO Programming Guide</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><A href="contents.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Next:</b> <a class="sectref" href="contents.html">Contents</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<div class="titlepage">
<center>
<h1>ZODB/ZEO Programming Guide</h1>
<p><b><font size="+2">A.M. Kuchling</font></b></p>
<p>akuchlin@mems-exchange.org</p>
<p><strong>Release 0.04</strong><br>
<strong>January 17, 2003</strong></p>
<p>
</center>
</div>
<p><hr>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"></a>
<UL CLASS="ChildLinks">
<LI><A href="contents.html">Contents</a>
<LI><A href="node2.html">1 Introduction</a>
<UL>
<LI><A href="node2.html#SECTION000210000000000000000">1.1 What is the ZODB?</a>
<LI><A href="node2.html#SECTION000220000000000000000">1.2 OODBs vs. Relational DBs</a>
<LI><A href="node2.html#SECTION000230000000000000000">1.3 What is ZEO?</a>
<LI><A href="node2.html#SECTION000240000000000000000">1.4 About this guide</a>
<LI><A href="node2.html#SECTION000250000000000000000">1.5 Acknowledgements</a>
</ul>
<LI><A href="node3.html">2 ZODB Programming</a>
<UL>
<LI><A href="node3.html#SECTION000310000000000000000">2.1 Installing ZODB</a>
<UL>
<LI><A href="node3.html#SECTION000311000000000000000">2.1.1 Requirements</a>
<LI><A href="node3.html#SECTION000312000000000000000">2.1.2 Installing the Packages</a>
</ul>
<LI><A href="node3.html#SECTION000320000000000000000">2.2 How ZODB Works</a>
<LI><A href="node3.html#SECTION000330000000000000000">2.3 Opening a ZODB</a>
<LI><A href="node3.html#SECTION000340000000000000000">2.4 Writing a Persistent Class</a>
<LI><A href="node3.html#SECTION000350000000000000000">2.5 Rules for Writing Persistent Classes</a>
<UL>
<LI><A href="node3.html#SECTION000351000000000000000">2.5.1 Modifying Mutable Objects</a>
<LI><A href="node3.html#SECTION000352000000000000000">2.5.2 Some Special Methods Don't Work</a>
<LI><A href="node3.html#SECTION000353000000000000000">2.5.3 <tt class="method">__getattr__</tt>, <tt class="method">__delattr__</tt>, and <tt class="method">__setattr__</tt></a>
</ul>
<LI><A href="node3.html#SECTION000360000000000000000">2.6 Writing Persistent Classes</a>
<UL>
<LI><A href="node3.html#SECTION000361000000000000000">2.6.1 Changing Instance Attributes</a>
</ul>
</ul>
<LI><A href="zeo.html">3 ZEO</a>
<UL>
<LI><A href="zeo.html#SECTION000410000000000000000">3.1 How ZEO Works</a>
<LI><A href="zeo.html#SECTION000420000000000000000">3.2 Installing ZEO</a>
<UL>
<LI><A href="zeo.html#SECTION000421000000000000000">3.2.1 Requirements</a>
<LI><A href="zeo.html#SECTION000422000000000000000">3.2.2 Running a server</a>
</ul>
<LI><A href="zeo.html#SECTION000430000000000000000">3.3 Testing the ZEO Installation</a>
<LI><A href="zeo.html#SECTION000440000000000000000">3.4 ZEO Programming Notes</a>
<LI><A href="zeo.html#SECTION000450000000000000000">3.5 Sample Application: chatter.py</a>
</ul>
<LI><A href="node5.html">4 Transactions and Versioning</a>
<UL>
<LI><A href="node5.html#SECTION000510000000000000000">4.1 Subtransactions</a>
<LI><A href="node5.html#SECTION000520000000000000000">4.2 Undoing Changes</a>
<LI><A href="node5.html#SECTION000530000000000000000">4.3 Versions</a>
<LI><A href="node5.html#SECTION000540000000000000000">4.4 Multithreaded ZODB Programs</a>
</ul>
<LI><A href="node6.html">5 Related Modules</a>
<UL>
<LI><A href="node6.html#SECTION000610000000000000000">5.1 <tt class="module">ZODB.PersistentMapping</tt></a>
<LI><A href="node6.html#SECTION000620000000000000000">5.2 <tt class="module">ZODB.PersistentList</tt></a>
<LI><A href="node6.html#SECTION000630000000000000000">5.3 BTrees Package</a>
</ul>
<LI><A href="node7.html">A. Resources</a>
<LI><A href="node8.html">B. GNU Free Documentation License</a>
<UL>
<LI><A href="node8.html#SECTION000810000000000000000">Preamble</a>
<LI><A href="node8.html#SECTION000820000000000000000">B..1 Applicability and Definitions</a>
<LI><A href="node8.html#SECTION000830000000000000000">B..2 Verbatim Copying</a>
<LI><A href="node8.html#SECTION000840000000000000000">B..3 Copying in Quantity</a>
<LI><A href="node8.html#SECTION000850000000000000000">B..4 Modifications</a>
<LI><A href="node8.html#SECTION000860000000000000000">B..5 Combining Documents</a>
<LI><A href="node8.html#SECTION000870000000000000000">B..6 Collections of Documents</a>
<LI><A href="node8.html#SECTION000880000000000000000">B..7 Aggregation With Independent Works</a>
<LI><A href="node8.html#SECTION000890000000000000000">B..8 Translation</a>
<LI><A href="node8.html#SECTION0008100000000000000000">B..9 Termination</a>
<LI><A href="node8.html#SECTION0008110000000000000000">B..10 Future Revisions of This Licence</a>
<LI><A href="node8.html#SECTION0008120000000000000000">ADDENDUM: How to use this License for your documents</a>
</ul>
<LI><A href="about.html">About this document ...</a>
</ul>
<!--End of Table of Child-Links-->
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><A href="contents.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Next:</b> <a class="sectref" href="contents.html">Contents</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/modules.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/next.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/node2.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node3.html">
<LINK REL="previous" href="contents.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node3.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="1 Introduction">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>1 Introduction</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A href="contents.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node3.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="contents.html">Contents</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node3.html">2 ZODB Programming</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000210000000000000000">1.1 What is the ZODB?</a>
<LI><A href="#SECTION000220000000000000000">1.2 OODBs vs. Relational DBs</a>
<LI><A href="#SECTION000230000000000000000">1.3 What is ZEO?</a>
<LI><A href="#SECTION000240000000000000000">1.4 About this guide</a>
<LI><A href="#SECTION000250000000000000000">1.5 Acknowledgements</a>
</ul>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION000200000000000000000">
1 Introduction</A>
</H1>
<P>
This guide explains how to write Python programs that use the Z Object
Database (ZODB) and Zope Enterprise Objects (ZEO). The latest version
of the guide is always available at
<a class="url" href="http://www.amk.ca/zodb/guide/">http://www.amk.ca/zodb/guide/</a>.
<P>
<H2><A NAME="SECTION000210000000000000000">
1.1 What is the ZODB?</A>
</H2>
<P>
The ZODB is a persistence system for Python objects. Persistent
programming languages provide facilities that automatically write
objects to disk and read them in again when they're required by a
running program. By installing the ZODB, you add such facilities to
Python.
<P>
It's certainly possible to build your own system for making Python
objects persistent. The usual starting points are the <tt class="module">pickle</tt>
module, for converting objects into a string representation, and
various database modules, such as the <tt class="module">gdbm</tt> or <tt class="module">bsddb</tt>
modules, that provide ways to write strings to disk and read them
back. It's straightforward to combine the <tt class="module">pickle</tt> module and
a database module to store and retrieve objects, and in fact the
<tt class="module">shelve</tt> module, included in Python's standard library, does
this.
<P>
The downside is that the programmer has to explicitly manage objects,
reading an object when it's needed and writing it out to disk when the
object is no longer required. The ZODB manages objects for you,
keeping them in a cache and writing them out if they haven't been
accessed in a while.
<P>
<H2><A NAME="SECTION000220000000000000000">
1.2 OODBs vs. Relational DBs</A>
</H2>
<P>
Another way to look at it is that the ZODB is a Python-specific
object-oriented database (OODB). Commercial object databases for C++
or Java often require that you jump through some hoops, such as using
a special preprocessor or avoiding certain data types. As we'll see,
the ZODB has some hoops of its own to jump through, but in comparison
the naturalness of the ZODB is astonishing.
<P>
Relational databases (RDBs) are far more common than OODBs.
Relational databases store information in tables; a table consists of
any number of rows, each row containing several columns of
information. (Rows are more formally called relations, which is where
the term ``relational database'' originates.)
<P>
Let's look at a concrete example. The example comes from my day job
working for the MEMS Exchange, in a greatly simplified version. The
job is to track process runs, which are lists of manufacturing steps
to be performed in a semiconductor fab. A run is owned by a
particular user, and has a name and assigned ID number. Runs consist
of a number of operations; an operation is a single step to be
performed, such as depositing something on a wafer or etching
something off it.
<P>
Operations may have parameters, which are additional information
required to perform an operation. For example, if you're depositing
something on a wafer, you need to know two things: 1) what you're
depositing, and 2) how much should be deposited. You might deposit
100 microns of silicon oxide, or 1 micron of copper.
<P>
Mapping these structures to a relational database is straightforward:
<P>
<div class="verbatim"><pre>
CREATE TABLE runs (
int run_id,
varchar owner,
varchar title,
int acct_num,
primary key(run_id)
);
CREATE TABLE operations (
int run_id,
int step_num,
varchar process_id,
PRIMARY KEY(run_id, step_num),
FOREIGN KEY(run_id) REFERENCES runs(run_id),
);
CREATE TABLE parameters (
int run_id,
int step_num,
varchar param_name,
varchar param_value,
PRIMARY KEY(run_id, step_num, param_name)
FOREIGN KEY(run_id, step_num)
REFERENCES operations(run_id, step_num),
);
</pre></div>
<P>
In Python, you would write three classes named <tt class="class">Run</tt>,
<tt class="class">Operation</tt>, and <tt class="class">Parameter</tt>. I won't present code for
defining these classes, since that code is uninteresting at this
point. Each class would contain a single method to begin with, an
<tt class="method">__init__</tt> method that assigns default values, such as 0 or
<code>None</code>, to each attribute of the class.
<P>
It's not difficult to write Python code that will create a <tt class="class">Run</tt>
instance and populate it with the data from the relational tables;
with a little more effort, you can build a straightforward tool,
usually called an object-relational mapper, to do this automatically.
(See
<a class="url" href="http://www.amk.ca/python/unmaintained/ordb.html">http://www.amk.ca/python/unmaintained/ordb.html</a> for a quick hack
at a Python object-relational mapper, and
<a class="url" href="http://www.python.org/workshops/1997-10/proceedings/shprentz.html">http://www.python.org/workshops/1997-10/proceedings/shprentz.html</a>for Joel Shprentz's more successful implementation of the same idea;
Unlike mine, Shprentz's system has been used for actual work.)
<P>
However, it is difficult to make an object-relational mapper
reasonably quick; a simple-minded implementation like mine is quite
slow because it has to do several queries to access all of an object's
data. Higher performance object-relational mappers cache objects to
improve performance, only performing SQL queries when they actually
need to.
<P>
That helps if you want to access run number 123 all of a sudden. But
what if you want to find all runs where a step has a parameter named
'thickness' with a value of 2.0? In the relational version, you have
two unappealing choices:
<P>
<OL>
<LI>Write a specialized SQL query for this case: <code>SELECT run_id
FROM operations WHERE param_name = 'thickness' AND param_value = 2.0</code>
<P>
If such queries are common, you can end up with lots of specialized
queries. When the database tables get rearranged, all these queries
will need to be modified.
<P>
</LI>
<LI>An object-relational mapper doesn't help much. Scanning
through the runs means that the the mapper will perform the required
SQL queries to read run #1, and then a simple Python loop can check
whether any of its steps have the parameter you're looking for.
Repeat for run #2, 3, and so forth. This does a vast
number of SQL queries, and therefore is incredibly slow.
<P>
</LI>
</OL>
<P>
An object database such as ZODB simply stores internal pointers from
object to object, so reading in a single object is much faster than
doing a bunch of SQL queries and assembling the results. Scanning all
runs, therefore, is still inefficient, but not grossly inefficient.
<P>
<H2><A NAME="SECTION000230000000000000000">
1.3 What is ZEO?</A>
</H2>
<P>
The ZODB comes with a few different classes that implement the
<tt class="class">Storage</tt> interface. Such classes handle the job of
writing out Python objects to a physical storage medium, which can be
a disk file (the <tt class="class">FileStorage</tt> class), a BerkeleyDB file
(<tt class="class">BerkeleyStorage</tt>), a relational database
(<tt class="class">DCOracleStorage</tt>), or some other medium. ZEO adds
<tt class="class">ClientStorage</tt>, a new <tt class="class">Storage</tt> that doesn't write to
physical media but just forwards all requests across a network to a
server. The server, which is running an instance of the
<tt class="class">StorageServer</tt> class, simply acts as a front-end for some
physical <tt class="class">Storage</tt> class. It's a fairly simple idea, but as
we'll see later on in this document, it opens up many possibilities.
<P>
<H2><A NAME="SECTION000240000000000000000">
1.4 About this guide</A>
</H2>
<P>
The primary author of this guide works on a project which uses the
ZODB and ZEO as its primary storage technology. We use the ZODB to
store process runs and operations, a catalog of available processes,
user information, accounting information, and other data. Part of the
goal of writing this document is to make our experience more widely
available. A few times we've spent hours or even days trying to
figure out a problem, and this guide is an attempt to gather up the
knowledge we've gained so that others don't have to make the same
mistakes we did while learning.
<P>
This document will always be a work in progress. If you wish to
suggest clarifications or additional topics, please send your comments to
<span class="email">akuchlin@mems-exchange.org</span>.
<P>
<H2><A NAME="SECTION000250000000000000000">
1.5 Acknowledgements</A>
</H2>
<P>
I'd like to thank the people who've pointed out inaccuracies and bugs,
offered suggestions on the text, or proposed new topics that should be
covered: Jeff Bauer, Willem Broekema, Thomas Guettler,
Chris McDonough, George Runyan.
<P>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A href="contents.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node3.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="contents.html">Contents</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node3.html">2 ZODB Programming</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/node3.html === (557/657 lines abridged)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" href="zeo.html">
<LINK REL="previous" HREF="node2.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" href="zeo.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="2 ZODB Programming">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>2 ZODB Programming</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node2.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A href="zeo.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node2.html">1 Introduction</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" href="zeo.html">3 ZEO</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000310000000000000000">2.1 Installing ZODB</a>
<UL>
[-=- -=- -=- 557 lines omitted -=- -=- -=-]
that would walk over every single object in a ZODB, checking each one
to see if it's an instance of <tt class="class">User</tt>.
<A NAME="tex2html1"
HREF="#foot262"><SUP>1</SUP></A>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.
<P>
XXX Rest of section not written yet: __getstate__/__setstate__
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot262">...User.
</A><A NAME="foot262"
HREF="node3.html#tex2html1"><SUP>1</SUP></A>
<DD>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?
</DL>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node2.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A href="zeo.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node2.html">1 Introduction</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" href="zeo.html">3 ZEO</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/node5.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node6.html">
<LINK REL="previous" href="zeo.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node6.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="4 Transactions and Versioning">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>4 Transactions and Versioning</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A href="zeo.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node6.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="zeo.html">3 ZEO</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node6.html">5 Related Modules</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000510000000000000000">4.1 Subtransactions</a>
<LI><A href="#SECTION000520000000000000000">4.2 Undoing Changes</a>
<LI><A href="#SECTION000530000000000000000">4.3 Versions</a>
<LI><A href="#SECTION000540000000000000000">4.4 Multithreaded ZODB Programs</a>
</ul>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION000500000000000000000">
4 Transactions and Versioning</A>
</H1>
<P>
<H2><A NAME="SECTION000510000000000000000">
4.1 Subtransactions</A>
</H2>
<P>
Subtransactions can be created within a transaction. Each
subtransaction can be individually committed and aborted, but the
changes within a subtransaction are not truly committed until the
containing transaction is committed.
<P>
The primary purpose of subtransactions is to decrease the memory usage
of transactions that touch a very large number of objects. Consider a
transaction during which 200,000 objects are modified. All the
objects that are modified in a single transaction have to remain in
memory until the transaction is committed, because the ZODB can't
discard them from the object cache. This can potentially make the
memory usage quite large. With subtransactions, a commit can be be
performed at intervals, say, every 10,000 objects. Those 10,000
objects are then written to permanent storage and can be purged from
the cache to free more space.
<P>
To commit a subtransaction instead of a full transaction,
pass a true value to the <tt class="method">commit()</tt>
or <tt class="method">abort()</tt> method of the <tt class="class">Transaction</tt> object.
<P>
<div class="verbatim"><pre>
# Commit a subtransaction
get_transaction().commit(1)
# Abort a subtransaction
get_transaction().abort(1)
</pre></div>
<P>
A new subtransaction is automatically started on committing or
aborting the previous subtransaction.
<P>
<H2><A NAME="SECTION000520000000000000000">
4.2 Undoing Changes</A>
</H2>
<P>
Some types of <tt class="class">Storage</tt> support undoing a transaction even after
it's been committed. You can tell if this is the case by calling the
<tt class="method">supportsUndo()</tt> method of the <tt class="class">DB</tt> instance, which
returns true if the underlying storage supports undo. Alternatively
you can call the <tt class="method">supportsUndo()</tt> method on the underlying
storage instance.
<P>
If a database supports undo, then the <tt class="method">undoLog(<var>start</var>,
<var>end</var><big>[</big>, func<big>]</big>)</tt> method on the <tt class="class">DB</tt> instance returns
the log of past transactions, returning transactions between the times
<var>start</var> and <var>end</var>, measured in seconds from the epoch.
If present, <var>func</var> is a function that acts as a filter on the
transactions to be returned; it's passed a dictionary representing
each transaction, and only transactions for which <var>func</var> returns
true will be included in the list of transactions returned to the
caller of <tt class="method">undoLog()</tt>. The dictionary contains keys for
various properties of the transaction. The most important keys are
"<tt class="samp">id</tt>", for the transaction ID, and "<tt class="samp">time</tt>", for the time at
which the transaction was committed.
<P>
<div class="verbatim"><pre>
>>> print storage.undoLog(0, sys.maxint)
[{'description': '',
'id': 'AzpGEGqU/0QAAAAAAAAGMA',
'time': 981126744.98,
'user_name': ''},
{'description': '',
'id': 'AzpGC/hUOKoAAAAAAAAFDQ',
'time': 981126478.202,
'user_name': ''}
...
</pre></div>
<P>
To store a description and a user name on a commit, get the current
transaction and call the <tt class="method">note(<var>text</var>)</tt> method to store a
description, and the
<tt class="method">setUser(<var>user_name</var>)</tt> method to store the user name.
While <tt class="method">setUser()</tt> overwrites the current user name and replaces
it with the new value, the <tt class="method">note()</tt> method always adds the text
to the transaction's description, so it can be called several times to
log several different changes made in the course of a single
transaction.
<P>
<div class="verbatim"><pre>
get_transaction().setUser('amk')
get_transaction().note('Change ownership')
</pre></div>
<P>
To undo a transaction, call the <tt class="method">DB.undo(<var>id</var>)</tt> method,
passing it the ID of the transaction to undo. If the transaction
can't be undone, a <tt class="exception">ZODB.POSException.UndoError</tt> exception
will be raised, with the message ``non-undoable
transaction''. Usually this will happen because later transactions
modified the objects affected by the transaction you're trying to
undo.
<P>
After you call <tt class="method">undo()</tt> you must commit the transaction for the
undo to actually be applied.
<A NAME="tex2html3"
HREF="#foot583"><SUP>3</SUP></A> There is one glitch in the undo process. The thread
that calls undo may not see the changes to the object until it calls
<tt class="method">Connection.sync()</tt> or commits another transaction.
<P>
<H2><A NAME="SECTION000530000000000000000">
4.3 Versions</A>
</H2>
<P>
While many subtransactions can be contained within a single regular
transaction, it's also possible to contain many regular transactions
within a long-running transaction, called a version in ZODB
terminology. Inside a version, any number of transactions can be
created and committed or rolled back, but the changes within a version
are not made visible to other connections to the same ZODB.
<P>
Not all storages support versions, but you can test for versioning
ability by calling <tt class="method">supportsVersions()</tt> method of the
<tt class="class">DB</tt> instance, which returns true if the underlying storage
supports versioning.
<P>
A version can be selected when creating the <tt class="class">Connection</tt>
instance using the <tt class="method">DB.open(<big>[</big><var>version</var><big>]</big>)</tt> method.
The <var>version</var> argument must be a string that will be used as the
name of the version.
<P>
<div class="verbatim"><pre>
vers_conn = db.open(version='Working version')
</pre></div>
<P>
Transactions can then be committed and aborted using this versioned
connection. Other connections that don't specify a version, or
provide a different version name, will not see changes committed
within the version named "<tt class="samp">Working version</tt>". To commit or abort a
version, which will either make the changes visible to all clients or
roll them back, call the <tt class="method">DB.commitVersion()</tt> or
<tt class="method">DB.abortVersion()</tt> methods.
XXX what are the source and dest arguments for?
<P>
The ZODB makes no attempt to reconcile changes between different
versions. Instead, the first version which modifies an object will
gain a lock on that object. Attempting to modify the object from a
different version or from an unversioned connection will cause a
<tt class="exception">ZODB.POSException.VersionLockError</tt> to be raised:
<P>
<div class="verbatim"><pre>
from ZODB.POSException import VersionLockError
try:
get_transaction().commit()
except VersionLockError, (obj_id, version):
print ('Cannot commit; object %s '
'locked by version %s' % (obj_id, version))
</pre></div>
<P>
The exception provides the ID of the locked object, and the name of
the version having a lock on it.
<P>
<H2><A NAME="SECTION000540000000000000000">
4.4 Multithreaded ZODB Programs</A>
</H2>
<P>
ZODB databases can be accessed from multithreaded Python programs.
The <tt class="class">Storage</tt> and <tt class="class">DB</tt> instances can be shared among
several threads, as long as individual <tt class="class">Connection</tt> instances
are created for each thread.
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot583">... applied.</A><A NAME="foot583"
HREF="node5.html#tex2html3"><SUP>3</SUP></A>
<DD>There are actually two different ways a storage can
implement the undo feature. Most of the storages that ship with ZODB
use the transactional form of undo described in the main text. Some
storages may use a non-transactional undo makes changes visible
immediately.
</DL>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A href="zeo.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node6.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="zeo.html">3 ZEO</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node6.html">5 Related Modules</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/node6.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node7.html">
<LINK REL="previous" HREF="node5.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node7.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="5 Related Modules">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>5 Related Modules</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node5.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node7.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node5.html">4 Transactions and Versioning</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node7.html">A. Resources</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000610000000000000000">5.1 <tt class="module">ZODB.PersistentMapping</tt></a>
<LI><A href="#SECTION000620000000000000000">5.2 <tt class="module">ZODB.PersistentList</tt></a>
<LI><A href="#SECTION000630000000000000000">5.3 BTrees Package</a>
</ul>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION000600000000000000000">
5 Related Modules</A>
</H1>
<P>
The ZODB package includes a number of related modules that provide
useful data types such as BTrees.
<P>
<H2><A NAME="SECTION000610000000000000000">
5.1 <tt class="module">ZODB.PersistentMapping</tt></A>
</H2>
<P>
The <tt class="class">PersistentMapping</tt> class is a wrapper for mapping objects
that will set the dirty bit when the mapping is modified by setting or
deleting a key.
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><a name="l2h-1"><tt class="function">PersistentMapping</tt></a></b>(</nobr></td>
<td><var>container = {}</var>)</td></tr></table>
<dd>
Create a <tt class="class">PersistentMapping</tt> object that wraps the
mapping object <var>container</var>. If you don't specify a
value for <var>container</var>, a regular Python dictionary is used.
</dl>
<P>
<tt class="class">PersistentMapping</tt> objects support all the same methods as
Python dictionaries do.
<P>
<H2><A NAME="SECTION000620000000000000000">
5.2 <tt class="module">ZODB.PersistentList</tt></A>
</H2>
<P>
The <tt class="class">PersistentList</tt> class is a wrapper for mutable sequence objects,
much as <tt class="class">PersistentMapping</tt> is a wrapper for mappings.
<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
<td><nobr><b><a name="l2h-2"><tt class="function">PersistentList</tt></a></b>(</nobr></td>
<td><var>initlist = []</var>)</td></tr></table>
<dd>
Create a <tt class="class">PersistentList</tt> object that wraps the
mutable sequence object <var>initlist</var>. If you don't specify a
value for <var>initlist</var>, a regular Python list is used.
</dl>
<P>
<tt class="class">PersistentList</tt> objects support all the same methods as
Python lists do.
<P>
<H2><A NAME="SECTION000630000000000000000">
5.3 BTrees Package</A>
</H2>
<P>
When programming with the ZODB, Python dictionaries aren't always what
you need. The most important case is where you want to store a very
large mapping. When a Python dictionary is accessed in a ZODB, the
whole dictionary has to be unpickled and brought into memory. If
you're storing something very large, such as a 100,000-entry user
database, unpickling such a large object will be slow. BTrees are a
balanced tree data structure that behave like a mapping but distribute
keys throughout a number of tree nodes. The nodes are stored in
sorted order. Nodes are then only unpickled and brought into memory
as they're accessed, so the entire tree doesn't have to occupy memory
(unless you really are touching every single key).
<P>
The BTrees package provides a large collection of related data
structures. There are variants of the data structures specialized to
handle integer values, which are faster and use less memory. There
are four modules that handle the different variants. The first two
letters of the module name specify the types of the keys and values in
mappings - O for any object and I for integer. The
<tt class="module">BTrees.IOBTree</tt> module provides a mapping that accepts integer
keys and arbitrary objects as values.
<P>
The four data structures provide by each module are a btree, a bucket,
a tree set, and a set. The btree and bucket types are mappings and
support all the usual mapping methods, e.g. <tt class="function">update()</tt> and
<tt class="function">keys()</tt>. The tree set and set types are similar to mappings
but they have no values; they support the methods that make sense for
a mapping with no keys, e.g. <tt class="function">keys()</tt> but not
<tt class="function">items()</tt>. The bucket and set types are the individual
building blocks for btrees and tree sets, respectively. A bucket or
set can be used when you are sure that it will have few elements. If
the data structure will grow large, you should use a btree or tree
set.
<P>
The four modules are named <tt class="module">OOBTree</tt>, <tt class="module">IOBTree</tt>,
<tt class="module">OIBTree</tt>, and <tt class="module">IIBTree</tt>. The two letter prefixes are
repeated in the data types names. The <tt class="module">BTrees.OOBTree</tt> module
defines the following types: <tt class="class">OOBTree</tt>, <tt class="class">OOBucket</tt>,
<tt class="class">OOSet</tt>, and <tt class="class">OOTreeSet</tt>.
<P>
The <tt class="function">keys()</tt>, <tt class="function">values()</tt>, and <tt class="function">items()</tt>
methods do not materialize a list with all of the data. Instead, they
return lazy sequences that fetch data from the BTree as needed. They
also support optional arguments to specify the minium and maximum
values to return.
<P>
A BTree object supports all the methods you would expect of a mapping
with a few extensions that exploit the fact that the keys are sorted.
The example below demonstrates how some of the methods work. The
extra methods re <tt class="function">minKey()</tt> and <tt class="function">maxKey()</tt>, which
find the minimum and maximum key value subject to an optional bound
argument, and <tt class="function">byValue()</tt>, which returns value, key pairs
in reversed sorted order subject to an optional minimum bound argument.
<P>
<div class="verbatim"><pre>
>>> from BTrees.OOBTree import OOBTree
>>> t = OOBTree()
>>> t.update({ 1: "red", 2: "green", 3: "blue", 4: "spades" })
>>> len(t)
4
>>> t[2]
'green'
>>> t.keys()
<OOBTreeItems object at 0x40269098>
>>> [k for k in t.keys()] # use a listcomp to get a printable sequence
[1, 2, 3, 4]
>>> [k for k in t.values()]
['red', 'green', 'blue', 'spades']
>>> [k for k in t.values(1, 2)]
['red', 'green']
>>> [k for k in t.values(2)]
['green', 'blue', 'spades']
>>> t.byValue("glue") # all values > "glue"
[('spades', 4), ('red', 1), ('green', 2)]
>>> t.minKey(1.5)
2
</pre></div>
<P>
Each of the modules also defines some functions that operate on
BTrees - <tt class="function">difference()</tt>, <tt class="function">union()</tt>, and
<tt class="function">difference()</tt>. The <tt class="function">difference()</tt> function returns
a bucket, while the other two methods return a set.
If the keys are integers, then the module also defines
<tt class="function">multiunion()</tt>. If the values are integers, then the module
also defines <tt class="function">weightedIntersection()</tt> and
<tt class="function">weighterUnion()</tt>. The function doc strings describe each
function briefly.
<P>
<P>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node5.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node7.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node5.html">4 Transactions and Versioning</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node7.html">A. Resources</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/node7.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node8.html">
<LINK REL="previous" HREF="node6.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node8.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="A. Resources">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>A. Resources</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node6.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node8.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node6.html">5 Related Modules</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node8.html">B. GNU Free Documentation</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION000700000000000000000">
A. Resources</A>
</H1>
<P>
ZODB HOWTO, by Michel Pelletier:
<BR>
Goes into slightly more detail about the rules for writing applications using the ZODB.
<BR><a class="url" href="http://www.zope.org/Members/michel/HowTos/ZODB-How-To">http://www.zope.org/Members/michel/HowTos/ZODB-How-To</a>
<P>
Introduction to the Zope Object Database, by Jim Fulton:
<BR>
Goes into much greater detail, explaining advanced uses of the ZODB and
how it's actually implemented. A definitive reference, and highly recommended.
<BR><a class="url" href="http://www.python.org/workshops/2000-01/proceedings/papers/fulton/zodb3.html">http://www.python.org/workshops/2000-01/proceedings/papers/fulton/zodb3.html</a>
<P>
Persistent Programing with ZODB, by Jeremy Hylton and Barry Warsaw:
<BR>
Slides for a tutorial presented at the 10th Python conference. Covers
much of the same ground as this guide, with more details in some areas
and less in others.
<BR><a class="url" href="http://www.zope.org/Members/bwarsaw/ipc10-slides">http://www.zope.org/Members/bwarsaw/ipc10-slides</a>
<P>
Download link for ZEO:
<BR><a class="url" href="http://www.zope.org/Products/ZEO/">http://www.zope.org/Products/ZEO/</a>
<P>
<P>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node6.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node8.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node6.html">5 Related Modules</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node8.html">B. GNU Free Documentation</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/node8.html === (453/553 lines abridged)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" href="about.html">
<LINK REL="previous" HREF="node7.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" href="about.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="B. GNU Free Documentation License">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>B. GNU Free Documentation License</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node7.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A href="about.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node7.html">A. Resources</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" href="about.html">About this document ...</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000810000000000000000">Preamble</a>
<LI><A href="#SECTION000820000000000000000">B..1 Applicability and Definitions</a>
[-=- -=- -=- 453 lines omitted -=- -=- -=-]
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
</BLOCKQUOTE>
<P>
<P>
If you have no Invariant Sections, write ``with no Invariant Sections''
instead of saying which ones are invariant. If you have no
Front-Cover Texts, write ``no Front-Cover Texts'' instead of
``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.
<P>
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
<P>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node7.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A href="about.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node7.html">A. Resources</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" href="about.html">About this document ...</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/previous.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/pyfav.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/up.gif ===
<Binary-ish file>
=== Added File ZODB3/Doc/zodb/zeo.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" HREF="node5.html">
<LINK REL="previous" HREF="node3.html">
<LINK REL="up" HREF="zodb.html">
<LINK REL="next" HREF="node5.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="3 ZEO">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>3 ZEO</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node3.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node5.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node3.html">2 ZODB Programming</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node5.html">4 Transactions and Versioning</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
<UL CLASS="ChildLinks">
<LI><A href="#SECTION000410000000000000000">3.1 How ZEO Works</a>
<LI><A href="#SECTION000420000000000000000">3.2 Installing ZEO</a>
<UL>
<LI><A href="#SECTION000421000000000000000">3.2.1 Requirements</a>
<LI><A href="#SECTION000422000000000000000">3.2.2 Running a server</a>
</ul>
<LI><A href="#SECTION000430000000000000000">3.3 Testing the ZEO Installation</a>
<LI><A href="#SECTION000440000000000000000">3.4 ZEO Programming Notes</a>
<LI><A href="#SECTION000450000000000000000">3.5 Sample Application: chatter.py</a>
</ul>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION000400000000000000000"> </A>
<BR>
3 ZEO
</H1>
<P>
<H2><A NAME="SECTION000410000000000000000">
3.1 How ZEO Works</A>
</H2>
<P>
The ZODB, as I've described it so far, can only be used within a
single Python process (though perhaps with multiple threads). ZEO,
Zope Enterprise Objects, extends the ZODB machinery to provide access
to objects over a network. The name "Zope Enterprise Objects" is a
bit misleading; ZEO can be used to store Python objects and access
them in a distributed fashion without Zope ever entering the picture.
The combination of ZEO and ZODB is essentially a Python-specific
object database.
<P>
ZEO consists of about 6000 lines of Python code, excluding tests. The
code is relatively small because it contains only code for a TCP/IP
server, and for a new type of Storage, <tt class="class">ClientStorage</tt>.
<tt class="class">ClientStorage</tt> simply makes remote procedure calls to the
server, which then passes them on a regular <tt class="class">Storage</tt> class such
as <tt class="class">FileStorage</tt>. The following diagram lays out the system:
<P>
XXX insert diagram here later
<P>
Any number of processes can create a <tt class="class">ClientStorage</tt>
instance, and any number of threads in each process can be using that
instance. <tt class="class">ClientStorage</tt> aggressively caches objects
locally, so in order to avoid using stale data. The ZEO server sends
an invalidation message to all the connected <tt class="class">ClientStorage</tt>
instances on every write operation. The invalidation message contains
the object ID for each object that's been modified, letting the
<tt class="class">ClientStorage</tt> instances delete the old data for the
given object from their caches.
<P>
This design decision has some consequences you should be aware of.
First, while ZEO isn't tied to Zope, it was first written for use with
Zope, which stores HTML, images, and program code in the database. As
a result, reads from the database are <i>far</i> more frequent than
writes, and ZEO is therefore better suited for read-intensive
applications. If every <tt class="class">ClientStorage</tt> is writing to the
database all the time, this will result in a storm of invalidate
messages being sent, and this might take up more processing time than
the actual database operations themselves.<A NAME="tex2html2"
HREF="#foot429"><SUP>2</SUP></A>
<P>
On the other hand, for applications that have few writes in comparison
to the number of read accesses, this aggressive caching can be a major
win. Consider a Slashdot-like discussion forum that divides the load
among several Web servers. If news items and postings are represented
by objects and accessed through ZEO, then the most heavily accessed
objects - the most recent or most popular postings - will very
quickly wind up in the caches of the
<tt class="class">ClientStorage</tt> instances on the front-end servers. The
back-end ZEO server will do relatively little work, only being called
upon to return the occasional older posting that's requested, and to
send the occasional invalidate message when a new posting is added.
The ZEO server isn't going to be contacted for every single request,
so its workload will remain manageable.
<P>
<H2><A NAME="SECTION000420000000000000000">
3.2 Installing ZEO</A>
</H2>
<P>
This section covers how to install the ZEO package, and how to
configure and run a ZEO Storage Server on a machine.
<P>
<H3><A NAME="SECTION000421000000000000000">
3.2.1 Requirements</A>
</H3>
<P>
The ZEO server software is included in ZODB3. As with the rest of
ZODB3, you'll need Python 2.1 or higher.
<P>
<H3><A NAME="SECTION000422000000000000000">
3.2.2 Running a server</A>
</H3>
<P>
The start.py script in the ZEO directory can be used to start a
server. Run it with the -h option to see the various values. If
you're just experimenting, a good choise is to use
<code>python ZEO/start.py -D -U /tmp/zeosocket</code> to run ZEO in
debug mode and with a Unix domain socket.
<P>
<H2><A NAME="SECTION000430000000000000000">
3.3 Testing the ZEO Installation</A>
</H2>
<P>
Once a ZEO server is up and running, using it is just like using ZODB
with a more conventional disk-based storage; no new programming
details are introduced by using a remote server. The only difference
is that programs must create a <tt class="class">ClientStorage</tt> instance instead
of a <tt class="class">FileStorage</tt> instance. From that point onward, ZODB-based
code is happily unaware that objects are being retrieved from a ZEO
server, and not from the local disk.
<P>
As an example, and to test whether ZEO is working correctly, try
running the following lines of code, which will connect to the server,
add some bits of data to the root of the ZODB, and commits the
transaction:
<P>
<div class="verbatim"><pre>
from ZEO import ClientStorage
from ZODB import DB
# Change next line to connect to your ZEO server
addr = ('kronos.example.com', 1975)
storage = ClientStorage.ClientStorage(addr)
db = DB(storage)
conn = db.open()
root = conn.root()
# Store some things in the root
root['list'] = ['a', 'b', 1.0, 3]
root['dict'] = {'a':1, 'b':4}
# Commit the transaction
get_transaction().commit()
</pre></div>
<P>
If this code runs properly, then your ZEO server is working correctly.
<P>
<H2><A NAME="SECTION000440000000000000000">
3.4 ZEO Programming Notes</A>
</H2>
<P>
ZEO is written using <tt class="module">asyncore</tt>, from the Python standard
library. It assumes that some part of the user application is running
an <tt class="module">asyncore</tt> mainloop. For example, Zope run the loop in a
separate thread and ZEO uses that. If your application does not have
a mainloop, ZEO will not process incoming invalidation messages until
you make some call into ZEO. The <tt class="method">Connection.sync</tt> method can
be used to process pending invalidation messages. You can call it
when you want to make sure the <tt class="class">Connection</tt> has the most recent
version of every object, but you don't have any other work for ZEO to do.
<P>
<H2><A NAME="SECTION000450000000000000000">
3.5 Sample Application: chatter.py</A>
</H2>
<P>
For an example application, we'll build a little chat application.
What's interesting is that none of the application's code deals with
network programming at all; instead, an object will hold chat
messages, and be magically shared between all the clients through ZEO.
I won't present the complete script here; it's included in my ZODB
distribution, and you can download it from
<a class="url" href="http://www.amk.ca/zodb/demos/">http://www.amk.ca/zodb/demos/</a>. Only the interesting portions of
the code will be covered here.
<P>
The basic data structure is the <tt class="class">ChatSession</tt> object,
which provides an <tt class="method">add_message()</tt> method that adds a
message, and a <tt class="method">new_messages()</tt> method that returns a list
of new messages that have accumulated since the last call to
<tt class="method">new_messages()</tt>. Internally, <tt class="class">ChatSession</tt>
maintains a B-tree that uses the time as the key, and stores the
message as the corresponding value.
<P>
The constructor for <tt class="class">ChatSession</tt> is pretty simple; it simply
creates an attribute containing a B-tree:
<P>
<div class="verbatim"><pre>
class ChatSession(Persistent):
def __init__(self, name):
self.name = name
# Internal attribute: _messages holds all the chat messages.
self._messages = BTrees.OOBTree.OOBTree()
</pre></div>
<P>
<tt class="method">add_message()</tt> has to add a message to the
<code>_messages</code> B-tree. A complication is that it's possible
that some other client is trying to add a message at the same time;
when this happens, the client that commits first wins, and the second
client will get a <tt class="exception">ConflictError</tt> exception when it tries to
commit. For this application, <tt class="exception">ConflictError</tt> isn't serious
but simply means that the operation has to be retried; other
applications might treat it as a fatal error. The code uses
<code>try...except...else</code> inside a <code>while</code> loop,
breaking out of the loop when the commit works without raising an
exception.
<P>
<div class="verbatim"><pre>
def add_message(self, message):
"""Add a message to the channel.
message -- text of the message to be added
"""
while 1:
try:
now = time.time()
self._messages[now] = message
get_transaction().commit()
except ConflictError:
# Conflict occurred; this process should pause and
# wait for a little bit, then try again.
time.sleep(.2)
pass
else:
# No ConflictError exception raised, so break
# out of the enclosing while loop.
break
# end while
</pre></div>
<P>
<tt class="method">new_messages()</tt> introduces the use of <i>volatile</i>
attributes. Attributes of a persistent object that begin with
<code>_v_</code> are considered volatile and are never stored in the
database. <tt class="method">new_messages()</tt> needs to store the last time
the method was called, but if the time was stored as a regular
attribute, its value would be committed to the database and shared
with all the other clients. <tt class="method">new_messages()</tt> would then
return the new messages accumulated since any other client called
<tt class="method">new_messages()</tt>, which isn't what we want.
<P>
<div class="verbatim"><pre>
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.
if not hasattr(self, '_v_last_time'):
self._v_last_time = 0
new = []
T = self._v_last_time
for T2, message in self._messages.items():
if T2 > T:
new.append(message)
self._v_last_time = T2
return new
</pre></div>
<P>
This application is interesting because it uses ZEO to easily share a
data structure; ZEO and ZODB are being used for their networking
ability, not primarily for their data storage ability. I can foresee
many interesting applications using ZEO in this way:
<P>
<UL>
<LI>With a Tkinter front-end, and a cleverer, more scalable data
structure, you could build a shared whiteboard using the same
technique.
<P>
</LI>
<LI>A shared chessboard object would make writing a networked chess
game easy.
<P>
</LI>
<LI>You could create a Python class containing a CD's title and
track information. To make a CD database, a read-only ZEO server
could be opened to the world, or an HTTP or XML-RPC interface could
be written on top of the ZODB.
<P>
</LI>
<LI>A program like Quicken could use a ZODB on the local disk to
store its data. This avoids the need to write and maintain
specialized I/O code that reads in your objects and writes them out;
instead you can concentrate on the problem domain, writing objects
that represent cheques, stock portfolios, or whatever.
<P>
</LI>
</UL>
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
<DT><A NAME="foot429">... themselves.</A><A NAME="foot429"
href="zeo.html#tex2html2"><SUP>2</SUP></A>
<DD>These messages are
small and sent in batches, so there would need to be a lot of writes
before it became a problem.
</DL>
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="node3.html"><img src='previous.gif'
border='0' height='32' alt='Previous Page' width='32'></A></td>
<td><A HREF="zodb.html"><img src='up.gif'
border='0' height='32' alt='Up One Level' width='32'></A></td>
<td><A HREF="node5.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="node3.html">2 ZODB Programming</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="zodb.html">ZODB/ZEO Programming Guide</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="node5.html">4 Transactions and Versioning</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>
=== Added File ZODB3/Doc/zodb/zodb.css ===
/*
* The first part of this is the standard CSS generated by LaTeX2HTML,
* with the "empty" declarations removed.
*/
/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
.math { font-family: "Century Schoolbook", serif; }
.math i { font-family: "Century Schoolbook", serif;
font-weight: bold }
.boldmath { font-family: "Century Schoolbook", serif;
font-weight: bold }
/*
* Implement both fixed-size and relative sizes.
*
* I think these can be safely removed, as it doesn't appear that
* LaTeX2HTML ever generates these, even though these are carried
* over from the LaTeX2HTML stylesheet.
*/
small.xtiny { font-size : xx-small; }
small.tiny { font-size : x-small; }
small.scriptsize { font-size : smaller; }
small.footnotesize { font-size : small; }
big.xlarge { font-size : large; }
big.xxlarge { font-size : x-large; }
big.huge { font-size : larger; }
big.xhuge { font-size : xx-large; }
/*
* Document-specific styles come next;
* these are added for the Python documentation.
*
* Note that the size specifications for the H* elements are because
* Netscape on Solaris otherwise doesn't get it right; they all end up
* the normal text size.
*/
body { color: #000000;
background-color: #ffffff; }
a:active { color: #ff0000; }
a[href]:hover { background-color: #bbeeff; }
a:visited { color: #551a8b; }
a:link { color: #0000bb; }
h1, h2, h3, h4, h5, h6 { font-family: avantgarde, sans-serif;
font-weight: bold; }
h1 { font-size: 180%; }
h2 { font-size: 150%; }
h3, h4 { font-size: 120%; }
code, tt { font-family: lucida typewriter, lucidatypewriter,
monospace; }
var { font-family: times, serif;
font-style: italic;
font-weight: normal; }
.typelabel { font-family: lucida, sans-serif; }
.navigation td { background-color: #99ccff;
font-weight: bold;
font-family: avantgarde, sans-serif;
font-size: 110%; }
div.warning { background-color: #fffaf0;
border: thin solid black;
padding: 0.5em;
margin-left: 2em;
margin-right: 2em; }
div.warning .label { font-size: 110%;
margin-right: 0.5em; }
.release-info { font-style: italic; }
.titlegraphic { vertical-align: top; }
.verbatim pre { color: #00008b;
font-family: lucida typewriter, lucidatypewriter,
monospace;
font-size: 90%; }
.verbatim { margin-left: 2em; }
.grammar { background-color: #99ccff;
margin-right: 0.5in;
padding: 0.05in; }
.productions { background-color: #bbeeff; }
.productions a:hover { background-color: #99ccff; }
.productions table { vertical-align: baseline; }
.grammar-footer { padding: 0.05in;
font-size: 85%; }
.email { font-family: avantgarde, sans-serif; }
.mailheader { font-family: avantgarde, sans-serif; }
.mimetype { font-family: avantgarde, sans-serif; }
.newsgroup { font-family: avantgarde, sans-serif; }
.url { font-family: avantgarde, sans-serif; }
.file { font-family: avantgarde, sans-serif; }
.tableheader { background-color: #99ccff;
font-family: avantgarde, sans-serif; }
.refcount-info { font-style: italic; }
.refcount-info .value { font-weight: bold;
color: #006600; }
/*
* Some decoration for the "See also:" blocks, in part inspired by some of
* the styling on Lars Marius Garshol's XSA pages.
* (The blue in the navigation bars is #99CCFF.)
*/
.seealso { background-color: #fffaf0;
border: thin solid black;
padding: 4pt; }
.seealso .heading { font-size: 110%; }
/*
* Class 'availability' is used for module availability statements at
* the top of modules.
*/
.availability .platform { font-weight: bold; }
=== Added File ZODB3/Doc/zodb/zodb.html ===
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="zodb.css" type='text/css'>
<link rel="first" href="zodb.html" title='ZODB/ZEO Programming Guide'>
<link rel="contents" href="contents.html" title="Contents"><link rel='last' href='about.html' title='About this document...'>
<link rel='help' href='about.html' title='About this document...'>
<LINK REL="next" href="contents.html">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name='aesop' content='information'>
<META NAME="description" CONTENT="ZODB/ZEO Programming Guide">
<META NAME="keywords" CONTENT="zodb">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<title>ZODB/ZEO Programming Guide</title>
</head>
<body>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><A href="contents.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Next:</b> <a class="sectref" href="contents.html">Contents</A>
<br><hr>
</DIV>
<!--End of Navigation Panel-->
<div class="titlepage">
<center>
<h1>ZODB/ZEO Programming Guide</h1>
<p><b><font size="+2">A.M. Kuchling</font></b></p>
<p>akuchlin@mems-exchange.org</p>
<p><strong>Release 0.04</strong><br>
<strong>January 17, 2003</strong></p>
<p>
</center>
</div>
<p><hr>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"></a>
<UL CLASS="ChildLinks">
<LI><A href="contents.html">Contents</a>
<LI><A href="node2.html">1 Introduction</a>
<UL>
<LI><A href="node2.html#SECTION000210000000000000000">1.1 What is the ZODB?</a>
<LI><A href="node2.html#SECTION000220000000000000000">1.2 OODBs vs. Relational DBs</a>
<LI><A href="node2.html#SECTION000230000000000000000">1.3 What is ZEO?</a>
<LI><A href="node2.html#SECTION000240000000000000000">1.4 About this guide</a>
<LI><A href="node2.html#SECTION000250000000000000000">1.5 Acknowledgements</a>
</ul>
<LI><A href="node3.html">2 ZODB Programming</a>
<UL>
<LI><A href="node3.html#SECTION000310000000000000000">2.1 Installing ZODB</a>
<UL>
<LI><A href="node3.html#SECTION000311000000000000000">2.1.1 Requirements</a>
<LI><A href="node3.html#SECTION000312000000000000000">2.1.2 Installing the Packages</a>
</ul>
<LI><A href="node3.html#SECTION000320000000000000000">2.2 How ZODB Works</a>
<LI><A href="node3.html#SECTION000330000000000000000">2.3 Opening a ZODB</a>
<LI><A href="node3.html#SECTION000340000000000000000">2.4 Writing a Persistent Class</a>
<LI><A href="node3.html#SECTION000350000000000000000">2.5 Rules for Writing Persistent Classes</a>
<UL>
<LI><A href="node3.html#SECTION000351000000000000000">2.5.1 Modifying Mutable Objects</a>
<LI><A href="node3.html#SECTION000352000000000000000">2.5.2 Some Special Methods Don't Work</a>
<LI><A href="node3.html#SECTION000353000000000000000">2.5.3 <tt class="method">__getattr__</tt>, <tt class="method">__delattr__</tt>, and <tt class="method">__setattr__</tt></a>
</ul>
<LI><A href="node3.html#SECTION000360000000000000000">2.6 Writing Persistent Classes</a>
<UL>
<LI><A href="node3.html#SECTION000361000000000000000">2.6.1 Changing Instance Attributes</a>
</ul>
</ul>
<LI><A href="zeo.html">3 ZEO</a>
<UL>
<LI><A href="zeo.html#SECTION000410000000000000000">3.1 How ZEO Works</a>
<LI><A href="zeo.html#SECTION000420000000000000000">3.2 Installing ZEO</a>
<UL>
<LI><A href="zeo.html#SECTION000421000000000000000">3.2.1 Requirements</a>
<LI><A href="zeo.html#SECTION000422000000000000000">3.2.2 Running a server</a>
</ul>
<LI><A href="zeo.html#SECTION000430000000000000000">3.3 Testing the ZEO Installation</a>
<LI><A href="zeo.html#SECTION000440000000000000000">3.4 ZEO Programming Notes</a>
<LI><A href="zeo.html#SECTION000450000000000000000">3.5 Sample Application: chatter.py</a>
</ul>
<LI><A href="node5.html">4 Transactions and Versioning</a>
<UL>
<LI><A href="node5.html#SECTION000510000000000000000">4.1 Subtransactions</a>
<LI><A href="node5.html#SECTION000520000000000000000">4.2 Undoing Changes</a>
<LI><A href="node5.html#SECTION000530000000000000000">4.3 Versions</a>
<LI><A href="node5.html#SECTION000540000000000000000">4.4 Multithreaded ZODB Programs</a>
</ul>
<LI><A href="node6.html">5 Related Modules</a>
<UL>
<LI><A href="node6.html#SECTION000610000000000000000">5.1 <tt class="module">ZODB.PersistentMapping</tt></a>
<LI><A href="node6.html#SECTION000620000000000000000">5.2 <tt class="module">ZODB.PersistentList</tt></a>
<LI><A href="node6.html#SECTION000630000000000000000">5.3 BTrees Package</a>
</ul>
<LI><A href="node7.html">A. Resources</a>
<LI><A href="node8.html">B. GNU Free Documentation License</a>
<UL>
<LI><A href="node8.html#SECTION000810000000000000000">Preamble</a>
<LI><A href="node8.html#SECTION000820000000000000000">B..1 Applicability and Definitions</a>
<LI><A href="node8.html#SECTION000830000000000000000">B..2 Verbatim Copying</a>
<LI><A href="node8.html#SECTION000840000000000000000">B..3 Copying in Quantity</a>
<LI><A href="node8.html#SECTION000850000000000000000">B..4 Modifications</a>
<LI><A href="node8.html#SECTION000860000000000000000">B..5 Combining Documents</a>
<LI><A href="node8.html#SECTION000870000000000000000">B..6 Collections of Documents</a>
<LI><A href="node8.html#SECTION000880000000000000000">B..7 Aggregation With Independent Works</a>
<LI><A href="node8.html#SECTION000890000000000000000">B..8 Translation</a>
<LI><A href="node8.html#SECTION0008100000000000000000">B..9 Termination</a>
<LI><A href="node8.html#SECTION0008110000000000000000">B..10 Future Revisions of This Licence</a>
<LI><A href="node8.html#SECTION0008120000000000000000">ADDENDUM: How to use this License for your documents</a>
</ul>
<LI><A href="about.html">About this document ...</a>
</ul>
<!--End of Table of Child-Links-->
<DIV CLASS="navigation">
<p><hr>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><A href="contents.html"><img src='next.gif'
border='0' height='32' alt='Next Page' width='32'></A></td>
<td align="center" width="100%">ZODB/ZEO Programming Guide</td>
<td><A href="contents.html"><img src='contents.gif'
border='0' height='32' alt='Contents' width='32'></A></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
<td><img src='blank.gif'
border='0' height='32' alt='' width='32'></td>
</tr></table>
<b class="navlabel">Next:</b> <a class="sectref" href="contents.html">Contents</A>
<hr>
<span class="release-info">Release 0.04, documentation updated on January 17, 2003.</span>
</DIV>
<!--End of Navigation Panel-->
</BODY>
</HTML>