Content State¶

The Content State API encodes a shareable reference to a IIIF resource or region — as a plain URI, inline JSON, or a base64url-encoded annotation. iiisight decodes any of these into a ContentState, and encodes new ones.

Decoding¶

state = iiisight.content_state.decode(token)

state.target_id     # the referenced resource (a canvas, manifest, …)
state.part_of       # the containing manifest id, if the target is within one
state.region        # a selector/fragment like "xywh=0,0,50,50", if any

ContentState.reference gives you a Reference you can hand straight to the client — it points at the fetchable document (the containing manifest when known, since a canvas URI is often not directly dereferenceable):

Async

state = iiisight.content_state.decode(token)
async with iiisight.AsyncClient() as client:
    doc = await client.resolve(state.reference)

Sync

state = iiisight.content_state.decode(token)
with iiisight.Client() as client:
    doc = client.resolve(state.reference)

Invalid tokens raise ContentStateError.

Encoding¶

token = iiisight.content_state.encode(
    "https://example.org/canvas/1",
    part_of="https://example.org/manifest",
    region="xywh=0,0,50,50",
)

This produces the compact base64url form (padding stripped), ready to put in a URL or share.