Skip to main content

Database backend for Annotator (

Project description

Annotator Store

This is a backend store for Annotator.

The functionality can roughly be separated in two parts:

  1. An abstraction layer wrapping Elasticsearch, to easily manage annotation storage. It features authorization to filter search results according to their permission settings.

  2. A Flask blueprint for a web server that exposes an HTTP API to the annotation storage. To use this functionality, build this package with the [flask] option.

Getting going

You’ll need a recent version of Python (Python 2 >=2.6 or Python 3 >=3.3) and ElasticSearch (>=1.0.0) installed.

The quickest way to get going requires the pip and virtualenv tools (easy_install virtualenv will get them both). Run the following in the repository root:

virtualenv pyenv
source pyenv/bin/activate
pip install -e .[flask]
cp annotator.cfg.example annotator.cfg

You should see something like:

* Running on
* Restarting with reloader...

If you wish to customize the configuration of the Annotator Store, make your changes to annotator.cfg or dive into

Additionally, the HOST and PORT environment variables override the default socket binding of address and port 5000.

Store API

The Store API is designed to be compatible with the Annotator. The annotation store, a JSON-speaking REST API, will be mounted at /api by default. See the Annotator documentation for details.

Running tests

We use nosetests to run tests. You can just pip install -e .[testing], ensure ElasticSearch is running, and then:

$ nosetests
Ran 86 tests in 19.171s


Alternatively (and preferably), you should install Tox, and then run tox. This will run the tests against multiple versions of Python (if you have them installed).

Please open an issue if you find that the tests don’t all pass on your machine, making sure to include the output of pip freeze.


All notable changes to this project will be documented in this file. This project endeavours to adhere to Semantic Versioning.

0.14.2 2015-07-17

  • FIXED: no longer mutates the passed query.

  • FIXED/BREAKING CHANGE: Document.get_by_uri() no longer returns a list for empty resultsets, instead returning None.

0.14.1 2015-03-05

  • FIXED: Document plugin doesn’t drop links without a type. The annotator client generates a typeless link from the document href. (#116)

  • ADDED: the search endpoint now supports ‘before’ and ‘after query parameters, which can be used to return annotations created between a specific time period.

0.14 - 2015-02-13

  • ADDED: the search endpoint now supports ‘sort’ and ‘order’ query parameters, which can be used to control the sort order of the returned results.

  • FIXED: previously only one document was returned when looking for equivalent documents (#110). Now the Document model tracks all discovered equivalent documents and keeps each document object up-to-date with them all.

  • BREAKING CHANGE: Document.get_all_by_uris() no longer exists. Use Document.get_by_uri() which should return a single document containing all equivalent URIs. (You may wish to update your index by fetching all documents and resaving them.)

  • FIXED: the search_raw endpoint no longer throws an exception when the ‘fields’ parameter is provided.

0.13.2 - 2014-12-03

  • Avoid a confusing error about reindexing when annotator is used as a library and not a standalone application (#107).

0.13.1 - 2014-12-03

  • Reindexer can run even when target exists.

0.13.0 - 2014-12-02

  • Slight changes to to ease subclassing it.

0.12.0 - 2014-10-06

  • A tool for migrating/reindexing elasticsearch ( was added (#103).

  • The store returns more appropriate HTTP response codes (#96).

  • Dropped support for ElasticSearch versions before 1.0.0 (#92).

  • The default search query has been changed from a term-filtered “match all” to a set of “match queries”, resulting in more liberal interpretations of queries (#89).

  • The default elasticsearch analyzer for annotation fields has been changed to “keyword” in order to provide more consistent case-sensitivity behaviours (#73, #88).

  • Made Flask an optional dependency: it is now possible to use the persistence components of the project without needing Flask (#76).

  • Python 3 compatibility (#72).

0.11.2 - 2014-07-25

  • SECURITY: Fixed bug that allowed authenticated users to overwrite annotations on which they did not have permissions (#82).

0.11.1 - 2014-04-09

  • Fixed support for using ElasticSearch instances behind HTTP Basic auth

0.11.0 - 2014-04-08

  • Add support for ElasticSearch 1.0

  • Create changelog

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

annotator-0.14.2-py2.py3-none-any.whl (22.5 kB view hashes)

Uploaded 2 7

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page