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 pass arbitrary binary
data in a simple string to the xapian.Document.set_data()
method.
It is often useful to normalise unicode data before passing it to Xapian -
Xapian currently has no built-in support for normalising unicode
representations of data. The standard python module
"unicodedata" provides support for normalising unicode: you
probably want the "NFKC" normalisation scheme: in other words,
use something like
unico