scistudio.previewers.models

Canonical import root: from scistudio.previewers.models import ...

Self-contained public-API reference — 21 symbols from this module's __all__, with signatures and docstrings inlined (ADR-052 §7). Generated; do not hand-edit.

EnvelopeKind — enum

Stability: provisional · Since 0.3.1

class EnvelopeKind(StrEnum)

The display kind a PreviewEnvelope declares for its payload.

These are the previewer-domain kinds. They are deliberately distinct from the older REST preview.kind strings (table / image / chart / text / composite / artifact); the API runtime maps between the two so existing callers and tests keep working.

FrontendManifest — class

Stability: provisional · Since 0.3.1

class FrontendManifest
FrontendManifest(previewer_id: 'str', module_url: 'str', export_name: 'str' = 'default', css: 'tuple[str, ...]' = (), version: 'str' = '0', api_version: 'str' = '1', asset_root: 'str | None' = None) -> None

Describes the same-origin UI bundle a previewer ships for the frontend.

A package or project previewer can include a small JavaScript module (and optional CSS) that the frontend loads at runtime to render a custom view. This descriptor tells the frontend what to import; the backend validates it and confines every asset read under asset_root before serving anything, and it refuses remote (http/https) URLs.

Example: >>> manifest = FrontendManifest( ... previewer_id="acme.image.viewer", ... module_url="/api/previews/assets/abc123", ... export_name="ImageViewer", ... ) >>> "asset_root" in manifest.to_dict() False

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return the wire-shape dict sent to the frontend (asset_root is omitted).

OwnerKind — enum

Stability: provisional · Since 0.3.1

class OwnerKind(StrEnum)

Where a previewer came from; sets how strongly it wins when routing.

When more than one previewer could handle a target, provenance decides precedence: a project-local previewer beats a package previewer, which beats a built-in core fallback. The string values appear verbatim in the REST and session API payloads.

PREVIEWER_API_VERSION — constant

Stability: unmarked — see the module source / ADR-052

constant — see the module source for the value.

PreviewEnvelope — class

Stability: provisional · Since 0.3.1

class PreviewEnvelope
PreviewEnvelope(previewer_id: 'str', target: 'PreviewTarget', kind: 'EnvelopeKind', payload: 'dict[str, Any]' = <factory>, session_id: 'str | None' = None, resources: 'tuple[PreviewResource, ...]' = (), metadata: 'PreviewMetadata' = <factory>, diagnostics: 'tuple[str, ...]' = (), error: 'PreviewErrorInfo | None' = None, frontend_manifest: 'FrontendManifest | None' = None) -> None

The backend's complete response describing one preview.

A provider returns an envelope; the session layer and REST API serialize it to the frontend. It carries the bounded payload, the metadata flags, any follow-up resources, non-fatal diagnostics, and — when the preview failed — a typed error. Build it with the previewer id, the target, an EnvelopeKind, and a JSON-safe payload.

Example: >>> env = PreviewEnvelope( ... previewer_id="core.text.basic", ... target=PreviewTarget(kind=TargetKind.DATA_REF, ref="r1"), ... kind=EnvelopeKind.TEXT, ... payload={"content": "hello"}, ... ) >>> env.kind.value 'text'

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the whole envelope for the API/wire.
• with_session(self, session_id: 'str | None') -> 'PreviewEnvelope' — unmarked — see the module source / ADR-052 — Return a copy bound to session_id.

PreviewError — exception

Stability: provisional · Since 0.3.1

class PreviewError(Exception)
PreviewError(message: 'str', *, detail: 'dict[str, Any] | None' = None) -> 'None'

Base class for typed preview errors — catch this in a provider.

Each subclass carries a PreviewErrorCode so the session/API layer can render a deterministic error envelope instead of an opaque 500. Catch PreviewError to handle any preview-layer failure uniformly.

Args: message: Human-readable description of the failure. detail: Optional structured context attached to the error envelope.

Members

• to_error_info(self) -> 'PreviewErrorInfo' — unmarked — see the module source / ADR-052 — Convert this error into a PreviewErrorInfo for an envelope.

PreviewErrorCode — enum

Stability: provisional · Since 0.3.1

class PreviewErrorCode(StrEnum)

Stable, machine-readable codes describing why a preview failed.

A failed envelope carries one of these on its error field so the frontend can react consistently instead of parsing a free-text message.

PreviewErrorInfo — class

Stability: provisional · Since 0.3.1

class PreviewErrorInfo
PreviewErrorInfo(code: 'PreviewErrorCode', message: 'str', detail: 'dict[str, Any]' = <factory>) -> None

The typed error payload embedded in a failed envelope.

When a preview fails, the envelope's kind is error and this object explains why: a stable PreviewErrorCode, a human message, and optional structured detail.

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the error payload.

PreviewLimits — class

Stability: provisional · Since 0.3.1

class PreviewLimits
PreviewLimits(max_rows: 'int' = 200, max_bytes: 'int' = 8388608, max_items: 'int' = 100, max_tile: 'int' = 256, max_dim: 'int' = 256) -> None

The bounded-read budgets applied to a preview session.

These mirror the limits the bounded reader enforces, and they are surfaced on the session so the UI can be honest about bounds — e.g. show "showing 200 of N rows". Read them from request.limits inside a provider.

Example: >>> limits = PreviewLimits() >>> limits.max_rows 200

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the budgets.

PreviewMetadata — class

Stability: provisional · Since 0.3.1

class PreviewMetadata
PreviewMetadata(sampled: 'bool' = False, truncated: 'bool' = False, cached: 'bool' = False, derived: 'bool' = False, complete: 'bool' = True, failed: 'bool' = False, extra: 'dict[str, Any]' = <factory>) -> None

Display and state flags carried by every preview envelope.

These six booleans tell the frontend exactly how trustworthy and complete the shown data is — for example whether it was sampled or truncated to stay within budget. Every envelope sets them so the UI can be honest about what the user is looking at. extra carries previewer-owned shape/type details.

Example: >>> meta = PreviewMetadata(truncated=True, extra={"shape": [1000, 3]}) >>> meta.to_dict()["truncated"] True

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return the flags plus extra flattened into one JSON-safe dict.

PreviewProvider — type-alias

Stability: unmarked — see the module source / ADR-052

type-alias — see the module source for the value.

PreviewRequest — class

Stability: provisional · Since 0.3.1

class PreviewRequest
PreviewRequest(target: 'PreviewTarget', spec: 'PreviewerSpec', query: 'dict[str, Any]', data_access: 'PreviewDataAccess', limits: 'PreviewLimits', session_id: 'str | None' = None, storage: 'StorageReference | None' = None, record_metadata: 'dict[str, Any]' = <factory>) -> None

Everything a provider receives when it is asked to render a preview.

The session manager builds this and passes it to your provider callable. Read the target, query, and budgets; do all reads through data_access using the supplied storage reference; and return a PreviewEnvelope.

Example: >>> def render(request: PreviewRequest) -> PreviewEnvelope: ... page = request.data_access.dataframe_page(request.storage) ... return PreviewEnvelope( ... previewer_id=request.spec.previewer_id, ... target=request.target, ... kind=EnvelopeKind.DATAFRAME, ... payload={"rows": page.rows}, ... )

PreviewResource — class

Stability: provisional · Since 0.3.1

class PreviewResource
PreviewResource(resource_id: 'str', kind: 'str', media_type: 'str | None' = None, description: 'str' = '', params: 'dict[str, Any]' = <factory>) -> None

Describes a bounded follow-up read a preview offers (a session resource).

An envelope can advertise extra reads the frontend may request on demand — an array tile, an image plane, a document page, or a child preview — without sending all of that data up front. Each one is described by a resource and fetched on demand through the session's resources route.

Example: >>> res = PreviewResource(resource_id="tile", kind="tile", ... params={"y0": 0, "x0": 0}) >>> res.kind 'tile'

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the resource descriptor.

PreviewResourceProvider — type-alias

Stability: unmarked — see the module source / ADR-052

type-alias — see the module source for the value.

PreviewSource — class

Stability: provisional · Since 0.3.1

class PreviewSource
PreviewSource(workflow_id: 'str | None' = None, node_id: 'str | None' = None, output_port: 'str | None' = None) -> None

Optional workflow/node/output identity shown alongside a preview.

This is display metadata only — it lets the preview panel label a preview as "node X, output port Y" without making the previewer part of the workflow. It carries no runtime truth and never drives data reads.

Example: >>> source = PreviewSource(workflow_id="wf1", node_id="n3", output_port="out") >>> source.to_dict()["node_id"] 'n3'

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of all three identity fields.

PreviewTarget — class

Stability: provisional · Since 0.3.1

class PreviewTarget
PreviewTarget(kind: 'TargetKind', ref: 'str', recorded_type: 'str' = '', type_chain: 'tuple[str, ...]' = (), collection_item_type: 'str | None' = None, source: 'PreviewSource | None' = None) -> None

Identifies the thing a previewer is asked to render.

A target names what to preview (a data object, a collection, an artifact, or a plot) and records its type information so the router can pick the best previewer. You build a target to ask the preview system for a preview, and a provider receives the normalized target on its request.

Example: >>> target = PreviewTarget( ... kind=TargetKind.DATA_REF, ... ref="catalog://run1/image0", ... recorded_type="Image", ... type_chain=("DataObject", "Array", "Image"), ... ) >>> target.is_collection False

Members

• is_collection(self) -> 'bool' — unmarked — see the module source / ADR-052 — Whether this target points at a collection (kind is collection_ref).
• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the target for the API/wire payload.

PreviewerEntryPoint — protocol

Stability: provisional · Since 0.3.1

class PreviewerEntryPoint(Protocol)
PreviewerEntryPoint(*args, **kwargs)

The callable a package wires to the scistudio.previewers entry point.

A package advertises its previewers by pointing a scistudio.previewers entry point at a zero-argument callable that returns a list of PreviewerSpec. Each returned spec declares owner_kind=OwnerKind.PACKAGE and a resolvable backend_provider (a callable or a module:callable import path).

Example: In pyproject.toml::

    [project.entry-points."scistudio.previewers"]
    imaging = "scistudio_blocks_imaging.previewers:get_previewers"

where ``get_previewers() -> list[PreviewerSpec]``. An installed
block/type package may instead re-export a module-level
``get_previewers()`` that the registry discovers as a companion factory,
in the same spirit as ``get_blocks`` / ``get_types``.

PreviewerSpec — class

Stability: provisional · Since 0.3.1

class PreviewerSpec
PreviewerSpec(previewer_id: 'str', owner_kind: 'OwnerKind', owner_name: 'str', target_type: 'str', supports_collection: 'bool' = False, priority: 'int' = 0, capabilities: 'tuple[str, ...]' = (), backend_provider: 'PreviewProvider | str | None' = None, resource_provider: 'PreviewResourceProvider | str | None' = None, frontend_manifest: 'FrontendManifest | None' = None, api_version: 'str' = '1') -> None

Declares one preview provider and how the router should choose it.

A package's entry-point callable returns a list of these. Each spec says which target type the previewer handles, how strongly it should win, what features it offers, and which backend callable renders the envelope. You construct specs to register a previewer; the router and session manager read them.

Example: >>> spec = PreviewerSpec( ... previewer_id="acme.image.viewer", ... owner_kind=OwnerKind.PACKAGE, ... owner_name="acme", ... target_type="Image", ... capabilities=("slice", "lut"), ... backend_provider="acme.previewers:render_image", ... ) >>> spec.target_type 'Image'

Members

• to_dict(self) -> 'dict[str, Any]' — unmarked — see the module source / ADR-052 — Return a JSON-safe dict of the spec (providers shown by name).

PreviewerSpecList — type-alias

Stability: unmarked — see the module source / ADR-052

type-alias — see the module source for the value.

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

ProviderError — exception

Stability: provisional · Since 0.3.1

class ProviderError(PreviewError)

Raise this from a provider for a hard failure it cannot recover from.

Use it when a provider genuinely cannot produce a payload and cannot turn the situation into a typed error envelope itself; the session layer catches it and renders a provider_exception error envelope.

TargetKind — enum

Stability: provisional · Since 0.3.1

class TargetKind(StrEnum)

The kind of thing a PreviewTarget points at.