API reference

The public API of the djiiif package. Everything below is generated from the source docstrings, so it always matches the installed version.

Fields and accessor

class IIIFField(verbose_name=None, name=None, width_field=None, height_field=None, **kwargs)[source]

An ImageField whose field files carry IIIF URLs via .iiif.

attr_class

alias of IIIFFieldFile

class IIIFFieldFile(instance, field, name)[source]

An ImageFieldFile that exposes an .iiif accessor.

property iiif: IIIFObject

Return a freshly built IIIFObject for this field file.

class IIIFObject(parent)[source]

The .iiif accessor for a field file: profile URLs and documents.

Constructed fresh on each IIIFFieldFile.iiif access. For a populated field it eagerly sets one attribute per settings.IIIF_PROFILES name (the assembled Image API URL) plus info (the external info.json URL) and identifier (the plain {host}/{identifier} base URI). For an empty or unset field every URL attribute is the empty string.

The generated documents — info_document and manifest — are lazy cached_property values because, unlike the URL attributes, they read the image’s pixel dimensions from storage. Constructing an IIIFObject therefore never touches the file.

as_dict(*, include_meta=False)[source]

Return the profile URLs as a plain dict, keyed by profile name.

Handy for JSON APIs (see djiiif.serializers) and for iterating profiles in a template. For an empty/unset field every value is "".

Parameters:

include_meta (bool) – When true, also include the info and identifier URLs under those keys.

Returns:

A {profile_name: url} mapping, optionally with info and identifier entries appended.

Return type:

dict[str, str]

property info_document: dict | None

The IIIF Image API info.json document (not its URL).

Distinct from info, which returns the URL of an external info.json served by an image server. This builds the document here from the image’s own width/height and the identifier base URI, so a view can serve a minimal info.json without a separate image server (e.g. JsonResponse(field.iiif.info_document)).

Accessing this reads the image from storage; the eager URL attributes never do. Shape is controlled by settings.IIIF_IMAGE_API_VERSION (default 3) and settings.IIIF_COMPLIANCE_LEVEL (default "level2"). When settings.IIIF_AUTH resolves to a probe service for this image, its Authorization Flow 2.0 service block is included; when settings.IIIF_INFO resolves to extras for this image (see resolve_info()), those declarative properties (sizes, tiles, limits, rights, …) are emitted too.

Returns:

The info.json document, or None for an empty/unset field.

property manifest: dict | None

A minimal single-image IIIF Presentation API 3.0 Manifest.

Wraps this image in a one-canvas manifest suitable for Mirador or OpenSeadragon. The label defaults to the file’s base name. Like info_document, accessing this reads the image dimensions from storage. When settings.IIIF_AUTH resolves to a probe service for this image, its Authorization Flow 2.0 service block is attached to the image body. When settings.IIIF_MANIFEST_DESCRIPTORS resolves to a descriptor bag for this image (see resolve_manifest_descriptors()), its descriptive properties (metadata, rights, …) are emitted at the manifest top level. When settings.IIIF_NAVPLACE resolves to a geometry for this image (see djiiif.geo.resolve_navplace()), its navPlace FeatureCollection is emitted (with the navPlace @context).

Returns:

The manifest document, or None for an empty/unset field.

content_state(*, xywh=None, encoded=True)[source]

Build a IIIF Content State for a shareable deep link to this image.

Targets this image’s own Canvas (with a partOf back to its Manifest), deriving both URIs the same way manifest does — so the state opens the exact image the manifest describes. Pass xywh to open zoomed to a region. Unlike manifest, this reads nothing from storage.

Parameters:

  • xywh (str | tuple[int, int, int, int] | None) – An optional region as an x,y,w,h string or 4-tuple of ints; omit for a whole-image state.

  • encoded (bool) – When true (default), return the URL-safe encoded string ready to drop into ?iiif-content=; when false, return the raw content-state dict.

Returns:

The encoded string ("" for an empty/unset field), or the raw dict (None for an empty/unset field) when encoded is false.

Return type:

str | dict | None

Profiles

class Profile(host, region='full', size='max', rotation='0', quality='default', format='jpg', mirror=False, upscale=False)[source]

A typed, IIIF Image API 3.0-aware image profile.

A structured alternative to the raw dict profile shape, with 3.0-friendly defaults (size="max") and helpers for the two 3.0 features that are easy to get wrong as hand-written strings: mirroring (! rotation prefix) and upscaling (^ size prefix). Existing dict and callable profiles keep working unchanged; this is purely an additive, opt-in convenience.

Parameters:
host

Base URL of the IIIF image server.

Type:

str

region

IIIF region parameter ("full", "square", x,y,w,h…).

Type:

str

size

IIIF size parameter ("max", "w,", "w,h"…). If upscale is set and this does not already start with ^, a ^ prefix is added when the spec is built.

Type:

str

rotation

IIIF rotation in degrees as a string. If mirror is set and this does not already start with !, a ! prefix is added.

Type:

str

quality

IIIF quality ("default", "color", "gray"…).

Type:

str

format

IIIF output format extension ("jpg", "png", "webp"…).

Type:

str

mirror

When true, mirror the image (adds the ! rotation prefix).

Type:

bool

upscale

When true, permit upscaling beyond the region (adds the ^ size prefix).

Type:

bool

as_spec()[source]

Resolve this profile to the plain dict spec the builders consume.

Folds mirror and upscale into the rotation and size strings, guarding against double-prefixing when the caller already supplied a !/^ prefix.

Returns:

A dict with the keys in PROFILE_KEYS.

Return type:

dict[str, str]

resolve_profile(profile, parent)[source]

Normalize any supported profile shape into a plain spec dict.

Accepts the three configured shapes — a Profile, a callable receiving parent and returning a Profile or dict, or a plain dict — and returns a uniform dict for URL assembly.

Parameters:

  • profile – The value from settings.IIIF_PROFILES for one profile name.

  • parent – The IIIFFieldFile passed to callable profiles.

Returns:

A resolved spec dict containing the keys in PROFILE_KEYS.

Raises:

ImproperlyConfigured – If profile (or a callable’s return value) is not a Profile, callable, or dict.

Return type:

dict[str, str]

image_url(spec, identifier)[source]

Assemble a full IIIF Image API request URL from a resolved spec.

Parameters:

  • spec (dict[str, str]) – A resolved profile spec (keys in PROFILE_KEYS).

  • identifier (str) – An already-encoded identifier segment (see encode_identifier()).

Returns:

The {host}/{identifier}/{region}/{size}/{rotation}/{quality}.{format} URL.

Return type:

str

encode_identifier(name)[source]

Percent-encode a field-file name into a IIIF identifier segment.

The IIIF Image API treats the identifier as a single path segment, so every character in the reserved to-encode set (/ ? # [ ] @ % and friends) must be percent-encoded — not just /. quote(safe="") encodes everything outside the unreserved set, which is a superset of the required behavior and keeps ordinary filenames (foo.jpg) untouched while correctly encoding a/b.jpg → a%2Fb.jpg and names containing spaces, ?, #, etc.

Parameters:

name (str) – The stored file name (e.g. "uploads/photo.jpg").

Returns:

The encoded identifier segment.

Return type:

str

Image & Presentation documents

build_info_document(id_url, width, height, *, version=None, level=None, auth=None, extras=None)[source]

Build a spec-conformant IIIF Image API info.json document.

Parameters:

  • id_url (str) – The image service base URI ({host}/{identifier}).

  • width (int) – Image width in pixels.

  • height (int) – Image height in pixels.

  • version (int | None) – Image API version (2 or 3); defaults to settings.IIIF_IMAGE_API_VERSION (3).

  • level (str | None) – Advertised compliance level; defaults to settings.IIIF_COMPLIANCE_LEVEL ("level2").

  • auth (dict | None) – An optional resolved Authorization Flow 2.0 probe-service dict (see resolve_auth()). When present it is added to the document’s service array; only valid at version 3.

  • extras (dict | None) – An optional normalized extras dict (see resolve_info()) of declarative properties — sizes, tiles, size limits, rights, preferred/extra capabilities. v2 accepts only sizes/tiles.

Returns:

The info.json document as a dict, ready for JsonResponse.

Raises:

ImproperlyConfigured – If version is unknown, auth is set while not on version 3, or an extras v3-only key is present at version 2.

Return type:

dict

build_manifest(id_url, width, height, *, label, version=None, level=None, auth=None, nav_place=None, **descriptors)[source]

Build a minimal single-image IIIF Presentation API 3.0 Manifest.

A thin wrapper over build_multi_manifest() for the common one-image case: the manifest wraps one image on one canvas so it opens directly in viewers like Mirador or OpenSeadragon. With no descriptors its output is identical to the historical single-image manifest.

Parameters:

  • id_url (str) – The image service base URI ({host}/{identifier}), reused as the image service id and as the stem for the synthetic URIs.

  • width (int) – Image width in pixels.

  • height (int) – Image height in pixels.

  • label – Human-readable label for the manifest (coerced via _language_map()).

  • version (int | None) – Image API version of the embedded image service (2 or 3); defaults to settings.IIIF_IMAGE_API_VERSION (3).

  • level (str | None) – Advertised compliance level; defaults to settings.IIIF_COMPLIANCE_LEVEL ("level2").

  • auth (dict | None) – An optional resolved Authorization Flow 2.0 probe-service dict (see resolve_auth()). When present it is added to the access-controlled image body’s service array; only valid at version 3.

  • nav_place (dict | None) – An optional GeoJSON FeatureCollection (see djiiif.geo.resolve_navplace()) emitted as the manifest’s navPlace; switches @context to the navPlace array.

  • **descriptors – Optional descriptive properties (keys in DESCRIPTOR_KEYS) emitted at the manifest top level.

Returns:

The manifest as a dict, ready for JsonResponse.

Raises:

ImproperlyConfigured – If version is unknown, auth is set while not on version 3, or a descriptor key is unknown.

Return type:

dict

build_multi_manifest(id_url, images, *, label, version=None, level=None, auth=None, nav_place=None, **descriptors)[source]

Build a multi-canvas IIIF Presentation API 3.0 Manifest.

Presents several images as one manifest — recto/verso, a paged object, detail shots — by repeating the single-canvas structure with per-canvas indexed id URIs. The document is always Presentation 3.0; each embedded image service reflects the Image API version.

Parameters:

  • id_url (str) – The manifest’s image service base URI ({host}/{identifier}), the stem for the synthetic manifest/canvas URIs.

  • images – A sequence of per-canvas specs — (service_id_url, width, height) tuples, or dicts with id / width / height and an optional label (see _normalize_image_spec()).

  • label – Manifest label (coerced via _language_map()).

  • version (int | None) – Image API version of the embedded image services (2 or 3); defaults to settings.IIIF_IMAGE_API_VERSION (3).

  • level (str | None) – Advertised compliance level; defaults to settings.IIIF_COMPLIANCE_LEVEL ("level2").

  • auth (dict | None) – An optional resolved Authorization Flow 2.0 probe-service dict applied to every image body; only valid at version 3.

  • nav_place (dict | None) – An optional GeoJSON FeatureCollection dict (see djiiif.geo.resolve_navplace()) emitted as the manifest’s navPlace. When present, @context becomes the two-element navPlace array and Features gain synthesized ids.

  • **descriptors – Optional descriptive properties (keys in DESCRIPTOR_KEYS) emitted at the manifest top level.

Returns:

The manifest as a dict, ready for JsonResponse.

Raises:

ImproperlyConfigured – If version is unknown, auth is set while not on version 3, or a descriptor key is unknown.

Return type:

dict

build_collection(id_url, items, *, label, **descriptors)[source]

Build a IIIF Presentation API 3.0 Collection of manifest references.

A Collection groups manifests for browsing — the natural rendering of a Django queryset (“all photos in this album”). It embeds only references to each manifest (id/type/label/thumbnail), never the manifests themselves, so even a large collection stays a small response.

Parameters:

  • id_url (str) – The Collection’s own id URI.

  • items – A sequence of member entries — (manifest_url, label) or (manifest_url, label, thumbnail) tuples, or already-formed member dicts (passed through). label is coerced via _language_map(); thumbnail via _thumbnail().

  • label – Collection label (coerced via _language_map()).

  • **descriptors – Optional descriptive properties (keys in DESCRIPTOR_KEYS) emitted at the collection top level.

Returns:

The Collection as a dict, ready for JsonResponse.

Raises:

ImproperlyConfigured – If a descriptor key is unknown.

Return type:

dict

class InfoExtras(sizes=None, tiles=None, max_width=None, max_height=None, max_area=None, rights=None, preferred_formats=None, extra_qualities=None, extra_formats=None, extra_features=None)[source]

Typed, opt-in optional info.json properties (a dual-shape helper).

A structured alternative to a raw dict for IIIF_INFO (the Profile/ProbeService precedent), with one field per optional Image API property. Every field defaults to None and is emitted only when set. djiiif does not verify these against the real image server — the operator declares what their server supports and djiiif advertises it.

Parameters:

  • sizes (list[dict] | None)

  • tiles (list[dict] | None)

  • max_width (int | None)

  • max_height (int | None)

  • max_area (int | None)

  • rights (str | None)

  • preferred_formats (list[str] | None)

  • extra_qualities (list[str] | None)

  • extra_formats (list[str] | None)

  • extra_features (list[str] | None)

sizes

Preferred complete-image sizes ([{"width": …, "height": …}]).

Type:

list[dict] | None

tiles

Tile descriptions ([{"width": …, "scaleFactors": [...]}]).

Type:

list[dict] | None

max_width / max_height / max_area

Server-enforced size limits.

rights

A license/rights URI (v3).

Type:

str | None

preferred_formats

Preferred output formats (v3).

Type:

list[str] | None

extra_qualities / extra_formats / extra_features

Capabilities beyond the compliance level (v3).

as_dict()[source]

Return the set (non-None) fields as a canonical-key dict.

Return type:

dict

resolve_info(parent)[source]

Resolve settings.IIIF_INFO to a normalized extras dict for an image.

Mirrors resolve_auth(): the setting may be a dict, an InfoExtras, a callable returning either (or None), or unset.

Parameters:

parent – The value passed to a callable config. On model paths this is the IIIFFieldFile; on view paths it is the decoded storage name (str) — both expose the identity a callable branches on. The documented callable signature is therefore parent: IIIFFieldFile | str.

Returns:

A normalized extras dict (empty when unset or resolved to None).

Raises:

ImproperlyConfigured – If the (resolved) value is not a dict, InfoExtras, or None, or carries an unknown/duplicate key.

Return type:

dict

Geolocation (navPlace)

resolve_navplace(parent)[source]

Resolve settings.IIIF_NAVPLACE to a navPlace FeatureCollection.

Mirrors djiiif.resolve_auth(). The setting may be a dotted-path string (imported), a callable, or a direct value; a callable is invoked with parent. The resolved value may be:

  • None — no navPlace,

  • a GeoJSON dict (bare geometry, Feature, or FeatureCollection),

  • a GEOS geometry (converted via .geojson; must be WGS84),

  • a (geometry_or_dict, label) pair — label coerced into the Feature’s properties (a language map).

Parameters:

parent – The value passed to a callable config. On model paths this is the IIIFFieldFile; on view paths it is the decoded storage name (str) — the parent: IIIFFieldFile | str convention.

Returns:

A normalized FeatureCollection dict, or None when unset/None.

Raises:

ImproperlyConfigured – If the resolved value is not an accepted shape, or a GEOS geometry is not WGS84.

Return type:

dict | None

Content State

build_content_state(manifest_id, *, canvas_id=None, xywh=None)[source]

Build a IIIF Content State API 1.0 annotation targeting a resource.

Produces the spec’s simplified target forms (Content State API 1.0 §3.2): with only manifest_id the state targets the Manifest; with canvas_id it targets that Canvas and carries a partOf back to the Manifest; xywh appends an #xywh= media-fragment to the canvas id to select a region.

Parameters:

  • manifest_id (str) – The Manifest URI (e.g. {host}/{identifier}/manifest).

  • canvas_id (str | None) – The Canvas URI to target within the manifest; omit to target the whole Manifest.

  • xywh (str | tuple[int, int, int, int] | None) – An optional region as an x,y,w,h string or 4-tuple of ints. Ignored when canvas_id is None.

Returns:

The content-state dict, ready for encode_content_state().

Return type:

dict

encode_content_state(state)[source]

Encode a content state for use as an iiif-content query parameter.

Implements the IIIF Content State API 1.0 §6 encoding: serialize to JSON (when given a dict), percent-encode the UTF-8 string exactly as JavaScript’s encodeURIComponent does, base64url-encode that, and strip the = padding. The percent-encoding step is part of the spec — the resulting string round-trips through any viewer’s decodeURIComponent.

Parameters:

state (dict | str) – A content-state dict (e.g. from build_content_state()) or a bare resource-URI str (the spec’s trivial form).

Returns:

The URL-safe, unpadded encoded string.

Return type:

str

decode_content_state(encoded)[source]

Decode an iiif-content value back into a content state.

The inverse of encode_content_state(): restore the stripped base64url padding, base64url-decode, reverse the percent-encoding, and json.loads the result. A payload that is not JSON (a bare resource-URI string) is returned verbatim.

Parameters:

encoded (str) – The encoded string from an iiif-content parameter.

Returns:

The decoded content-state dict, or the bare URI str for a non-JSON payload.

Return type:

dict | str

Change Discovery

class Activity(object_id, end_time, type='Update', object_type='Manifest')[source]

One IIIF Change Discovery activity over a IIIF resource.

The typed, opt-in shape for an IIIF_ACTIVITY_SOURCE entry — a structured alternative to a plain dict with the same keys and defaults, normalized by resolve_activity() (the Profile/ProbeService dual-shape precedent).

Parameters:
object_id

The activity object’s URL (a manifest or collection).

Type:

str

end_time

The modification timestamp — an aware datetime (serialized ISO 8601) or a preformed ISO 8601 string.

Type:

datetime.datetime | str

type

The activity type — "Update" (default) or "Create" (both level-1). "Delete" is level-2 and out of scope here.

Type:

str

object_type

The object’s IIIF type — "Manifest" (default) or "Collection".

Type:

str

resolve_activity(entry)[source]

Normalize an IIIF_ACTIVITY_SOURCE entry to a plain dict.

Mirrors resolve_profile(): an entry may be an Activity or a plain dict (with object_id / end_time required and type / object_type optional). Both normalize to a dict carrying every key with defaults applied.

Parameters:

entry – An Activity or a dict from the activity source.

Returns:

A dict with keys object_id, end_time, type, object_type.

Raises:

ImproperlyConfigured – If entry is neither an Activity nor a dict.

Return type:

dict

build_activity(object_id, end_time, *, activity_type='Update', object_type='Manifest')[source]

Build one ActivityStreams activity for an orderedItems list.

Parameters:

  • object_id (str) – The activity object’s URL (a manifest or collection).

  • end_time (datetime | str) – The modification timestamp — an aware datetime (serialized via .isoformat()) or a preformed ISO 8601 string.

  • activity_type (str) – The activity type ("Update" / "Create").

  • object_type (str) – The object’s IIIF type ("Manifest" / "Collection").

Returns:

The activity dict — {"type", "object": {"id", "type"}, "endTime"}. No @context (activities are always embedded in a page).

Return type:

dict

build_ordered_collection(id_url, total, first_url, last_url)[source]

Build the Change Discovery OrderedCollection entry point.

Parameters:

  • id_url (str) – The collection’s own URL.

  • total (int) – totalItems — the activity count across all pages.

  • first_url (str) – URL of the first OrderedCollectionPage.

  • last_url (str) – URL of the last OrderedCollectionPage.

Returns:

The OrderedCollection dict, ready for JsonResponse.

Return type:

dict

build_collection_page(id_url, collection_url, activities, *, prev_url=None, next_url=None, start_index=None)[source]

Build one Change Discovery OrderedCollectionPage.

Parameters:

  • id_url (str) – This page’s own URL.

  • collection_url (str) – URL of the owning OrderedCollection (emitted as partOf).

  • activities (list[dict]) – The page’s activities (see build_activity()), in ascending endTime order.

  • prev_url (str | None) – URL of the previous page; omitted on the first page.

  • next_url (str | None) – URL of the next page; omitted on the last page.

  • start_index (int | None) – 0-based index of this page’s first item within the whole stream; omitted when None.

Returns:

The OrderedCollectionPage dict, ready for JsonResponse.

Return type:

dict

Authorization Flow 2.0

class ProbeService(id, access=None)[source]

An Authorization Flow 2.0 probe service (AuthProbeService2).

The top of the nested auth service block and the value clients look for in an info.json / manifest. Use as an IIIF_AUTH value or return it from an IIIF_AUTH callable.

Parameters:
id

The probe service URI.

Type:

str

access

The nested AccessService.

Type:

djiiif.AccessService | None

as_dict()[source]

Serialize to the nested Auth 2.0 service dict.

Return type:

dict

class AccessService(id, profile='active', label=None, heading=None, note=None, confirm_label=None, token=None, logout=None)[source]

An Authorization Flow 2.0 access service (AuthAccessService2).

Parameters:
id

The access service URI.

Type:

str

profile

The interaction pattern — "active" (interactive login), "kiosk" (automatic), or "external" (ambient/IP).

Type:

str

label / heading / note / confirm_label

active-pattern UI text; each accepts a plain string, list of strings, or a IIIF language map.

token

The nested TokenService.

Type:

djiiif.TokenService | None

logout

The optional nested LogoutService.

Type:

djiiif.LogoutService | None

as_dict()[source]

Serialize to the nested Auth 2.0 service dict.

Return type:

dict

class TokenService(id)[source]

An Authorization Flow 2.0 access token service (AuthAccessTokenService2).

Parameters:

id (str)

as_dict()[source]

Serialize to the nested Auth 2.0 service dict.

Return type:

dict

class LogoutService(id, label=None)[source]

An Authorization Flow 2.0 logout service (AuthLogoutService2).

Parameters:
as_dict()[source]

Serialize to the nested Auth 2.0 service dict.

Return type:

dict

resolve_auth(parent)[source]

Resolve settings.IIIF_AUTH to a probe-service dict for an image.

Mirrors resolve_profile(): the setting may be a ProbeService, a raw dict, a callable receiving the field file and returning either (or None for a public image), or unset. Empty/public cases resolve to None so no auth block is emitted.

Parameters:

parent – The IIIFFieldFile passed to callable configs.

Returns:

The nested probe-service dict, or None when there is no auth.

Raises:

ImproperlyConfigured – If the (resolved) value is not a ProbeService, dict, or None.

Return type:

dict | None

Views and serializer

Drop-in views that serve IIIF documents for stored images.

Mounting djiiif.urls.urlpatterns turns a Django instance into a minimal provider of two documents built from a stored image: an Image API info.json (serve_info_json()) and a Presentation API manifest (serve_manifest()). Each maps an identifier back to a stored image, reads its dimensions, and returns the document built by the corresponding djiiif builder. Neither serves derivative pixels — only the JSON documents.

Two settings-driven views need no stored image: serve_collection() renders a browsable Collection of manifest references, and serve_activity_collection() / serve_activity_page() render a paged IIIF Change Discovery activity stream so aggregators can harvest what changed. serve_annotation_page() serves a W3C AnnotationPage (transcriptions/OCR/commentary) and serve_search() answers IIIF Content Search 2.0 queries; both draw from project-owned backend callables, and serve_manifest() advertises them when configured.

serve_info_json(request, identifier)[source]

Serve the info.json document for a stored image.

The document’s id is taken from the request URL (minus the /info.json suffix) so it always matches the URL the document is served from, as the spec requires. When settings.IIIF_INFO is configured, its declarative extras are threaded in; a per-image IIIF_INFO callable receives the decoded storage name here (there is no field file on the view path — see djiiif.resolve_info()).

Parameters:

  • request – The incoming HttpRequest.

  • identifier – The encoded identifier segment captured by the URLconf.

Returns:

A JSON-LD JsonResponse carrying the info.json document.

Raises:

Http404 – If the identifier does not resolve to a readable image.

serve_manifest(request, identifier)[source]

Serve a single-image Presentation API manifest for a stored image.

The image service base URI is the request URL minus the /manifest suffix, matching the identifier the info.json view serves. The manifest label defaults to the file’s base name.

When IIIF_ANNOTATIONS_BACKEND is configured, the canvas gains an annotations reference to this image’s AnnotationPage; when a search backend is available (a dedicated IIIF_SEARCH_BACKEND or the annotations fallback), the manifest advertises a SearchService2. Both are view-only — IIIFObject.manifest (no request in scope) emits neither. When IIIF_NAVPLACE is configured its callable receives the decoded storage name here (no field file on the view path) and its geometry is emitted as navPlace.

Parameters:

  • request – The incoming HttpRequest.

  • identifier – The encoded identifier segment captured by the URLconf.

Returns:

A JSON-LD JsonResponse carrying the manifest document.

Raises:

Http404 – If the identifier does not resolve to a readable image.

serve_collection(request)[source]

Serve a IIIF Collection of manifest references.

Driven by the IIIF_COLLECTION_SOURCE setting — a callable returning an iterable of member entries ((manifest_url, label[, thumbnail]) tuples or preformed member dicts, per djiiif.build_collection()) and, optionally, a label for the collection itself. When the setting is unset the endpoint does not exist, so it returns 404.

The collection’s id is the request URL, so it always matches where it is served from. The response reads no image storage — it references manifests by URL only.

Parameters:

request – The incoming HttpRequest.

Returns:

A JSON-LD JsonResponse carrying the Collection document.

Raises:

Http404 – If IIIF_COLLECTION_SOURCE is unset.

serve_activity_collection(request)[source]

Serve the Change Discovery OrderedCollection entry point.

Driven by IIIF_ACTIVITY_SOURCE (see _activity_paginator()). The collection’s id is the request URL; first/last point at the page routes. Reads no image storage.

Parameters:

request – The incoming HttpRequest.

Returns:

A JSON-LD JsonResponse carrying the OrderedCollection.

Raises:

Http404 – If IIIF_ACTIVITY_SOURCE is unset.

serve_activity_page(request, page)[source]

Serve one Change Discovery OrderedCollectionPage.

The page’s activities are the source entries for this slice, resolved via djiiif.resolve_activity() and built with djiiif.build_activity(), kept in the source’s ascending-endTime order (the source owns that contract; djiiif does not re-sort). prev/next are emitted at the interior boundaries only.

Parameters:

  • request – The incoming HttpRequest.

  • page – The 1-based page number (captured by the <int:page> route).

Returns:

A JSON-LD JsonResponse carrying the OrderedCollectionPage.

Raises:

Http404 – If IIIF_ACTIVITY_SOURCE is unset or page is out of range.

serve_annotation_page(request, identifier)[source]

Serve a W3C AnnotationPage for a stored image.

Draws its annotations from the IIIF_ANNOTATIONS_BACKEND callable (identifier, request) -> iterable of Annotation / dict entries. The annotations target {id_url}/canvas/1, matching the canvas serve_manifest() emits. Reads no image storage.

Parameters:

  • request – The incoming HttpRequest.

  • identifier – The encoded identifier segment captured by the URLconf.

Returns:

A JSON-LD JsonResponse carrying the AnnotationPage.

Raises:

Http404 – If IIIF_ANNOTATIONS_BACKEND is unset.

Answer a IIIF Content Search 2.0 query for a stored image.

Uses IIIF_SEARCH_BACKEND (identifier, q, request) -> iterable of hits when configured; otherwise falls back to a case-insensitive substring match over IIIF_ANNOTATIONS_BACKEND (so serving annotations yields search for free). A missing or empty q returns a valid empty page — never the whole corpus. Unimplemented spec parameters (motivation/date/user) are echoed in ignored. Reads no image storage.

Parameters:

  • request – The incoming HttpRequest.

  • identifier – The encoded identifier segment captured by the URLconf.

Returns:

A JSON-LD JsonResponse carrying the search AnnotationPage.

Raises:

Http404 – If neither a search nor an annotations backend is configured.

class IIIFSerializerField(*args, **kwargs)[source]

A read-only DRF field that serializes an IIIFField to its profile URLs.

Declare it on a serializer with the model’s IIIF field as the source:

class AssetSerializer(serializers.ModelSerializer):
    original = IIIFSerializerField()

    class Meta:
        model = Asset
        fields = ["id", "original"]

The representation is djiiif.IIIFObject.as_dict(), i.e. a {profile_name: url} mapping (with info/identifier included when include_meta is set).

Parameters:

include_meta (bool)

include_meta

Passed through to as_dict to include the info and identifier URLs.

to_representation(value)[source]

Serialize an IIIFFieldFile to its profile URL mapping.

Parameters:

value – The IIIFFieldFile attribute value for the source field.

Returns:

The {profile_name: url} mapping from value.iiif.as_dict.

Return type:

dict[str, str]