==============================
How to implement a new backend
==============================

Index
=====

* Subclass :class:`whoosh.index.Index`.

* Indexes must implement the following methods.

  * :meth:`whoosh.index.Index.is_empty`

  * :meth:`whoosh.index.Index.doc_count`

  * :meth:`whoosh.index.Index.reader`

  * :meth:`whoosh.index.Index.writer`

* Indexes that require/support locking must implement the following methods.

  * :meth:`whoosh.index.Index.lock`

  * :meth:`whoosh.index.Index.unlock`

* Indexes that support deletion must implement the following methods.

  * :meth:`whoosh.index.Index.delete_document`

  * :meth:`whoosh.index.Index.doc_count_all` -- if the backend has delayed
    deletion.

* Indexes that require/support versioning/transactions *may* implement the following methods.

  * :meth:`whoosh.index.Index.latest_generation`

  * :meth:`whoosh.index.Index.up_to_date`

  * :meth:`whoosh.index.Index.last_modified`

* Index *may* implement the following methods (the base class's versions are no-ops).

  * :meth:`whoosh.index.Index.optimize`

  * :meth:`whoosh.index.Index.close`


IndexWriter
===========

* Subclass :class:`whoosh.writing.IndexWriter`.

* IndexWriters must implement the following methods.

  * :meth:`whoosh.writing.IndexWriter.add_document`

  * :meth:`whoosh.writing.IndexWriter.add_reader`

* Backends that support deletion must implement the following methods.

  * :meth:`whoosh.writing.IndexWriter.delete_document`

* IndexWriters that work as transactions must implement the following methods.

  * :meth:`whoosh.reading.IndexWriter.commit` -- Save the additions/deletions done with
    this IndexWriter to the main index, and release any resources used by the IndexWriter.

  * :meth:`whoosh.reading.IndexWriter.cancel` -- Throw away any additions/deletions done
    with this IndexWriter, and release any resources used by the IndexWriter.


IndexReader
===========

* Subclass :class:`whoosh.reading.IndexReader`.

* IndexReaders must implement the following methods.

  * :meth:`whoosh.reading.IndexReader.__contains__`

  * :meth:`whoosh.reading.IndexReader.__iter__`

  * :meth:`whoosh.reading.IndexReader.iter_from`

  * :meth:`whoosh.reading.IndexReader.stored_fields`

  * :meth:`whoosh.reading.IndexReader.doc_count_all`

  * :meth:`whoosh.reading.IndexReader.doc_count`

  * :meth:`whoosh.reading.IndexReader.doc_field_length`

  * :meth:`whoosh.reading.IndexReader.field_length`

  * :meth:`whoosh.reading.IndexReader.max_field_length`

  * :meth:`whoosh.reading.IndexReader.postings`

  * :meth:`whoosh.reading.IndexReader.has_vector`

  * :meth:`whoosh.reading.IndexReader.vector`

  * :meth:`whoosh.reading.IndexReader.doc_frequency`

  * :meth:`whoosh.reading.IndexReader.frequency`

* Backends that support deleting documents should implement the following
  methods.

  * :meth:`whoosh.reading.IndexReader.has_deletions`
  * :meth:`whoosh.reading.IndexReader.is_deleted`

* Backends that support versioning should implement the following methods.

  * :meth:`whoosh.reading.IndexReader.generation`

* If the IndexReader object does not keep the schema in the ``self.schema``
  attribute, it needs to override the following methods.

  * :meth:`whoosh.reading.IndexReader.field`

  * :meth:`whoosh.reading.IndexReader.field_names`

  * :meth:`whoosh.reading.IndexReader.scorable_names`

  * :meth:`whoosh.reading.IndexReader.vector_names`

* IndexReaders *may* implement the following methods.

  * :meth:`whoosh.reading.DocReader.close` -- closes any open resources associated with the
    reader.


Matcher
=======

The :meth:`whoosh.reading.IndexReader.postings` method returns a
:class:`whoosh.matching.Matcher` object. You will probably need to implement
a custom Matcher class for reading from your posting lists.

* Subclass :class:`whoosh.matching.Matcher`.

* Implement the following methods at minimum.

  * :meth:`whoosh.matching.Matcher.is_active`

  * :meth:`whoosh.matching.Matcher.copy`

  * :meth:`whoosh.matching.Matcher.id`

  * :meth:`whoosh.matching.Matcher.next`

  * :meth:`whoosh.matching.Matcher.value`

  * :meth:`whoosh.matching.Matcher.value_as`

  * :meth:`whoosh.matching.Matcher.score`

* Depending on the implementation, you *may* implement the following methods
  more efficiently.

  * :meth:`whoosh.matching.Matcher.skip_to`

  * :meth:`whoosh.matching.Matcher.weight`

* If the implementation supports quality, you should implement the following
  methods.

  * :meth:`whoosh.matching.Matcher.supports_quality`

  * :meth:`whoosh.matching.Matcher.quality`

  * :meth:`whoosh.matching.Matcher.block_quality`

  * :meth:`whoosh.matching.Matcher.skip_to_quality`