Catalog Interfaces

interface zope.catalog.interfaces.ICatalogQuery[source]

Provides Catalog Queries.


Search on the given indexes.

Keyword arguments dictionary keys are index names and values are queries for these indexes.

Keyword arguments has some special names, used by the catalog itself:

  • _sort_index - The name of index to sort results with. This index must implement zope.index.interfaces.IIndexSort.
  • _limit - Limit result set by this number, useful when used with sorting.
  • _reverse - Reverse result set, also useful with sorting.
interface zope.catalog.interfaces.ICatalogEdit[source]

Extends: zope.index.interfaces.IInjection

Allows one to manipulate the Catalog information.


Reindex all objects.

interface zope.catalog.interfaces.ICatalogIndex[source]

Extends: zope.index.interfaces.IInjection, zope.index.interfaces.IIndexSearch

An index to be used in a catalog

interface zope.catalog.interfaces.ICatalog[source]

Extends: zope.catalog.interfaces.ICatalogQuery, zope.catalog.interfaces.ICatalogEdit, zope.container.interfaces.IContainer

Marker to describe a catalog in content space.

__setitem__(key, value)

Add the given object to the container under the given name.

Raises a TypeError if the key is not a unicode or ascii string.

Raises a ValueError if the key is empty, or if the key contains a character which is not allowed in an object name.

Raises a KeyError if the key violates a uniqueness constraint.

The container might choose to add a different object than the one passed to this method.

If the object doesn’t implement IContained, then one of two things must be done:

  1. If the object implements ILocation, then the IContained interface must be declared for the object.
  2. Otherwise, a ContainedProxy is created for the object and stored.

The object’s __parent__ and __name__ attributes are set to the container and the given name.

If the old parent was None, then an IObjectAddedEvent is generated, otherwise, an IObjectMovedEvent is generated. An IContainerModifiedEvent is generated for the container.

If the object replaces another object, then the old object is deleted before the new object is added, unless the container vetos the replacement by raising an exception.

If the object’s __parent__ and __name__ were already set to the container and the name, then no events are generated and no hooks. This allows advanced clients to take over event generation.

interface zope.catalog.interfaces.IAttributeIndex[source]

I index objects by first adapting them to an interface, then retrieving a field on the adapted object.



Objects will be adapted to this interface


Field Name

Name of the field to index


Field Callable

If true, then the field should be called to get the value to be indexed

interface zope.catalog.interfaces.INoAutoIndex[source]

Marker for objects that should not be automatically indexed

interface zope.catalog.interfaces.INoAutoReindex[source]

Marker for objects that should not be automatically reindexed



class zope.catalog.catalog.ResultSet(uids, uidutil)[source]

Lazily accessed set of objects.

zope.catalog.catalog.indexAdded(index, event)[source]

When an index is added to a catalog, we have to index existing objects

When an index is added, we tell it’s parent to index it:

>>> class FauxCatalog:
...     updated = None
...     def updateIndex(self, index):
...         self.updated = index
>>> class FauxIndex:
...     pass
>>> index = FauxIndex()
>>> index.__parent__ = FauxCatalog()
>>> from zope.catalog.catalog import indexAdded
>>> indexAdded(index, None)
>>> index.__parent__.updated is index

A subscriber to IntIdAddedEvent


A subscriber to ObjectModifiedEvent


A subscriber to IntIdRemovedEvent

Index Implementations

The implementations of various kinds of indexes are spread across a few modules.

Attribute Indexes

Index interface-defined attributes

class zope.catalog.attribute.AttributeIndex(field_name=None, interface=None, field_callable=False, *args, **kwargs)[source]

Bases: object

Index interface-defined attributes

Mixin for indexing a particular attribute of an object after first adapting the object to be indexed to an interface.

The class is meant to be mixed with a base class that defines an index_doc method and an unindex_doc method:

>>> class BaseIndex(object):
...     def __init__(self):
...         self.data = []
...     def index_doc(self, id, value):
...         self.data.append((id, value))
...     def unindex_doc(self, id):
...         for n, (iid, _) in enumerate(self.data):
...             if id == iid:
...                 del self.data[n]
...                 break

The class does two things. The first is to get a named field from an object:

>>> class Data(object):
...     def __init__(self, v):
...         self.x = v
>>> from zope.catalog.attribute import AttributeIndex
>>> class Index(AttributeIndex, BaseIndex):
...     pass
>>> index = Index('x')
>>> index.index_doc(11, Data(1))
>>> index.index_doc(22, Data(2))
>>> index.data
[(11, 1), (22, 2)]

If the field value is None, indexing it removes it from the index:

>>> index.index_doc(11, Data(None))
>>> index.data
[(22, 2)]

If the field names a method (any callable object), the results of calling that field can be indexed:

>>> def z(self): return self.x + 20
>>> Data.z = z
>>> index = Index('z', field_callable=True)
>>> index.index_doc(11, Data(1))
>>> index.index_doc(22, Data(2))
>>> index.data
[(11, 21), (22, 22)]

Of course, if you neglect to set field_callable when you index a method, it’s likely that most concrete index implementations will raise an exception, but this class will happily pass that callable on:

>>> index = Index('z')
>>> data = Data(1)
>>> index.index_doc(11, data)
>>> index.data
[(11, <bound method ...>>)]

The class can also adapt an object to an interface before getting the field:

>>> from zope.interface import Interface
>>> class I(Interface):
...     pass
>>> class Data(object):
...     def __init__(self, v):
...         self.x = v
...     def __conform__(self, iface):
...         if iface is I:
...             return Data2(self.x)
>>> class Data2(object):
...     def __init__(self, v):
...         self.y = v * v
>>> index = Index('y', I)
>>> index.index_doc(11, Data(3))
>>> index.index_doc(22, Data(2))
>>> index.data
[(11, 9), (22, 4)]

If adapting to the interface fails, the object is not indexed:

>>> class I2(Interface): pass
>>> I2(Data(3), None) is None
>>> index = Index('y', I2)
>>> index.index_doc(11, Data(3))
>>> index.data

When you define an index class, you can define a default interface and/or a default interface:

>>> class Index(AttributeIndex, BaseIndex):
...     default_interface = I
...     default_field_name = 'y'
>>> index = Index()
>>> index.index_doc(11, Data(3))
>>> index.index_doc(22, Data(2))
>>> index.data
[(11, 9), (22, 4)]
default_field_name = None

Subclasses can set this to a string if they want to allow construction without passing the field_name.

default_interface = None

Subclasses can set this to an interface (a callable taking the object do index and the default value to return) if they want to allow construction that doesn’t provide an interface.

index_doc(docid, object)[source]

Derives the value to index for object.

Uses the interface passed to the constructor to adapt the object, and then gets the field (calling it if field_callable was set). If the value thus found is None, calls unindex_doc. Otherwise, passes the docid and the value to the superclass’s implementation of index_doc.

Field Indexes

Field catalog indexes

interface zope.catalog.field.IFieldIndex[source]

Extends: zope.catalog.interfaces.IAttributeIndex, zope.catalog.interfaces.ICatalogIndex

Interface-based catalog field index

class zope.catalog.field.FieldIndex(field_name=None, interface=None, field_callable=False, *args, **kwargs)[source]

Bases: zope.catalog.attribute.AttributeIndex, zope.index.field.index.FieldIndex, zope.container.contained.Contained

Default implementation of a IFieldIndex.

Keyword Indexes

Keyword catalog index

interface zope.catalog.keyword.IKeywordIndex[source]

Extends: zope.catalog.interfaces.IAttributeIndex, zope.catalog.interfaces.ICatalogIndex

Interface-based catalog keyword index

class zope.catalog.keyword.KeywordIndex(field_name=None, interface=None, field_callable=False, *args, **kwargs)[source]

Bases: zope.catalog.attribute.AttributeIndex, zope.index.keyword.index.KeywordIndex, zope.container.contained.Contained

Default implementation of IKeywordIndex.

class zope.catalog.keyword.CaseInsensitiveKeywordIndex(field_name=None, interface=None, field_callable=False, *args, **kwargs)[source]

Bases: zope.catalog.attribute.AttributeIndex, zope.index.keyword.index.CaseInsensitiveKeywordIndex, zope.container.contained.Contained

A kind of IKeywordIndex that is not sensitive to case.

Text Indexes

Text catalog indexes

interface zope.catalog.text.ITextIndex[source]

Extends: zope.catalog.interfaces.IAttributeIndex, zope.catalog.interfaces.ICatalogIndex

Interface-based catalog text index.

We redefine the fields that zope.catalog.interfaces.IAttributeIndex defines in order to change their defaults.



Objects will be adapted to this interface. The default is zope.index.text.interfaces.ISearchableText


Field Name

Name of the field to index. Defaults to getSearchableText.


Field Callable

If true (the default), then the field should be called to get the value to be indexed

class zope.catalog.text.TextIndex(field_name=None, interface=None, field_callable=False, *args, **kwargs)[source]

Bases: zope.catalog.attribute.AttributeIndex, zope.index.text.textindex.TextIndex, zope.container.contained.Contained

Default implementation of ITextIndex.