API reference

The complete public API, generated from the source docstrings. Everything here is importable directly from the top-level iiisight package (e.g. iiisight.AsyncClient, iiisight.Manifest).

Clients

The client facades: AsyncClient (flagship) and Client (sync).

Both fetch IIIF documents over HTTP and hand the body to normalize(), returning the normalized model with its diagnostics attached. All network I/O is explicit here — the model never fetches behind attribute access. expand() resolves a collection’s references, and resolve() fetches a single reference; both are the only ways to trigger the follow-on requests a collection or reference implies.

The two facades share every pure helper in this module; only the httpx call differs (async vs. sync). Class names mirror httpx so its users have no surprise.

iiisight.client.DEFAULT_CONCURRENCY = 8

Default cap on concurrent fetches when expanding a collection (async only).

class iiisight.client.AsyncClient(*, http_client=None, timeout=30.0, concurrency=8)[source]

Bases: object

An async IIIF client over a shared httpx.AsyncClient connection pool.

Use as an async context manager. Pass http_client to reuse an existing httpx.AsyncClient (e.g. with custom auth/caching); iiisight then does not close it.

Parameters:

  • http_client (AsyncClient | None)

  • timeout (float)

  • concurrency (int)

async aclose()[source]

Close the underlying httpx client, unless it was supplied externally.

Return type:

None

async fetch(url)[source]

Fetch and normalize a manifest or collection (auto-detected).

Parameters:

url (str)

Return type:

Manifest | Collection

async fetch_manifest(url)[source]

Fetch a URL expected to be a Manifest.

Parameters:

url (str)

Return type:

Manifest

async fetch_collection(url)[source]

Fetch a URL expected to be a Collection.

Parameters:

url (str)

Return type:

Collection

async resolve(reference)[source]

Fetch the document a reference points at.

Parameters:

reference (Reference)

Return type:

Manifest | Collection

async expand(collection)[source]

Resolve a collection’s items one level deep, preserving order.

Embedded items are returned as-is; references are fetched (concurrently, bounded by the client’s concurrency).

Parameters:

collection (Collection)

Return type:

list[Manifest | Collection]

async load_info(target)[source]

Fetch an image service’s info.json and return the loaded service.

Parameters:

target (ImageService | Canvas)

Return type:

ImageService

async fetch_region(service, region='full', size='max', **url_kwargs)[source]

Fetch the image bytes for a region/size from an image service.

Parameters:
Return type:

bytes

async search(target, query, params=None)[source]

Run a Content Search against a resource’s search service.

Parameters:

  • target (Described | Service | str) – A manifest/canvas (its search service is discovered), a Service, or a search base URL.

  • query (str) – The search query string.

  • params (Mapping[str, str] | None) – Extra query parameters (e.g. motivation, date).

Returns:

An AnnotationPage of hit annotations.

Return type:

AnnotationPage

async probe(probe_service, token=None)[source]

Call an auth probe service to check access, optionally with a token.

Parameters:
Return type:

ProbeResult

async access_token(token_service)[source]

Non-interactive token exchange against an access token service.

Parameters:

token_service (AccessTokenService)

Return type:

TokenResult

async check_compliance(target)[source]

Probe an image service for Image API conformance.

Loads info.json (if needed), then issues the requests appropriate to the claimed compliance level and verifies the returned image dimensions.

Parameters:

target (ImageService | Canvas | str) – an image service base URL, an ImageService, or a Canvas (its primary image service is used).

Return type:

ConformanceReport

async fetch_changes(url)[source]

Fetch a Change Discovery OrderedCollection (the activity stream).

Parameters:

url (str)

Return type:

ChangeCollection

async iter_activities(source, *, newest_first=True, since=None)[source]

Walk a change stream, yielding activities across pages.

Parameters:

  • source (ChangeCollection | str) – a change-collection URL or a fetched ChangeCollection.

  • newest_first (bool) – walk from last backwards (recent changes first); set False for an oldest-first full sync from first.

  • since (str | None) – an endTime string; only strictly-newer activities are yielded (and newest-first paging stops once it reaches older ones).

Return type:

AsyncIterator[Activity]

class iiisight.client.Client(*, http_client=None, timeout=30.0)[source]

Bases: object

A synchronous IIIF client — the same surface as AsyncClient without await. Use as a context manager.

Parameters:

  • http_client (Client | None)

  • timeout (float)

close()[source]

Close the underlying httpx client, unless it was supplied externally.

Return type:

None

fetch(url)[source]

Fetch and normalize a manifest or collection (auto-detected).

Parameters:

url (str)

Return type:

Manifest | Collection

fetch_manifest(url)[source]

Fetch a URL expected to be a Manifest.

Parameters:

url (str)

Return type:

Manifest

fetch_collection(url)[source]

Fetch a URL expected to be a Collection.

Parameters:

url (str)

Return type:

Collection

resolve(reference)[source]

Fetch the document a reference points at.

Parameters:

reference (Reference)

Return type:

Manifest | Collection

expand(collection)[source]

Resolve a collection’s items one level deep, preserving order.

Parameters:

collection (Collection)

Return type:

list[Manifest | Collection]

load_info(target)[source]

Fetch an image service’s info.json and return the loaded service.

Parameters:

target (ImageService | Canvas)

Return type:

ImageService

fetch_region(service, region='full', size='max', **url_kwargs)[source]

Fetch the image bytes for a region/size from an image service.

Parameters:
Return type:

bytes

search(target, query, params=None)[source]

Run a Content Search against a resource’s search service.

Parameters:
Return type:

AnnotationPage

probe(probe_service, token=None)[source]

Call an auth probe service to check access, optionally with a token.

Parameters:
Return type:

ProbeResult

access_token(token_service)[source]

Non-interactive token exchange against an access token service.

Parameters:

token_service (AccessTokenService)

Return type:

TokenResult

check_compliance(target)[source]

Probe an image service for Image API conformance (see AsyncClient).

Parameters:

target (ImageService | Canvas | str)

Return type:

ConformanceReport

fetch_changes(url)[source]

Fetch a Change Discovery OrderedCollection (the activity stream).

Parameters:

url (str)

Return type:

ChangeCollection

iter_activities(source, *, newest_first=True, since=None)[source]

Walk a change stream, yielding activities across pages (see AsyncClient).

Parameters:
Return type:

Iterator[Activity]

async iiisight.client.fetch(url)[source]

One-shot async fetch of a manifest or collection.

Parameters:

url (str)

Return type:

Manifest | Collection

async iiisight.client.fetch_manifest(url)[source]

One-shot async fetch of a Manifest.

Parameters:

url (str)

Return type:

Manifest

async iiisight.client.fetch_collection(url)[source]

One-shot async fetch of a Collection.

Parameters:

url (str)

Return type:

Collection

iiisight.client.fetch_sync(url)[source]

One-shot sync fetch of a manifest or collection.

Parameters:

url (str)

Return type:

Manifest | Collection

iiisight.client.fetch_manifest_sync(url)[source]

One-shot sync fetch of a Manifest.

Parameters:

url (str)

Return type:

Manifest

iiisight.client.fetch_collection_sync(url)[source]

One-shot sync fetch of a Collection.

Parameters:

url (str)

Return type:

Collection

Normalization

iiisight.normalize.normalize(document)[source]

Normalize a IIIF document into a Manifest or Collection.

Parameters:

document (Mapping[str, Any]) – A parsed IIIF JSON document.

Returns:

The normalized document, with any repairs recorded on .diagnostics.

Return type:

Manifest | Collection

iiisight.normalize.parse_annotation_page(document)[source]

Parse a standalone AnnotationPage (e.g. a Content Search response).

Accepts a v3 AnnotationPage (items) or a v2 sc:AnnotationList (resources), which is upgraded first.

Parameters:

document (Mapping[str, Any])

Return type:

AnnotationPage

Model

The normalized IIIF model — a v3-shaped consumer subset of the Presentation API, produced by iiisight.normalize.normalize().

Every type is a frozen dataclass and every collection field is a tuple defaulting to empty (never None), so tolerant traversal never trips on a missing list. Derived views (Canvas.images, Canvas.image_service) are pure properties over the parsed fields — they never perform I/O.

class iiisight.model.MetadataEntry(label, value)[source]

Bases: object

A single metadata (or requiredStatement) label/value pair.

Parameters:
label: LanguageMap
value: LanguageMap

Bases: object

An external link: homepage, rendering, seeAlso, or logo.

Parameters:
id: str
type: str | None = None
label: LanguageMap | None = None
format: str | None = None
profile: str | None = None
language: tuple[str, ...] = ()
class iiisight.model.Agent(id, type='Agent', label=None, homepage=(), logo=(), see_also=())[source]

Bases: object

A provider agent.

Parameters:
id: str
type: str = 'Agent'
label: LanguageMap | None = None
homepage: tuple[Link, ...] = ()
see_also: tuple[Link, ...] = ()
class iiisight.model.Selector(type, value=None, conforms_to=None)[source]

Bases: object

A target selector (fragment xywh/t, point, SVG, or Image API).

Parameters:

  • type (str)

  • value (str | None)

  • conforms_to (str | None)

type: str
value: str | None = None
conforms_to: str | None = None
class iiisight.model.SpecificResource(source, selector=None)[source]

Bases: object

A reference to part of a resource: a source id plus an optional selector.

Parameters:
source: str
selector: Selector | None = None
class iiisight.model.Reference(id, type, label=None)[source]

Bases: object

An unresolved pointer (a collection or range item): id/type/label only.

Parameters:
id: str
type: str
label: LanguageMap | None = None
class iiisight.model.Service(id, type=None, profile=None, label=None, context=None, raw=None)[source]

Bases: object

A non-image service on a resource (search, autocomplete, auth, …).

Image API services attach to a ContentResource as ImageService; this generic type carries the manifest/canvas-level services (e.g. a Content Search endpoint) so callers can discover them.

Parameters:
id: str
type: str | None = None
profile: str | None = None
label: LanguageMap | None = None
context: str | None = None
raw: Mapping[str, Any] | None = None

The original service JSON, preserved for specialized consumers (e.g. auth, whose nested services and fields fall outside this consumer subset).

class iiisight.model.Size(width, height)[source]

Bases: object

A discrete available image size from info.json sizes.

Parameters:
width: int
height: int
class iiisight.model.TileSet(width, height, scale_factors)[source]

Bases: object

A tiles entry: tile dimensions plus the scale factors it serves.

Parameters:
width: int
height: int | None
scale_factors: tuple[int, ...]
class iiisight.model.Tile(region, size, url)[source]

Bases: object

A single computed tile request (region/size/URL).

Parameters:
region: str
size: str
url: str
class iiisight.model.ImageService(id, api_version, compliance_level=None, loaded=False, protocol=None, width=None, height=None, max_width=None, max_height=None, max_area=None, sizes=(), tiles=(), preferred_formats=(), extra_formats=(), extra_qualities=(), extra_features=())[source]

Bases: object

An Image API service attached to a content resource.

Carries only what the manifest embedded (usually id + profile) until client.load_info() sets loaded and populates the rest from info.json. Phase 1 produces the unloaded stub; the loaded fields and the URL/tile helpers arrive in Phase 4.

Parameters:
id: str
api_version: int
compliance_level: str | None = None
loaded: bool = False
protocol: str | None = None
width: int | None = None
height: int | None = None
max_width: int | None = None
max_height: int | None = None
max_area: int | None = None
sizes: tuple[Size, ...] = ()
tiles: tuple[TileSet, ...] = ()
preferred_formats: tuple[str, ...] = ()
extra_formats: tuple[str, ...] = ()
extra_qualities: tuple[str, ...] = ()
extra_features: tuple[str, ...] = ()
url(region='full', size='max', rotation='0', quality='default', fmt=None)[source]

Build an Image API URL for this service.

size="max" emits full for a v2 service and max for v3 — the most common v2/v3 footgun — and other size tokens pass through unchanged.

Parameters:

  • region (str) – Region token (full, square, x,y,w,h, pct:...).

  • size (str) – Size token (max/full, w,, ,h, w,h, !w,h, pct:n).

  • rotation (str) – Rotation token.

  • quality (str) – Quality token.

  • fmt (str | None) – Format extension; defaults to a preferred format, else jpg.

Returns:

The assembled {id}/{region}/{size}/{rotation}/{quality}.{fmt} URL.

Return type:

str

thumbnail_url(width)[source]

Return a full-image URL near width px, preferring an advertised size.

When sizes are advertised (the level-0-safe path), the smallest size at least width wide is used, else the largest available; otherwise a plain {width}, size is requested.

Parameters:

width (int)

Return type:

str

tile_grid(scale_factor, quality='default', fmt=None)[source]

Enumerate the tile requests covering the whole image at scale_factor.

Requires a service populated by client.load_info().

Raises:
Parameters:

  • scale_factor (int)

  • quality (str)

  • fmt (str | None)

Return type:

list[Tile]

tile_pyramid()[source]

Enumerate tiles across every advertised scale factor (the full pyramid).

Return type:

list[Tile]

class iiisight.model.ContentResource(id, type, format=None, height=None, width=None, duration=None, label=None, language=(), service=(), services=())[source]

Bases: object

A painting/supplementing body: image, A/V, text, dataset, or model.

Parameters:
id: str
type: str
format: str | None = None
height: int | None = None
width: int | None = None
duration: float | None = None
label: LanguageMap | None = None
language: tuple[str, ...] = ()
service: tuple[ImageService, ...] = ()
services: tuple[Service, ...] = ()

Non-image services on the body (e.g. an auth probe service).

class iiisight.model.TextualBody(value='', type='TextualBody', format=None, language=())[source]

Bases: object

An inline textual annotation body (e.g. a comment).

Parameters:
value: str = ''
type: str = 'TextualBody'
format: str | None = None
language: tuple[str, ...] = ()
class iiisight.model.Annotation(id, type='Annotation', motivation=(), body=None, target=None)[source]

Bases: object

A Web Annotation: a motivation, a body, and a target.

Parameters:
id: str
type: str = 'Annotation'
motivation: tuple[str, ...] = ()
body: ContentResource | TextualBody | tuple[ContentResource | TextualBody, ...] | None = None
target: str | SpecificResource | None = None
class iiisight.model.AnnotationPage(id, type='AnnotationPage', items=())[source]

Bases: object

A page of annotations.

Parameters:
id: str
type: str = 'AnnotationPage'
items: tuple[Annotation, ...] = ()
class iiisight.model.Described(id, type, label=None, metadata=(), summary=None, required_statement=None, rights=None, provider=(), thumbnail=(), homepage=(), rendering=(), see_also=(), part_of=(), services=(), behavior=(), nav_date=None, raw=None)[source]

Bases: object

The Presentation “descriptive properties” shared by most resources.

Parameters:
id: str
type: str
label: LanguageMap | None = None
metadata: tuple[MetadataEntry, ...] = ()
summary: LanguageMap | None = None
required_statement: MetadataEntry | None = None
rights: str | None = None
provider: tuple[Agent, ...] = ()
thumbnail: tuple[ContentResource, ...] = ()
homepage: tuple[Link, ...] = ()
rendering: tuple[Link, ...] = ()
see_also: tuple[Link, ...] = ()
part_of: tuple[Reference, ...] = ()
services: tuple[Service, ...] = ()
behavior: tuple[str, ...] = ()
nav_date: str | None = None
raw: Mapping[str, Any] | None = None

The parsed JSON this resource was normalized from, preserved for consumers that need the source verbatim (e.g. a harvester archiving the original metadata). v2 inputs are upgraded to v3 first, so raw reflects the v3-shaped document the model was built from.

class iiisight.model.Canvas(id, type, label=None, metadata=(), summary=None, required_statement=None, rights=None, provider=(), thumbnail=(), homepage=(), rendering=(), see_also=(), part_of=(), services=(), behavior=(), nav_date=None, raw=None, height=None, width=None, duration=None, items=(), annotations=())[source]

Bases: Described

A view/page: spatial (height/width) and/or temporal (duration).

Parameters:
height: int | None = None
width: int | None = None
duration: float | None = None
items: tuple[AnnotationPage, ...] = ()
annotations: tuple[AnnotationPage, ...] = ()
property images: list[ContentResource]

Painting-annotation image bodies on this canvas, in document order.

property image_service: ImageService | None

The first Image API service on this canvas’s images, if any.

class iiisight.model.Range(id, type, label=None, metadata=(), summary=None, required_statement=None, rights=None, provider=(), thumbnail=(), homepage=(), rendering=(), see_also=(), part_of=(), services=(), behavior=(), nav_date=None, raw=None, items=(), start=None)[source]

Bases: Described

A structural range (table-of-contents node).

Parameters:
items: tuple[Canvas | Range | SpecificResource | Reference, ...] = ()
start: Canvas | SpecificResource | None = None
class iiisight.model.Manifest(id, type, label=None, metadata=(), summary=None, required_statement=None, rights=None, provider=(), thumbnail=(), homepage=(), rendering=(), see_also=(), part_of=(), services=(), behavior=(), nav_date=None, raw=None, canvases=(), structures=(), annotations=(), start=None, viewing_direction=None, diagnostics=<factory>)[source]

Bases: Described

A single object: its canvases, structures, and manifest-level annotations.

Parameters:
canvases: tuple[Canvas, ...] = ()
structures: tuple[Range, ...] = ()
annotations: tuple[AnnotationPage, ...] = ()
start: Canvas | SpecificResource | None = None
viewing_direction: str | None = None
diagnostics: tuple[Diagnostic, ...]
class iiisight.model.Collection(id, type, label=None, metadata=(), summary=None, required_statement=None, rights=None, provider=(), thumbnail=(), homepage=(), rendering=(), see_also=(), part_of=(), services=(), behavior=(), nav_date=None, raw=None, items=(), viewing_direction=None, diagnostics=<factory>)[source]

Bases: Described

A grouping of manifests and/or sub-collections (often as references).

Parameters:
items: tuple[Manifest | Collection | Reference, ...] = ()
viewing_direction: str | None = None
diagnostics: tuple[Diagnostic, ...]

Language maps

The LanguageMap value type for IIIF language maps.

IIIF represents human-readable strings (label, summary, metadata labels/values) as language maps: a mapping of BCP-47 language code to a list of string values, with the special key "none" for values with no language. LanguageMap wraps that shape so callers can pull a display string without hand-indexing {"en": ["..."]}.

class iiisight.language.LanguageMap(values=None)[source]

Bases: object

An immutable IIIF language map (lang -> list[str]).

Construct from a mapping of language code to a list of strings. The "none" key holds values with no associated language.

Parameters:

values (Mapping[str, Iterable[str]] | None)

languages()[source]

Return the language codes present, in insertion order.

Return type:

list[str]

get(language)[source]

Return the values for language (empty list if absent).

Parameters:

language (str)

Return type:

list[str]

text(language=None, separator=' ')[source]

Return a single display string.

Selection order: the requested language if given and present, else the no-language "none" values, else the first language present, else an empty string. Multiple values for the chosen language are joined with separator.

Parameters:

  • language (str | None) – Preferred language code, or None for the default order.

  • separator (str) – Joins multiple values for the chosen language.

Returns:

The chosen values joined into one string.

Return type:

str

Diagnostics

Structured diagnostics emitted while normalizing a IIIF document.

Tolerance is the core invariant: the normalizer never raises on a spec-imperfect document. Instead it repairs what it can and records each repair as a Diagnostic. Severity encodes how lossy the repair was; even ERROR never raises.

class iiisight.diagnostics.Severity(*values)[source]

Bases: Enum

How lossy a normalization repair was.

Variables:

  • INFO – Spec-sanctioned normalization (e.g. a default the spec allows).

  • WARNING – A deviation that was repaired (missing recommended field, coerced type) without losing information.

  • ERROR – Something that could not be represented and had to be dropped or skipped; the model is lossy at path but still usable, and no exception was raised.

INFO = 'info'
WARNING = 'warning'
ERROR = 'error'
class iiisight.diagnostics.Diagnostic(code, severity, path, message, recovered=None)[source]

Bases: object

A single repair the normalizer made to a document.

Variables:

  • code (str) – Stable machine-readable code, e.g. "coerced-language-map".

  • severity (iiisight.diagnostics.Severity) – How lossy the repair was.

  • path (str) – JSON pointer to the offending node ("" for the root).

  • message (str) – Human-readable description of what was wrong.

  • recovered (str | None) – What was assumed, coerced, or skipped to recover, if anything.

Parameters:
code: str
severity: Severity
path: str
message: str
recovered: str | None = None

Image API

iiisight.image.parse_info(info)[source]

Build a loaded ImageService from a parsed info.json document.

Parameters:

info (Mapping[str, Any])

Return type:

ImageService

Content Search

IIIF Content Search: discover a resource’s search service and parse results.

A manifest (or canvas) advertises a Content Search service in its service block; find_search_service() locates it. search_url() builds the query URL, and parse_search_response() normalizes the response — a v3 AnnotationPage or a v2 sc:AnnotationList — into an AnnotationPage of hit annotations. client.search() ties these together.

iiisight.search.find_search_service(resource)[source]

Return the Content Search service on a resource, or None.

Parameters:

resource (Described)

Return type:

Service | None

iiisight.search.search_url(target, query, params=None)[source]

Build a Content Search query URL for a resource, service, or base URL.

Parameters:
Return type:

str

iiisight.search.parse_search_response(document)[source]

Parse a Content Search response into an AnnotationPage of hits.

Parameters:

document (Mapping[str, Any])

Return type:

AnnotationPage

Content State

IIIF Content State API 1.0: decode and encode shareable references.

A content state points at a IIIF resource (a manifest, a canvas, a region of a canvas) in a form that can be passed around — most commonly a base64url-encoded (padding-stripped) JSON annotation, but also a plain resource URI or inline JSON. decode() turns any of those into a ContentState, whose reference can be handed to client.resolve to fetch the containing document. encode() produces the compact base64url token.

exception iiisight.content_state.ContentStateError[source]

Bases: IIISightError

A content-state token could not be decoded.

class iiisight.content_state.ContentState(target_id, target_type=None, part_of=None, region=None, raw=None)[source]

Bases: object

A decoded content state.

Variables:

  • target_id (str) – The referenced resource id (a canvas, manifest, etc.).

  • target_type (str | None) – Its type, if known.

  • part_of (str | None) – The containing manifest id, if the target is within one.

  • region (str | None) – A selector/fragment value (e.g. xywh=0,0,10,10), if any.

  • raw (dict[str, Any] | None) – The decoded annotation, when the token carried one.

Parameters:

  • target_id (str)

  • target_type (str | None)

  • part_of (str | None)

  • region (str | None)

  • raw (dict[str, Any] | None)

target_id: str
target_type: str | None = None
part_of: str | None = None
region: str | None = None
raw: dict[str, Any] | None = None
property reference: Reference

A Reference to the fetchable document.

Prefers the containing manifest (part_of) when known — a canvas URI is often not directly dereferenceable — else the target itself.

iiisight.content_state.decode(token)[source]

Decode a content-state token into a ContentState.

Parameters:

token (str)

Return type:

ContentState

iiisight.content_state.encode(target_id, *, target_type='Canvas', part_of=None, region=None)[source]

Encode a reference as a base64url content-state token (padding stripped).

Parameters:

  • target_id (str)

  • target_type (str)

  • part_of (str | None)

  • region (str | None)

Return type:

str

Authorization Flow

IIIF Authorization Flow 2.0 (metadata + non-interactive token exchange).

iiisight describes the auth services on a resource and can drive the non-interactive parts of the flow — probing whether a resource is accessible and exchanging for an access token where the token service is directly callable (e.g. an external profile relying on cookies). The interactive login step (opening the access service in a browser and reading the token via postMessage) is inherently the host application’s job and is out of scope; iiisight gives you the service metadata to drive it.

The auth services are a nested tree (AuthProbeService2 → AuthAccessService2 → AuthAccessTokenService2 / AuthLogoutService2) carrying fields outside the normalized subset, so they are parsed from each Service’s preserved raw JSON.

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

Bases: object

An AuthLogoutService2.

Parameters:
id: str
label: LanguageMap | None = None
class iiisight.auth.AccessTokenService(id, error_heading=None, error_note=None)[source]

Bases: object

An AuthAccessTokenService2 — where a token is obtained.

Parameters:
id: str
error_heading: LanguageMap | None = None
error_note: LanguageMap | None = None
class iiisight.auth.AccessService(id, profile=None, label=None, heading=None, note=None, confirm_label=None, token_service=None, logout_service=None)[source]

Bases: object

An AuthAccessService2 — where the user authenticates.

Parameters:
id: str
profile: str | None = None
label: LanguageMap | None = None
heading: LanguageMap | None = None
note: LanguageMap | None = None
confirm_label: LanguageMap | None = None
token_service: AccessTokenService | None = None
logout_service: LogoutService | None = None
class iiisight.auth.ProbeService(id, access_services=())[source]

Bases: object

An AuthProbeService2 — the entry point to a resource’s auth flow.

Parameters:
id: str
access_services: tuple[AccessService, ...] = ()
property token_service: AccessTokenService | None

The first access token service among the access services, if any.

class iiisight.auth.ProbeResult(status, location=None, heading=None, note=None)[source]

Bases: object

The result of calling a probe service (AuthProbeResult2).

Parameters:
status: int
location: str | None = None
heading: LanguageMap | None = None
note: LanguageMap | None = None
property accessible: bool

True when the resource is accessible with the credentials supplied.

class iiisight.auth.TokenResult(access_token=None, expires_in=None, error=None)[source]

Bases: object

The result of a non-interactive token exchange.

Parameters:

  • access_token (str | None)

  • expires_in (int | None)

  • error (str | None)

access_token: str | None = None
expires_in: int | None = None
error: str | None = None
property ok: bool
iiisight.auth.find_probe_service(resource)[source]

Find the auth probe service on a resource, if it is access-controlled.

Accepts a Canvas (searches its images’ services), a ContentResource, a bare Service, or any resource with a services list.

Parameters:

resource (Described | ContentResource | Service)

Return type:

ProbeService | None

iiisight.auth.probe_service_from(service)[source]

Parse a Service into a ProbeService, or None.

Parameters:

service (Service)

Return type:

ProbeService | None

iiisight.auth.parse_probe_result(document)[source]

Parse an AuthProbeResult2 document.

Parameters:

document (Mapping[str, Any])

Return type:

ProbeResult

iiisight.auth.parse_token_result(document)[source]

Parse an AuthAccessToken2 (or error) document.

Parameters:

document (Mapping[str, Any])

Return type:

TokenResult

Lint

Consumer-oriented lint over the diagnostics a normalization produced.

This is the byproduct the tolerance design unlocks: because normalize() records every repair it made, a lint is just a reporting view over document.diagnostics — “what did a real client have to guess or fix to read this document?” It is client-compatibility feedback, not a strict spec-conformance check.

class iiisight.lint.LintReport(diagnostics)[source]

Bases: object

The diagnostics from normalizing a document, organized for reporting.

Parameters:

diagnostics (tuple[Diagnostic, ...])

diagnostics: tuple[Diagnostic, ...]
property errors: tuple[Diagnostic, ...]

Diagnostics where information was dropped or skipped.

property warnings: tuple[Diagnostic, ...]

Diagnostics for deviations that were repaired without loss.

property infos: tuple[Diagnostic, ...]

Diagnostics for spec-sanctioned normalizations.

property ok: bool

True when nothing beyond informational normalization occurred.

counts()[source]

Return the diagnostic count for every severity (zero-filled).

Return type:

dict[Severity, int]

summary()[source]

A one-line human summary, e.g. "1 error, 2 warnings, 3 info".

Return type:

str

iiisight.lint.lint(document)[source]

Lint a IIIF document.

Parameters:

document (Manifest | Collection | Mapping[str, Any]) – An already-normalized Manifest/Collection, or a raw parsed JSON dict (which is normalized first).

Returns:

A LintReport over the document’s diagnostics.

Return type:

LintReport

Conformance

Image API conformance probing.

Given a loaded ImageService, this plans a battery of Image API requests appropriate to the service’s claimed compliance level, and — for requests whose output size is predictable — verifies that the server returns an image of the expected pixel dimensions, not merely an HTTP 200.

Dimensions are read straight from the returned image’s header (JPEG / PNG / GIF) with image_size(), so no image-decoding dependency is required. When a response is in a format we can’t measure, the check verifies reachability only and says so. The client drives the requests (iiisight.AsyncClient.check_compliance()); the planning and evaluation here are pure.

class iiisight.conformance.Check(name, level, url, ok, detail)[source]

Bases: object

The result of a single conformance request.

Parameters:
name: str
level: str
url: str
ok: bool
detail: str
class iiisight.conformance.ConformanceReport(service_id, claimed_level, checks)[source]

Bases: object

The result of probing an image service.

Parameters:
service_id: str
claimed_level: str | None
checks: tuple[Check, ...]
property conforms: bool

True if every check at or below the claimed level passed.

When the level is unknown, every check must pass.

property passed: tuple[Check, ...]
property failed: tuple[Check, ...]
summary()[source]
Return type:

str

class iiisight.conformance.CheckSpec(name, level, url, expected)[source]

Bases: NamedTuple

A planned request: what to fetch and the expected output dimensions.

Parameters:
name: str

Alias for field number 0

level: str

Alias for field number 1

url: str

Alias for field number 2

expected: tuple[int, int] | None

Alias for field number 3

iiisight.conformance.plan_checks(service)[source]

Plan the conformance requests for a loaded image service.

Parameters:

service (ImageService)

Return type:

list[CheckSpec]

iiisight.conformance.evaluate(spec, status, content_type, data)[source]

Turn an HTTP response to a planned request into a Check.

Parameters:
Return type:

Check

iiisight.conformance.image_size(data)[source]

Read (width, height) from an image’s header, without decoding pixels.

Supports PNG, JPEG, and GIF — the formats IIIF Image API servers return in practice. Returns None for anything else.

Parameters:

data (bytes)

Return type:

tuple[int, int] | None

Change Discovery

IIIF Change Discovery API 1.0: consume a repository’s activity stream.

A publisher exposes a W3C Activity Streams OrderedCollection of paged activities (Create / Update / Delete / …), each referencing a IIIF resource that changed. Harvesters walk the pages to discover changed resources and re-fetch them. This module models and parses that stream; the client (iiisight.AsyncClient.fetch_changes() / iter_activities) walks it.

Activities are ordered oldest → newest across the collection, so a harvester looking for recent changes walks from last backwards via prev (the default), while a full sync walks from first forwards via next.

class iiisight.discovery.Activity(type, object, end_time=None, id=None, actor=None)[source]

Bases: object

A single change activity referencing the resource that changed.

Parameters:
type: str
object: Reference | None
end_time: str | None = None
id: str | None = None
actor: str | None = None
property reference: Reference | None

The changed resource as a Reference (hand to client.resolve).

class iiisight.discovery.ActivityPage(id, items=(), next=None, prev=None, part_of=None, start_index=None)[source]

Bases: object

An OrderedCollectionPage of activities, with paging links.

Parameters:
id: str
items: tuple[Activity, ...] = ()
next: str | None = None
prev: str | None = None
part_of: str | None = None
start_index: int | None = None
class iiisight.discovery.ChangeCollection(id, total_items=None, first=None, last=None, items=())[source]

Bases: object

An OrderedCollection — the entry point to an activity stream.

Parameters:
id: str
total_items: int | None = None
first: str | None = None
last: str | None = None
items: tuple[Activity, ...] = ()
iiisight.discovery.parse_change_collection(document)[source]

Parse an OrderedCollection change-discovery document.

Parameters:

document (Mapping[str, Any])

Return type:

ChangeCollection

iiisight.discovery.parse_activity_page(document)[source]

Parse an OrderedCollectionPage of activities.

Parameters:

document (Mapping[str, Any])

Return type:

ActivityPage

iiisight.discovery.page_activities(page, newest_first, since)[source]

Return the activities to yield from a page and whether to stop paging.

Ordering within the stream is oldest → newest; newest_first reverses each page. since (an endTime string) filters to strictly-newer activities — when walking newest-first, reaching an older activity means paging can stop.

Parameters:
Return type:

tuple[list[Activity], bool]

Errors

Exception types raised by iiisight.

Tolerance covers document imperfection — a malformed manifest is repaired and reported via diagnostics, never raised. Genuine failures of the transport (a 404, a connection error, a non-JSON body) and caller-contract violations (asking fetch_manifest for a URL that resolves to a Collection) are exceptional and raise these types.

exception iiisight.errors.IIISightError[source]

Bases: Exception

Base class for all errors raised by iiisight.

exception iiisight.errors.FetchError(url, message)[source]

Bases: IIISightError

A document could not be retrieved or decoded.

Variables:

url – The URL that was being fetched.

Parameters:
exception iiisight.errors.UnexpectedDocumentError[source]

Bases: IIISightError

A fetched document was not of the type the caller asked for.

exception iiisight.errors.ImageServiceNotLoaded[source]

Bases: IIISightError

A tile/region operation needs an ImageService populated by load_info().

exception iiisight.errors.UnknownScaleFactor[source]

Bases: IIISightError

A tile was requested at a scale factor the service does not advertise.