Introduction

The ZODB3 package provides a set of tools for using the Zope Object Database (ZODB) in Python programs separately from Zope. The tools you get are identical to the ones provided in Zope, because they come from the same source repository. They have been packaged for use in non-Zope stand-alone Python applications.

ZODB3 is known to work with Python 2.1.3, 2.2.3, and 2.3. Note that 2.2.1 does not work. ZODB 3.1.5 is compatible with Zope 2.6. This is a maintenance release.

Our primary development platforms are Linux and Windows 2000, but we occasionally test with Windows 98, too. The test suite should pass without error on all of these platforms, although it can take a long time on Windows.

The components you get with the ZODB3 release are as follows:

• Core ZODB, including the persistence machinery
• Standard storages such as FileStorage
• Supporting modules such as ExtensionClass
• The persistent BTrees modules
• ZEO
• BerkeleyDB based storages
• Some documentation <wink>

Prerequisites

You must have Python installed. If you've installed Python from RPM, be sure that you've installed the development RPMs too, since ZODB3 builds Python extensions. If you have the source release of ZODB3, you will need a C compiler.

If you intend to use the BerkeleyDB storages, you will need to install the Berkeley database software and PyBSDDB, the Berkeley DB Python wrapper. It is recommended that you use Berkeley 4.1.25 and PyBSDDB 4.1.6. See the Doc/BDBStorage.txt file for details.

Installation

ZODB3 is released as a distutils package. To build it, run the setup script:

% python setup.py build

To test the build, run the test script:

% python test.py

For more verbose test output, append one or two '-v' arguments to this command.

If all the tests succeeded, you can install ZODB3 using the setup script:

% python setup.py install

This should now make all of ZODB accessible to your Python programs. You can test this by cd'ing to your home directory and typing the following commands:

Python 2.2.2 (#1, Oct 18 2002, 15:34:34)
[GCC 2.95.3 19991030 (prerelease)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import ZODB
>>> ZODB.__version__
'3.1.3'

To install ZODB3 using ZEO version 1 instead of version 2, pass the --with-zeo1 argument to setup.py when you build and install:

% python setup.py build --with-zeo1

% python setup.py install --with-zeo1

Installing ZEO for Zope

This package provides ZEO 2.0.4, which is compatible with Zope 2.6. There are two ways to install the ZEO package for Zope 2.6. You can copy the ZEO directory into Zope's lib/python directory. Or you can run "python setup.py install --home Zope" and have distutils install all the ZODB packages in Zope/lib/python. If you have Zope 2.6.2, you can choose either option. If you have earlier versions of Zope 2.6, you should use distutils because ZEO 2.0.4 depends on changes to other packages that are not present in earlier versions of Zope.

Note that it is usually possible to run a ZEO server without having a full Zope install. The ZODB3 package is self-contained and can be used for a ZEO server unless you have custom code in your Zope software home that performs conflict resolution. In most cases, conflict resolution is most important for BTrees, which is part of ZODB3.

Testing

ZODB3 comes with a large test suite that can be run from the source directory before ZODB is installed. The simplest way to run the tests is:

% python test.py -v

This command will run all the tests, printing a single dot for each test. When it finishes, it will print a test summary. The exact number of tests can vary depending on platform and available third-party libraries. On Windows, the tests can take much longer to execute:

Ran 859 tests in 153.277s

OK

The test script has many more options. Use the -h or --help options to see a file list of options.

Windows + Python 2.1.3 note: The test driver looks at gc.garbage after each test, and prints gc.garbage if it's not empty. An ever-increasing list of unreclaimable garbage will get displayed if you run the tests on Windows with Python 2.1.3. The cause is that 2.1.3's socket.py supplies a socket wrapper class on Windows, with a needless __del__ method. This __del__ method was simply removed in later Python releases. You can do the same without harm in a Python 2.1.3 release: edit Libsocket.py, and comment out, or delete, this code in class _socketobject:

def __del__(self):
    self.close()

History

The version numbering scheme for ZODB is complicated. Starting with this release, we are trying to make it simpler. This is release 3.1.1 of the package named ZODB3. Versions prior to 3.1 had different names and different numbers. This section describes the gory details.

Historically, ZODB was distributed as a part of the Zope application server. Jim Fulton's paper at the Python conference in 2000 described a version of ZODB he called ZODB 3, based on an earlier persistent object system called BoboPOS. The earliest versions of ZODB 3 were released with Zope 2.0.

Andrew Kuchling extracted ZODB from Zope 2.4.1 and packaged it for use by standalone Python programs. He called this version "StandaloneZODB". Andrew's guide to using ZODB is included in the Doc directory. This version of ZODB was hosted at http://sf.net/projects/zodb. It supported Python 1.5.2, and might still be of interest to users of this very old Python version.

Zope Corporation released a version of ZODB called "StandaloneZODB 1.0" in Feb. 2002. This release was based on Andrew's packaging, but built from the same CVS repository as Zope. It is roughly equivalent to the ZODB in Zope 2.5.

Why not call the current release StandaloneZODB 1.1? The name StandaloneZODB is a bit of a mouthful. The standalone part of the name suggests that the Zope version is the real version and that this is an afterthought, which isn't the case. Finally, we started work on ZODB4 -- a major new version based on Python 2.2 new-style types instead of ExtensionClass. So we're calling this release "ZODB3". We settled on the 3.1 version number so that we don't create the impression that this version of ZODB is the same as the one Jim described as ZODB 3 in 2000.

More information

We maintain a Wiki page about all things ZODB, including status on future directions for ZODB. Please see

http://www.zope.org/Wikis/ZODB

and feel free to contribute your comments. There is a Mailman mailing list in place to discuss all issues related to ZODB. You can send questions to

zodb-dev@zope.org

or subscribe at

http://lists.zope.org/mailman/listinfo/zodb-dev

and view its archives at

http://lists.zope.org/pipermail/zodb-dev

Andrew's ZODB Programmers Guide is made available in several forms, including DVI and HTML. To view it online, point your browser at the file Doc/guide/zodb/index.html

Bugs and Patches

You can submit bug reports and patches on Andrew's ZODB SourceForge project at:

http://sourceforge.net/tracker/?group_id=15628