Annotations

geniza.annotations provides a minimal implementation of the W3C annotation protocol to provide annotation storage for project transcriptions.

models

class geniza.annotations.models.Annotation(*args, **kwargs)

Annotation model for storing annotations in the database.

Annotations may be either block-level or line-level. Block-level annotation is the default; in most cases, a block-level annotation’s content is stored as a TextualBody in its content JSON.

However, block-level annotations may also be used to group line-level annotations, in which case they have no textual content themselves, except for an optional label. Instead, their content is serialized by joining TextualBody values from all associated line-level annotations.

Line-level annotations are associated with blocks via the block property, and that relationship is serialized as partOf at the root of the line-level annotation.

exception DoesNotExist

exception MultipleObjectsReturned

block

block-level annotation associated with this (line-level) annotation. if null, this is a block-level annotation. if a block is deleted, all associated lines will be deleted.

property block_content_html

convenience method to get HTML content, including label and any associated lines, of a block-level annotation, as a list of HTML strings

property body_content

convenience method to get annotation body content

canonical

optional canonical identifier, for annotations imported from another source

compile(include_context=True)

Combine annotation data and return as a dictionary that can be serialized as JSON. Includes context by default, but may be omitted when annotation will be included in context that already has it defined.

content

json content of the annotation. in addition to W3C Web Annotation Data Model properties, may also include: “schema:position”, which tracks the order of the annotation with respect to others in the same block or canvas; and “textGranularity”, which indicates whether this is a block- or line-level annotation

created

date created

property etag

Compute and return an md5 hash of content to use as an ETag.

NOTE: Only content can be modified in the editor, so it is the only hashed attribute. If other attributes become mutable, modify this function to include them in the ETag computation.

classmethod flatten_html_list(html_string)

If the passed-in html string has nested lists, this method flattens it to a single list of one level of items. The method doesn’t drop any item nor sub-item, instead it promotes the sub-items up as many levels as necessary to bring them all as the items of the single list

footnote

related scholarship record; used for source and manifest uri in JSON serialization

get_absolute_url()

url for this annotation (relative to the current application)

property has_lines

cached property to indicate whether or not this is a block-level annotation with line-level children

id

annotation id (uuid, autogenerated when created)

property label

convenience method to get annotation label

modified

date last modified

classmethod sanitize_html(html)

Sanitizes passed HTML according to allowed tags and attributes, stripping out any that are not allowed, and spans with no attributes.

set_content(data)

Set or update annotation content and model fields.

If via or canonical are set and the values differ in the new data, a ValueError exception will be raised and the data will not be saved.

property target_source_id

convenience method to access target source id

property target_source_manifest_id

convenience method to access manifest id for target source

uri()

URI for this annotation (absolute url)

via

uri of annotation when imported from another copy (optional)

class geniza.annotations.models.AnnotationQuerySet(model=None, query=None, using=None, hints=None)

by_target_context(uri)

filter queryset by the context of the target (i.e, the manifest the canvas belongs to)

group_by_canvas()

Aggregate annotations by canvas id; returns a dictionary of lists, keys are canvas ids, items are lists of annotations.

group_by_manifest()

Aggregate annotations by manifest uri; returns a dictionary of lists, keys are manifest uri, items are lists of annotations.

geniza.annotations.models.annotations_to_list(annotations, uri)

Generate an AnnotationList from a list of annotations. Must specify the uri for the annotation list id. Returns a dict that can be serialized as JSON.

views

class geniza.annotations.views.AnnotationDetail(**kwargs)

View to read, update, or delete a single annotation.

delete(request, *args, **kwargs)

delete the annotation on DELETE

dispatch(request, *args, **kwargs)

Wrap the dispatch method to add ETag/last modified headers when appropriate, then return a conditional response.

get(request, *args, **kwargs)

display as annotation

get_etag(request, *args, **kwargs)

Get etag from annotation

get_last_modified(request, *args, **kwargs)

Return last modified datetime.datetime

get_permission_required()

return permission required based on request method

model

alias of Annotation

post(request, *args, **kwargs)

update the annotation on POST

class geniza.annotations.views.AnnotationList(**kwargs)

Base annotation endpoint; on GET, returns an annotation collection; on POST with valid credentials and permissions, creates a new annotation.

get(request, *args, **kwargs)

generate annotation collection response on GET request

get_permission_required()

return permission required based on request method

model

alias of Annotation

post(request, *args, **kwargs)

“Create a new annotation

class geniza.annotations.views.AnnotationResponse(*args, **kwargs)

Base class for annotation responses; extends json response to set annotation profile content type.

class geniza.annotations.views.AnnotationSearch(**kwargs)

Simple seach endpoint based on IIIF Search API. Returns an annotation list response.

get(request, *args, **kwargs)

Search annotations and return an annotation list. Currently only supports search by target uri and source uri.

model

alias of Annotation

class geniza.annotations.views.ApiAccessMixin

geniza.annotations.views.parse_annotation_data(request)

For annotation create and update methods, parse json data from request in order to set/update associated footnote. Returns content dict and footnote object.