iiisight 0.1__py3-none-any.whl

iiisight/__init__.py

@@ -0,0 +1,129 @@
+"""iiisight — a tolerant, async (and sync) Python client for consuming IIIF.
+
+This package is the read/consume side of IIIF: fetch a manifest or collection,
+normalize Presentation v2 to v3, walk the structure, and pull tile-aware image
+regions. See ``PLAN.md`` for the implementation plan; this module is the public
+entry point and currently exposes only the resolved package version.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from . import auth, content_state
+from .auth import (
+    AccessService,
+    AccessTokenService,
+    LogoutService,
+    ProbeResult,
+    ProbeService,
+    TokenResult,
+    find_probe_service,
+)
+from .client import (
+    AsyncClient,
+    Client,
+    fetch,
+    fetch_collection,
+    fetch_collection_sync,
+    fetch_manifest,
+    fetch_manifest_sync,
+    fetch_sync,
+)
+from .content_state import ContentState, ContentStateError
+from .diagnostics import Diagnostic, Severity
+from .errors import (
+    FetchError,
+    IIISightError,
+    ImageServiceNotLoaded,
+    UnexpectedDocumentError,
+    UnknownScaleFactor,
+)
+from .image import parse_info
+from .language import LanguageMap
+from .lint import LintReport, lint
+from .model import (
+    Agent,
+    Annotation,
+    AnnotationPage,
+    Canvas,
+    Collection,
+    ContentResource,
+    ImageService,
+    Link,
+    Manifest,
+    MetadataEntry,
+    Range,
+    Reference,
+    Selector,
+    Service,
+    Size,
+    SpecificResource,
+    TextualBody,
+    Tile,
+    TileSet,
+)
+from .normalize import normalize, parse_annotation_page
+from .search import find_search_service, parse_search_response, search_url
+
+try:
+    __version__ = _version("iiisight")
+except PackageNotFoundError:  # pragma: no cover - only hit when running from a source tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "normalize",
+    "parse_annotation_page",
+    "parse_info",
+    "find_search_service",
+    "search_url",
+    "parse_search_response",
+    "auth",
+    "find_probe_service",
+    "ProbeService",
+    "AccessService",
+    "AccessTokenService",
+    "LogoutService",
+    "ProbeResult",
+    "TokenResult",
+    "lint",
+    "LintReport",
+    "content_state",
+    "ContentState",
+    "ContentStateError",
+    "AsyncClient",
+    "Client",
+    "fetch",
+    "fetch_manifest",
+    "fetch_collection",
+    "fetch_sync",
+    "fetch_manifest_sync",
+    "fetch_collection_sync",
+    "IIISightError",
+    "FetchError",
+    "UnexpectedDocumentError",
+    "ImageServiceNotLoaded",
+    "UnknownScaleFactor",
+    "Diagnostic",
+    "Severity",
+    "LanguageMap",
+    "Agent",
+    "Annotation",
+    "AnnotationPage",
+    "Canvas",
+    "Collection",
+    "ContentResource",
+    "ImageService",
+    "Link",
+    "Manifest",
+    "MetadataEntry",
+    "Range",
+    "Reference",
+    "Selector",
+    "Service",
+    "Size",
+    "SpecificResource",
+    "TextualBody",
+    "Tile",
+    "TileSet",
+]

iiisight/auth.py

@@ -0,0 +1,215 @@
+"""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 :class:`~iiisight.model.Service`'s
+preserved ``raw`` JSON.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .language import LanguageMap
+from .model import Canvas, ContentResource, Described, Service
+
+PROBE_TYPE = "AuthProbeService2"
+ACCESS_TYPE = "AuthAccessService2"
+TOKEN_TYPE = "AuthAccessTokenService2"
+LOGOUT_TYPE = "AuthLogoutService2"
+
+
+@dataclass(frozen=True)
+class LogoutService:
+    """An ``AuthLogoutService2``."""
+
+    id: str
+    label: LanguageMap | None = None
+
+
+@dataclass(frozen=True)
+class AccessTokenService:
+    """An ``AuthAccessTokenService2`` — where a token is obtained."""
+
+    id: str
+    error_heading: LanguageMap | None = None
+    error_note: LanguageMap | None = None
+
+
+@dataclass(frozen=True)
+class AccessService:
+    """An ``AuthAccessService2`` — where the user authenticates."""
+
+    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
+
+
+@dataclass(frozen=True)
+class ProbeService:
+    """An ``AuthProbeService2`` — the entry point to a resource's auth flow."""
+
+    id: str
+    access_services: tuple[AccessService, ...] = ()
+
+    @property
+    def token_service(self) -> AccessTokenService | None:
+        """The first access token service among the access services, if any."""
+        for access in self.access_services:
+            if access.token_service is not None:
+                return access.token_service
+        return None
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    """The result of calling a probe service (``AuthProbeResult2``)."""
+
+    status: int
+    location: str | None = None
+    heading: LanguageMap | None = None
+    note: LanguageMap | None = None
+
+    @property
+    def accessible(self) -> bool:
+        """True when the resource is accessible with the credentials supplied."""
+        return self.status == 200
+
+
+@dataclass(frozen=True)
+class TokenResult:
+    """The result of a non-interactive token exchange."""
+
+    access_token: str | None = None
+    expires_in: int | None = None
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.access_token is not None
+
+
+def find_probe_service(resource: Described | ContentResource | Service) -> ProbeService | None:
+    """Find the auth probe service on a resource, if it is access-controlled.
+
+    Accepts a :class:`Canvas` (searches its images' services), a
+    :class:`ContentResource`, a bare :class:`Service`, or any resource with a
+    ``services`` list.
+    """
+    for service in _candidate_services(resource):
+        probe = probe_service_from(service)
+        if probe is not None:
+            return probe
+    return None
+
+
+def probe_service_from(service: Service) -> ProbeService | None:
+    """Parse a :class:`Service` into a :class:`ProbeService`, or ``None``."""
+    raw = service.raw or {}
+    if (service.type or raw.get("type")) != PROBE_TYPE:
+        return None
+    access = tuple(
+        _access_service(entry)
+        for entry in _as_list(raw.get("service"))
+        if isinstance(entry, Mapping) and entry.get("type") == ACCESS_TYPE
+    )
+    return ProbeService(id=service.id, access_services=access)
+
+
+def parse_probe_result(document: Mapping[str, Any]) -> ProbeResult:
+    """Parse an ``AuthProbeResult2`` document."""
+    location = document.get("location")
+    if isinstance(location, Mapping):
+        location_id = location.get("id") or location.get("@id")
+    elif isinstance(location, str):
+        location_id = location
+    else:
+        location_id = None
+    return ProbeResult(
+        status=int(document.get("status", 200)),
+        location=str(location_id) if location_id else None,
+        heading=_lang(document.get("heading")),
+        note=_lang(document.get("note")),
+    )
+
+
+def parse_token_result(document: Mapping[str, Any]) -> TokenResult:
+    """Parse an ``AuthAccessToken2`` (or error) document."""
+    token = document.get("accessToken")
+    if token:
+        return TokenResult(access_token=str(token), expires_in=document.get("expiresIn"))
+    error = document.get("profile") or document.get("error") or document.get("type")
+    return TokenResult(error=str(error) if error else "unknown")
+
+
+def _candidate_services(resource: Described | ContentResource | Service) -> list[Service]:
+    if isinstance(resource, Service):
+        return [resource]
+    if isinstance(resource, ContentResource):
+        return list(resource.services)
+    if isinstance(resource, Canvas):
+        collected: list[Service] = []
+        for image in resource.images:
+            collected.extend(image.services)
+        collected.extend(resource.services)
+        return collected
+    return list(getattr(resource, "services", ()) or ())
+
+
+def _access_service(raw: Mapping[str, Any]) -> AccessService:
+    token_service: AccessTokenService | None = None
+    logout_service: LogoutService | None = None
+    for entry in _as_list(raw.get("service")):
+        if not isinstance(entry, Mapping):
+            continue
+        if entry.get("type") == TOKEN_TYPE:
+            token_service = AccessTokenService(
+                id=str(entry.get("id", "")),
+                error_heading=_lang(entry.get("errorHeading")),
+                error_note=_lang(entry.get("errorNote")),
+            )
+        elif entry.get("type") == LOGOUT_TYPE:
+            logout_service = LogoutService(
+                id=str(entry.get("id", "")), label=_lang(entry.get("label"))
+            )
+    return AccessService(
+        id=str(raw.get("id", "")),
+        profile=raw.get("profile"),
+        label=_lang(raw.get("label")),
+        heading=_lang(raw.get("heading")),
+        note=_lang(raw.get("note")),
+        confirm_label=_lang(raw.get("confirmLabel")),
+        token_service=token_service,
+        logout_service=logout_service,
+    )
+
+
+def _lang(value: Any) -> LanguageMap | None:
+    if isinstance(value, Mapping):
+        return LanguageMap(
+            {key: val if isinstance(val, list) else [val] for key, val in value.items()}
+        )
+    if isinstance(value, str):
+        return LanguageMap({"none": [value]})
+    return None
+
+
+def _as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]

iiisight/client.py

@@ -0,0 +1,339 @@
+"""The client facades: :class:`AsyncClient` (flagship) and :class:`Client` (sync).
+
+Both fetch IIIF documents over HTTP and hand the body to
+:func:`~iiisight.normalize.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.
+"""
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import TypeVar
+
+import httpx
+
+from .auth import (
+    AccessTokenService,
+    ProbeResult,
+    ProbeService,
+    TokenResult,
+    parse_probe_result,
+    parse_token_result,
+)
+from .errors import FetchError, UnexpectedDocumentError
+from .image import parse_info
+from .model import (
+    AnnotationPage,
+    Canvas,
+    Collection,
+    Described,
+    ImageService,
+    Manifest,
+    Reference,
+    Service,
+)
+from .normalize import normalize
+from .search import parse_search_response, search_url
+from .transport import ACCEPT, DEFAULT_TIMEOUT, afetch_json, fetch_json
+
+#: Default cap on concurrent fetches when expanding a collection (async only).
+DEFAULT_CONCURRENCY = 8
+
+_Doc = TypeVar("_Doc", Manifest, Collection)
+
+
+def _image_service_of(target: ImageService | Canvas) -> ImageService:
+    """Resolve an ImageService from a service or a canvas's primary image."""
+    if isinstance(target, ImageService):
+        return target
+    if isinstance(target, Canvas):
+        service = target.image_service
+        if service is None:
+            raise UnexpectedDocumentError("canvas has no image service to load")
+        return service
+    raise UnexpectedDocumentError(f"cannot load info for a {type(target).__name__}")
+
+
+def _info_url(service: ImageService) -> str:
+    return f"{service.id.rstrip('/')}/info.json"
+
+
+def _finalize(document: Manifest | Collection, final_url: str) -> Manifest | Collection:
+    """Fill an absent document id from the URL it was fetched from."""
+    if not document.id:
+        return replace(document, id=final_url)
+    return document
+
+
+def _expect(document: Manifest | Collection, kind: type[_Doc]) -> _Doc:
+    """Return ``document`` if it is ``kind``, else raise UnexpectedDocumentError."""
+    if not isinstance(document, kind):
+        raise UnexpectedDocumentError(
+            f"expected a {kind.__name__} but fetched a {type(document).__name__}"
+        )
+    return document
+
+
+class AsyncClient:
+    """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.
+    """
+
+    def __init__(
+        self,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        concurrency: int = DEFAULT_CONCURRENCY,
+    ):
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._concurrency = concurrency
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying httpx client, unless it was supplied externally."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def fetch(self, url: str) -> Manifest | Collection:
+        """Fetch and normalize a manifest or collection (auto-detected)."""
+        body, final_url = await afetch_json(self._http, url)
+        return _finalize(normalize(body), final_url)
+
+    async def fetch_manifest(self, url: str) -> Manifest:
+        """Fetch a URL expected to be a Manifest."""
+        return _expect(await self.fetch(url), Manifest)
+
+    async def fetch_collection(self, url: str) -> Collection:
+        """Fetch a URL expected to be a Collection."""
+        return _expect(await self.fetch(url), Collection)
+
+    async def resolve(self, reference: Reference) -> Manifest | Collection:
+        """Fetch the document a reference points at."""
+        return await self.fetch(reference.id)
+
+    async def expand(self, collection: Collection) -> list[Manifest | Collection]:
+        """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``).
+        """
+        semaphore = asyncio.Semaphore(self._concurrency)
+
+        async def _one(item: Manifest | Collection | Reference) -> Manifest | Collection:
+            if isinstance(item, Reference):
+                async with semaphore:
+                    return await self.fetch(item.id)
+            return item
+
+        return list(await asyncio.gather(*(_one(item) for item in collection.items)))
+
+    async def load_info(self, target: ImageService | Canvas) -> ImageService:
+        """Fetch an image service's ``info.json`` and return the loaded service."""
+        service = _image_service_of(target)
+        body, _ = await afetch_json(self._http, _info_url(service))
+        return parse_info(body)
+
+    async def fetch_region(
+        self, service: ImageService, region: str = "full", size: str = "max", **url_kwargs: str
+    ) -> bytes:
+        """Fetch the image bytes for a region/size from an image service."""
+        url = service.url(region=region, size=size, **url_kwargs)
+        try:
+            response = await self._http.get(url, follow_redirects=True)
+            response.raise_for_status()
+            return response.content
+        except httpx.HTTPError as exc:
+            raise FetchError(url, str(exc)) from exc
+
+    async def search(
+        self,
+        target: Described | Service | str,
+        query: str,
+        params: Mapping[str, str] | None = None,
+    ) -> AnnotationPage:
+        """Run a Content Search against a resource's search service.
+
+        Args:
+            target: A manifest/canvas (its search service is discovered), a
+                :class:`Service`, or a search base URL.
+            query: The search query string.
+            params: Extra query parameters (e.g. ``motivation``, ``date``).
+
+        Returns:
+            An :class:`AnnotationPage` of hit annotations.
+        """
+        body, _ = await afetch_json(self._http, search_url(target, query, params))
+        return parse_search_response(body)
+
+    async def probe(self, probe_service: ProbeService, token: str | None = None) -> ProbeResult:
+        """Call an auth probe service to check access, optionally with a token."""
+        headers = {"Accept": ACCEPT}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        try:
+            response = await self._http.get(
+                probe_service.id, headers=headers, follow_redirects=True
+            )
+            response.raise_for_status()
+            return parse_probe_result(response.json())
+        except httpx.HTTPError as exc:
+            raise FetchError(probe_service.id, str(exc)) from exc
+        except ValueError as exc:
+            raise FetchError(probe_service.id, f"probe response was not valid JSON: {exc}") from exc
+
+    async def access_token(self, token_service: AccessTokenService) -> TokenResult:
+        """Non-interactive token exchange against an access token service."""
+        body, _ = await afetch_json(self._http, token_service.id)
+        return parse_token_result(body)
+
+
+class Client:
+    """A synchronous IIIF client — the same surface as :class:`AsyncClient`
+    without ``await``. Use as a context manager."""
+
+    def __init__(
+        self,
+        *,
+        http_client: httpx.Client | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying httpx client, unless it was supplied externally."""
+        if self._owns_client:
+            self._http.close()
+
+    def fetch(self, url: str) -> Manifest | Collection:
+        """Fetch and normalize a manifest or collection (auto-detected)."""
+        body, final_url = fetch_json(self._http, url)
+        return _finalize(normalize(body), final_url)
+
+    def fetch_manifest(self, url: str) -> Manifest:
+        """Fetch a URL expected to be a Manifest."""
+        return _expect(self.fetch(url), Manifest)
+
+    def fetch_collection(self, url: str) -> Collection:
+        """Fetch a URL expected to be a Collection."""
+        return _expect(self.fetch(url), Collection)
+
+    def resolve(self, reference: Reference) -> Manifest | Collection:
+        """Fetch the document a reference points at."""
+        return self.fetch(reference.id)
+
+    def expand(self, collection: Collection) -> list[Manifest | Collection]:
+        """Resolve a collection's items one level deep, preserving order."""
+        return [
+            self.fetch(item.id) if isinstance(item, Reference) else item
+            for item in collection.items
+        ]
+
+    def load_info(self, target: ImageService | Canvas) -> ImageService:
+        """Fetch an image service's ``info.json`` and return the loaded service."""
+        service = _image_service_of(target)
+        body, _ = fetch_json(self._http, _info_url(service))
+        return parse_info(body)
+
+    def fetch_region(
+        self, service: ImageService, region: str = "full", size: str = "max", **url_kwargs: str
+    ) -> bytes:
+        """Fetch the image bytes for a region/size from an image service."""
+        url = service.url(region=region, size=size, **url_kwargs)
+        try:
+            response = self._http.get(url, follow_redirects=True)
+            response.raise_for_status()
+            return response.content
+        except httpx.HTTPError as exc:
+            raise FetchError(url, str(exc)) from exc
+
+    def search(
+        self,
+        target: Described | Service | str,
+        query: str,
+        params: Mapping[str, str] | None = None,
+    ) -> AnnotationPage:
+        """Run a Content Search against a resource's search service."""
+        body, _ = fetch_json(self._http, search_url(target, query, params))
+        return parse_search_response(body)
+
+    def probe(self, probe_service: ProbeService, token: str | None = None) -> ProbeResult:
+        """Call an auth probe service to check access, optionally with a token."""
+        headers = {"Accept": ACCEPT}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        try:
+            response = self._http.get(probe_service.id, headers=headers, follow_redirects=True)
+            response.raise_for_status()
+            return parse_probe_result(response.json())
+        except httpx.HTTPError as exc:
+            raise FetchError(probe_service.id, str(exc)) from exc
+        except ValueError as exc:
+            raise FetchError(probe_service.id, f"probe response was not valid JSON: {exc}") from exc
+
+    def access_token(self, token_service: AccessTokenService) -> TokenResult:
+        """Non-interactive token exchange against an access token service."""
+        body, _ = fetch_json(self._http, token_service.id)
+        return parse_token_result(body)
+
+
+# --- Module-level convenience -----------------------------------------------
+
+
+async def fetch(url: str) -> Manifest | Collection:
+    """One-shot async fetch of a manifest or collection."""
+    async with AsyncClient() as client:
+        return await client.fetch(url)
+
+
+async def fetch_manifest(url: str) -> Manifest:
+    """One-shot async fetch of a Manifest."""
+    async with AsyncClient() as client:
+        return await client.fetch_manifest(url)
+
+
+async def fetch_collection(url: str) -> Collection:
+    """One-shot async fetch of a Collection."""
+    async with AsyncClient() as client:
+        return await client.fetch_collection(url)
+
+
+def fetch_sync(url: str) -> Manifest | Collection:
+    """One-shot sync fetch of a manifest or collection."""
+    with Client() as client:
+        return client.fetch(url)
+
+
+def fetch_manifest_sync(url: str) -> Manifest:
+    """One-shot sync fetch of a Manifest."""
+    with Client() as client:
+        return client.fetch_manifest(url)
+
+
+def fetch_collection_sync(url: str) -> Collection:
+    """One-shot sync fetch of a Collection."""
+    with Client() as client:
+        return client.fetch_collection(url)