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


If you want per-object permissions on individual annotations (rather than the standard django type-based permissions), you must also install django-guardian and include guardian in your INSTALLED_APPS. Per-object permissions must be turned on in Django settings by setting ANNOTATION_OBJECT_PERMISSIONS to True.

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.


Per-object permissions require that a permissions plugin be included when you initialize your annotator.js Annotator object. That code is currently available as a plugin in the Readux codebase

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.

Files for annotator_store, version 0.6.0
Filename, size File type Python version Upload date Hashes
Filename, size annotator_store-0.6.0-py2-none-any.whl (798.3 kB) File type Wheel Python version 2.7 Upload date Hashes View
Filename, size annotator_store-0.6.0.tar.gz (790.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page