Python bindings for Xapian

The Python bindings for Xapian are packaged in the xapian module, and largely follow the C++ API, with the following differences and additions. Python strings and lists, etc., are converted automatically in the bindings, so generally it should just work as expected.

The examples subdirectory contains examples showing how to use the Python bindings based on the simple examples from xapian-examples: simpleindex.py, simplesearch.py, simpleexpand.py. There's also simplematchdecider.py which shows how to define a MatchDecider in Python.

Exceptions

Exceptions are thrown as SWIG exceptions instead of Xapian exceptions. This isn't done well at the moment; in future we will throw wrapped Xapian exceptions. For now, it's probably easier to catch all exceptions and try to take appropriate action based on their associated string.

Iterators

All iterators support next() and equals() methods to move through and test iterators (as for all language bindings). MSetIterator and ESetIterator also support prev(). Python-wrapped iterators also support direct comparison, so something like:

   m=mset.begin()
   while m!=mset.end():
     # do something
     m.next()

Iterator dereferencing

C++ iterators are often dereferenced to get information, eg (*it). With Python these are all mapped to named methods, as follows:

Other methods, such as MSetIterator.get_document(), are available unchanged.

Pythonic iterators

Provided you're using Python 2.2 or newer, many classes that support C++-style iterators also support Pythonic iterators which do the same thing in a Python style. The following are supported (where marked as default iterator, it means __iter__() does the right thing so you can for instance use for term in document to iterate over terms in the Document):

The Pythonic iterators will all return lists representing the appropriate item when their next() method is called, except PositionIter which just returns a single value:

MSet

MSet objects have some additional methods to simplify access (these work using the C++ array dereferencing):

Additionally, the MSet has a property, mset.items, which returns a list of tuples representing the MSet; this may be more convenient than using the MSetIterator. The members of the tuple are as follows.

Two MSet objects are equal if they have the same number and maximum possible number of members, and if every document member of the first MSet exists at the same index in the second MSet, with the same weight.

ESet

The ESet has a property, eset.items, which returns a list of tuples representing the ESet; this may be more convenient than using the ESetIterator. The members of the tuple are as follows.

Database Factory Functions

• Xapian::Auto::open_stub() is wrapped as xapian.open_stub()
• Xapian::Quartz::open() is wrapped as xapian.quartz_open()
• Xapian::InMemory::open() is wrapped as xapian.inmemory_open()
• Xapian::Remote::open() is wrapped as xapian.remote_open() (only the TCP version is currently wrapped, the "program" version isn't).

Query

In C++ there's a Xapian::Query constructor which takes a query operator and start/end iterators specifying a number of terms or queries, plus an optional parameter. In Python, this is wrapped to accept any Python sequence (for example a list or tuple) to give the terms/queries, and you can specify a mixture of terms and queries if you wish. For example:

   subq = xapian.Query(xapian.Query.OP_AND, "hello", "world")
   q = xapian.Query(xapian.Query.OP_AND, [subq, "foo", xapian.Query("bar", 2)])

Enquire

There is an additional method get_matching_terms() which takes an MSetIterator and returns a list of terms in the current query which match the document given by that iterator. You may find this more convenient than using the TermIterator directly.

MatchDecider

Custom MatchDeciders can be created in Python; simply subclass xapian.MatchDecider, ensure you call the super-constructor, and define a __call__ method that will do the work. The simplest example (which does nothing useful) would be as follows:

class mymatchdecider(xapian.MatchDecider):
  def __init__(self):
    xapian.MatchDecider.__init__(self)

  def __call__(self, doc):
    return 1