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.
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.
empty() methods
empty() methods are renamed to is_empty() in the bindings.
All iterators support next() and equals() methods to move through
and test iterators (as for all language bindings). Python-wrapped
iterators also support direct comparison, so something like:
m=mset.begin()
while m!=mset.end():
# do something
m.next()
C++ iterators are often dereferenced to get information, eg
(*it). With Python these are all mapped to named methods, as
follows:
| Iterator | Dereferencing method |
| PositionIterator | get_termpos() |
| PostingIterator | get_docid() |
| TermIterator | get_term() |
| ValueIterator | get_value() |
| MSetIterator | get_docid() |
| ESetIterator | get_termname() |
Other methods, such as MSetIterator.get_document(), are available unchanged.
MSet objects have some additional methods to simplify access (these work using the C++ array dereferencing):
| Method name | Explanation |
get_hit(index) | returns MSetIterator at index |
get_document_percentage(index) | convert_to_percent(get_hit(index)) |
get_document(index) | get_hit(index).get_document() |
get_document_id(index) | get_hit(index).get_docid() |
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.
| Index | Contents |
xapian.MSET_DID | Document id |
xapian.MSET_WT | Weight |
xapian.MSET_RANK | Rank |
xapian.MSET_PERCENT | Percentage weight |
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.
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.
| Index | Contents |
xapian.ESET_TNAME | Term name |
xapian.ESET_WT | Weight |
Functions in Xapian::Auto are mapped directly into the xapian
module (so Xapian::Auto::open() becomes xapian.open(), for
instance). The Xapian::Auto::DB_* constants are available as
xapian.DB_*.
Please note that although the source code for the bindings
indicates that there's another constructor to xapian.Query that
should be able to take a default query operator, a list of queries,
and an optional window, this doesn't actually work in Python at the
moment due to the way SWIG overloading works.
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. This may be slightly
more convenient than using the TermIterator directly.
The query parser and C++ wrapped stemmers are wrapped for Python as
xapian.QueryParser and xapian.Stem. The interfaces are identical to
the C++ versions.
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 mymatcher(xapian.MatchDecider):
def __init__(self):
xapian.MatchDecider.__init__(self)
def __call__(self, doc):
return 1
There are examples of the Python bindings, based on simplesearch and
simpleindex from xapian-examples, in the examples subdirectory. There is also an example of defining a MatchDecider in Python.