ZCatalog Standalone

Download ZCatalog 1.0a1

ZCatalog adds an important feature to the Zope Object Database (ZODB): searchability. ZODB allows you to easily create a hierarchy of objects that you can traverse to find what you're looking for. However, when you're trying to quickly find objects that cut across different parts of the hierarchy, or trying to find an object by something other than its main key, the ZODB alone doesn't do it.

ZCatalog allows you to easily search on discrete fields or to perform full-text searches. The package is very extensible.

This release is a packaging of Zope's ZCatalog for use with the standalone ZODB package. It differs from the original ZCatalog in that all Zope-specific parts (security, object containment, etc.) have been removed and the objects have all been moved from their zope.* package locations into zcatalog. It requires, but does not include:

I am only testing this with Python 2.4 and ZODB 3.4, though it will possibly work with slightly earier releases.

This is a packaging of the ZCatalog from Zope 3.1. Since Zope 3.1 has not yet been released, this package was made from an svn snapshot on June 4, 2005. Indexes and other add-on features from Zope 2.x will undoubtedly require changes. I had originally created a standalone version of the Zope 2.8 catalog, but the 3.1 catalog is far cleaner or better suited to use outside of Zope.

Until someone takes over maintenance of this package, it should always be available at:

http://www.blazingthings.com/dev/zcatalog.html

Your best bet for support would be one of the Zope mailing lists:

http://www.zope.org/Resources/MailingLists

If you do need to use the mailing lists, odds are that catalog-specific questions will be better received on the zope3-users list.

Quickstart

Create a catalog:

from zcatalog import catalog
cat = catalog.Catalog()

Create an index or two:

from zcatalog import indexes
fi = indexes.FieldIndex(field_name="name")
ti = indexes.TextIndex(field_name="description")
cat["name"] = fi
cat["description"] = ti

This creates a "FieldIndex" (which searches on discrete values) that will index the "name" attribute of objects in the catalog. This index is given the name "name" in the catalog, though you could name the index anything you want. I also created a "TextIndex" which allows full-text searches.

Now, let's put some data in the catalog:

from persistent import Persistent

class MyFoo(Persistent):
    def __init__(self, name, description):
        self.name = name
        self.description = description

    def __str__(self):
        return self.name

a = MyFoo("Jack Jack", "Cute kid, sometimes too hot to handle.")
b = MyFoo("Anakin Skywalker", "I'm not your father. Hey, check out this hot lightsaber!")
cat.index_doc(a)
cat.index_doc(b)

Standalone ZCatalog maintains an internal mapping of objects to an integer ID. In Zope 3, this mapping is handled outside of ZCatalog. If you want, you can create a separate ID mapping object. Take a look at the intid module.

Now, let's try a search!

map(str, list(cat.searchResults(name=["Jack Jack", "Jack Jack"])))

Which gets you:

['Jack Jack']

A FieldIndex takes min and max parameters. If you're looking for an exact match, you need to pass the value in twice, like I did here.

map(str, list(cat.searchResults(description="hot")))
map(str, list(cat.searchResults(description="father")))
map(str, list(cat.searchResults(description="father OR hot")))
map(str, list(cat.searchResults(description="father AND hot")))

Which gets you:

--> ['Jack Jack', 'Anakin Skywalker']
--> ['Anakin Skywalker']
--> ['Jack Jack', 'Anakin Skywalker']
--> ['Anakin Skywalker']

Doesn't get much easier than that, does it?

License

This package is released under the Zope Public License 2.1, just as the original code was.

How this was created

In order to make upgrades easier, this package was built via a script that I wrote specifically to put this package together. I tried to preserve as many of the original files as possible, so you may see some functions that don't work outside of Zope. catalog.py and the IntIds class in cataloghelper.py were based on code from Zope, but the changes needed were extensive enough that I decided to make new files for these functions.

The remainder of the files largely just had unneeded imports removed and references to zope.* packages changed to zcatalog.*.

Hopefully, this arrangement will make it easy to keep up to date with changes to catalog that may occur within Zope itself.

Since I am no longer supporting or upgrading this package, I am providing the somewhat hackish source files used to generate this:

zcatalog-src.tgz

The buildcatalog.py script takes the Zope3 source files and does an automated mangling of them to generate a complete source tree for the Standalone ZCatalog package. There are some hardcoded (but relative) paths in the script that you will either need to honor or change in order to use it.