xapian-haystack/README.rst

Xapian backend for Django-Haystack
==================================

.. _Travis: https://travis-ci.org/notanumber/xapian-haystack

.. image:: https://travis-ci.org/notanumber/xapian-haystack.svg?branch=master
   :target: https://travis-ci.org/notanumber/xapian-haystack

Xapian-haystack is a backend of `Django-Haystack <http://haystacksearch.org/>`_
for the `Xapian <http://xapian.org>`_ search engine.
Thanks for checking it out.

You can find more information about Xapian `here <http://getting-started-with-xapian.readthedocs.org>`_.


Features
--------

Xapian-Haystack provides all the standard features of Haystack:

- Weighting
- Faceted search (date, query, etc.)
- Sorting
- Spelling suggestions


Requirements
------------

- Python 2.4+ (Python 3.3 not support `yet <http://trac.xapian.org/ticket/346>`_).
- Django 1.5+
- Django-Haystack 2.0.X
- Xapian 1.0.13+

In particular, this we build this backend on `Travis`_ using:

- Python 2.7.6
- Django 1.6.4
- Django-Haystack (latest)
- Xapian 1.2.8 (libxapian22)


Installation
------------

First you need to install Xapian in your machine.
We recommend installing it on the virtual environment using
`this gist <https://gist.github.com/jleclanche/ea0bc333b20ef6aa749c>`_:
activate the virtual environment and run the script.

You can test if the installation was successful by running::

    python -c "import xapian"

Finally, install Xapian-Haystack by running::

    pip install git+https://github.com/notanumber/xapian-haystack.git


Configuration
-------------

Xapian is configured as other backends of Haystack.
You have to define the connection to the database,
which is done to a path to a directory, e.g::

    HAYSTACK_CONNECTIONS = {
        'default': {
            'ENGINE': 'xapian_backend.XapianEngine',
            'PATH': os.path.join(os.path.dirname(__file__), 'xapian_index')
        },
    }

The backend has the following optional settings:

- ``HAYSTACK_XAPIAN_LANGUAGE``: the stemming language; the default is `english` and the list of available languages
  can be found `here <http://xapian.org/docs/apidoc/html/classXapian_1_1Stem.html>`_.

- ``HAYSTACK_XAPIAN_WEIGHTING_SCHEME``: the weighting scheme used for documents;
  the default is `BM25 <https://en.wikipedia.org/wiki/Okapi_BM25>`_ but others can be chosen from
  `this list <http://getting-started-with-xapian.readthedocs.org/en/latest/howtos/weighting_scheme.html>`_.

- ``HAYSTACK_XAPIAN_FLAGS``: the options used to parse `AutoQueries`;
  the default is ``FLAG_PHRASE | FLAG_BOOLEAN | FLAG_LOVEHATE | FLAG_WILDCARD | FLAG_PURE_NOT``
  See `here <http://xapian.org/docs/apidoc/html/classXapian_1_1QueryParser.html>`_ for more information
  on what they mean.


Testing
-------

Xapian-Haystack has a test suite in continuous deployment in `Travis`_. The script ``.travis.yml`` contains
all the steps required to run the test suite.

Other way is to clone `Django-Haystack <https://github.com/toastdriven/django-haystack>`_,
copy the content of the ``tests/`` folder of Xapian-Haystack to the ``tests/`` folder of Haystack,
and copy ``xapian_backend.py`` to ``haystack/backends/`` folder.

The tests can then be run from the folder ``tests/`` using::

django-admin.py test --settings=xapian_settings xapian_tests


Source
------

The source code can be found in `github <http://github.com/notanumber/xapian-haystack/>`_.


Credits
-------

Xapian-Haystack is maintained by Jorge C. Leitão;
`David Sauve <mailto:david.sauve@bag-of-holding.com>`_ was the main contributor of Xapian-Haystack and
Xapian-Haystack was originally funded by `Trapeze <http://www.trapeze.com>`_.


License
-------

Xapian-haystack is free software licenced under GNU General Public Licence v2 and
Copyright (c) 2009, 2010, 2011, 2012 David Sauve, 2009, 2010 Trapeze, 2014 Jorge C. Leitão.
It may be redistributed under the terms specified in the LICENSE file.

Questions, Comments, Concerns:
------------------------------

Feel free to open an issue `here <http://github.com/notanumber/xapian-haystack/issues>`_
or pull request your work.

You can ask questions on the django-haystack `mailing list <http://groups.google.com/group/django-haystack/>`_
or in the irc ``#haystack``.