scistudio.api.seam

Canonical import root: from scistudio.api.seam import ...

Self-contained public-API reference — 12 symbols from this module's __all__, with signatures and docstrings inlined. Generated; do not hand-edit.

AUDIENCE_EXTERNAL_TAG — constant

Stability: unmarked — no runtime stability marker

constant — see the module source for the value.

Capabilities — class

Stability: provisional · Since 0.3.5

class Capabilities
Capabilities(identity: 'IdentityCapability | None' = None, transfer: 'bool' = False) -> None

The enterprise capabilities the backend declares to the frontend at boot.

Everything is off by default, which is the open-source edition: no declaration reaches the page and the UI is unchanged. identity carries the signed-in user and logout URL; transfer turns on laptop-to-server file transfer. The frontend reads the declaration through its typed accessor (frontend/src/lib/capabilities.ts).

Members

• any_enabled(self) -> 'bool' — unmarked — no runtime stability marker — Whether at least one capability is on.
• to_bootstrap(self) -> 'dict[str, Any]' — unmarked — no runtime stability marker — Return the JSON-ready declaration injected into the served page.

GuardContext — class

Stability: provisional · Since 0.3.5

class GuardContext
GuardContext(root_path: 'str' = '') -> None

What create_app tells a guard about the application it wraps.

root_path is the normalized mount prefix ("" at the root, else "/prefix"), read from the same single normalization point as the rest of the backend. New fields are added here rather than to the factory call, so a guard written today keeps working.

Members

• route_path(self, scope: 'Scope') -> 'str' — unmarked — no runtime stability marker — Return the router's path for scope (the prefix removed).

GuardFactory — protocol

Stability: provisional · Since 0.3.5

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

Build the guard create_app(guard=...) installs.

Called once with the inner ASGI application and a GuardContext; returns the guard, itself an ASGI application wrapping app. A guard class whose constructor takes (app, context) satisfies this protocol directly; a guard that needs settings is passed as a closure or functools.partial.

The guard sees only http and websocket scopes that are not under a self-authenticating prefix; the factory routes everything else (the lifespan scope, registered prefixes) past it. It sits inside the CORS layer, so preflight handling and CORS headers on rejections are unchanged, and inside request logging, so a rejection is logged with its request id.

IdentityCapability — class

Stability: provisional · Since 0.3.5

class IdentityCapability
IdentityCapability(user: 'str', logout_url: 'str') -> None

The identity capability: who is signed in, and where to sign out.

user is the signed-in user's display name. In the enterprise edition's one-user-one-backend deployment it is fixed for the backend's lifetime. logout_url names the backend's own logout endpoint as an absolute path (for example /api/session/logout). That endpoint ends the SciStudio session before any identity-provider logout. The frontend sends it a same-origin POST, resolved under the service prefix, and then follows the location the response returns; a plain GET navigation would let other sites force a logout.

LifespanHook — protocol

Stability: provisional · Since 0.3.5

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

A startup check or background task run inside the application lifespan.

Called with the application at startup, after the core runtime exists (app.state.runtime is set); returns an async context manager. Its entry is the startup work: raising aborts startup, so a misconfiguration fails at spawn rather than at first login. Its exit is the teardown, run in reverse hook order before the core runtime stops, whether the application is shutting down normally or startup failed after this hook was entered. A @contextlib.asynccontextmanager function taking app satisfies this protocol.

is_self_authenticating_path — function

Stability: provisional · Since 0.3.5

is_self_authenticating_path(path: 'str') -> 'bool'

Return whether a route path lies under a registered prefix.

path is the router's path, the mount prefix already removed (see GuardContext.route_path). A prefix matches itself and anything below it on a segment boundary: /api/panels/t matches /api/panels/t/abc/x but not /api/panels/tx.

mcp — constant

Stability: provisional · Since 0.3.5

constant — see the module source for the value.

register_self_authenticating_prefix — function

Stability: provisional · Since 0.3.5

register_self_authenticating_prefix(prefix: 'str') -> 'str'

Register a route-path prefix whose routes authenticate requests themselves.

Every guard, the default loopback guard and any replacement, skips its own check for requests under the prefix and leaves authentication to the owning route; create_app enforces this for whichever guard it installs. Matching runs on the route path after root-path prefix handling, so registering /api/panels/t/ also covers /user/<name>/scistudio/api/panels/t/....

The owning route MUST authenticate every request it serves. Register the narrowest prefix that covers those routes. Returns the normalized prefix (/api/panels/t); registering the same prefix again is a no-op.

Raises ValueError for a prefix outside /api/ or with a non-literal segment.

self_authenticating_prefixes — function

Stability: provisional · Since 0.3.5

self_authenticating_prefixes() -> 'tuple[str, ...]'

Return the registered prefixes, normalized, in registration order.

unregister_self_authenticating_prefix — function

Stability: provisional · Since 0.3.5

unregister_self_authenticating_prefix(prefix: 'str') -> 'None'

Remove a registered prefix; requests under it are guarded again.

Unregistering a prefix that is not registered is a no-op.

workflow_runs_active — function

Stability: provisional · Since 0.3.5

workflow_runs_active(app: 'FastAPI') -> 'bool'

Return whether any workflow run in this backend is still executing.

A Hub activity reporter polls this so idle culling never stops a backend mid-analysis. Returns False before the lifespan has created the runtime and after every run's task has finished.