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.
The Python bindings come with a test suite, consisting of two test files:
smoketest.py and pythontest.py. These are run by the
"make check" command, or may be run manually. By default, they
will display the names of any tests which failed, and then display a count of
tests which run and which failed. The verbosity may be increased by setting
the "VERBOSE" environment variable: a value of 1 will display
detailed information about failures, and a value of 2 will display further
information about the progress of tests.
Xapian exceptions are translated into Python exceptions with the same names
and inheritance hierarchy as the C++ exception classes. The base class of
all Xapian exceptions is the xapian.Error class, and this in
turn is a child of the standard python exceptions.Exception
class.
This means that programs can trap all xapian exceptions using "except
xapian.Error", and can trap all exceptions which don't indicate that
the program should terminate using "except Exception".
The xapian Python bindings accept unicode strings as well as simple strings (ie, "str" type strings) at all places in the API which accept string data. Any unicode strings supplied will automatically be translated into UTF-8 simple strings before being passed to the Xapian core. The Xapian core is largely agnostic about character encoding, but in those places where it does process data in a character encoding dependent way it assumes that the data is in UTF-8. The Xapian Python bindings always return string data as simple strings.
Therefore, in order to avoid issues with character encodings, you should always pass text data to Xapian as unicode strings, or UTF-8 encoded simple strings. There is, however, no requirement for simple strings passed into Xapian to be valid UTF-8 encoded strings, unless they are being passed to a text processing routine (such as the query parser, or the stemming algorithms). For example, it is perfectly valid to pa