notmuch2 - python3 compatible bindings to notmuch

These bindings use CFFI to generate the bindings making it work well
with both CPython and PyPy.  They try to ensure all operations
from within Python are safe and handle the memory management themselves.

Building notmuch2
-----------------

The provided setup.py file can be used to build and install the
bindings.  You will need python3, setuptools and cffi installed for
this to work.

By default this will assume that the C compiler can find both
notmuch.h and libnotmuch.so.5, if these are installed in a system-wide
location they will normally be found there.  When building notmuch
with make it will ensure that the C compiler finds the in-tree version
of notmuch instead of any system-wide one which might be available.
However the resulting python module is not relocatable and is mainly
used by the notmuch test suite.  For installing your own notmuch
python package it is recommended to first install libnotmuch system
wide and than use setup.py to build and install the python package.

If you really need to customise your build environment, have a look at
the INCUDE_DIRS, LIBRARY_DIRS and EXTRA_LINK_ARGS variables in
notmuch2/_build.py.

Documentation
-------------

The package has extensive docstrings, these docs are also included in
the general notmuch sphinx documentation.  See the notmuch `doc/`
subdirectory for this.


Development
-----------

An easy way to work on the bindings themselves is to create a
virtualenv to work in.  Install the python bindings in editable mode
using:

$ cd bindings/python-cffi
$ pip install -e .

However as described above this will build against the system-wide
notmuch installation.  If you need to work on the currently developed
libnotmuch you can invoke pip with some extra --global-option
arguments.  This is rather verbose, so the pip-editable-build.sh
script does this for you:

$ make
$ cd bindings/python-cffi
$ ./pip-editable-build.sh

Tests are written using pytest and can be run using:

$ pip install pytest pytest-cov
$ pytest

Individual tests can be selected:

$ pytest tests/test_database.py::TestCreate::test_create