Skip to main content

Django application to act as an annotator.js 2.x annotator-store backend

Project description

Build Status Code Coverage Code Health Requirements Status Documentation Status

annotator_store is a Django application meant for use within a Django project as an annotator.js 2.x annotation store backend, and implements the Annotator Storage API.

annotator_store was originally develop as a component of Readux.


This software is distributed under the Apache 2.0 License.


Use pip to install:

pip install

You can also install from GitHub. Use branch or tag name, e.g. @develop or @1.0, to install a specific tagged release or branch:

pip install git+


Add annotator_store to installed applications and make sure that other required components are enabled:


Include the annotation storage API urls at the desired base url with the namespace:

from annotator_store import views as annotator_views

urlpatterns = [
    # annotations
    url(r'^annotations/api/', include('annotator_store.urls', namespace='annotation-api')),
    # annotatorjs doesn't handle trailing slash in api prefix url
    url(r'^annotations/api', annotator_views.AnnotationIndex.as_view(), name='annotation-api-prefix'),

Run migrations to create annotation database tables:

python migrate

Custom Annotation Model

This module is designed to allow the use of a custom Annotation model, in order to add functionality or relationships to other models within an application. To take advantage of this feature, you should extend the abstract model annotator_store.models.BaseAnnotation and configure your model in Django setings, e.g.:

ANNOTATOR_ANNOTATION_MODEL = 'myapp.LocalAnnotation'

If you want per-object permissions on your annotation model, you should extend annotator_store.models.AnnotationWithPermissions rather than the base annotation class.

Development instructions

This git repository uses git flow branching conventions.

Initial setup and installation:

  • recommended: create and activate a python virtualenv:

    virtualenv annotator-store
    source annotator-store/bin/activate
  • pip install the package with its python dependencies:

    pip install -e .

Unit Testing

Unit tests are run with py.test but use Django test classes for convenience and compatibility with django test suites. Running the tests requires a minimal settings file for Django required configurations.

  • Copy sample test settings and add a SECRET_KEY:

    cp ci/
  • To run the tests, either use the configured test command:

    python test
  • Or install test requirements and use py.test directly:

    pip install -e '.[test]'

Sphinx Documentation

  • To work with the sphinx documentation, install sphinx directly via pip or via:

    pip install -e '.[docs]'
  • Documentation can be built in the docs directory using:

    make html

Project details

Download files

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

Source Distribution

annotator_store-0.6.0.tar.gz (790.3 kB view hashes)

Uploaded Source

Built Distribution

annotator_store-0.6.0-py2-none-any.whl (798.3 kB view hashes)

Uploaded Python 2

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