scistudio.panels

Canonical import root: from scistudio.panels import ...

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

OwnerKind — enum

Stability: provisional · Since 0.3.5

class OwnerKind(StrEnum)

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

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

PANEL_API_VERSION — constant

Stability: unmarked — no runtime stability marker

constant — see the module source for the value.

PanelDescriptor — class

Stability: provisional · Since 0.3.5

class PanelDescriptor
PanelDescriptor(id: 'str', api_version: 'str', contexts: 'tuple[str, ...]', types: 'tuple[str, ...]', root: 'Path', owner_kind: 'OwnerKind', owner_name: 'str', priority: 'int' = 0, name: 'str' = '', description: 'str' = '', version: 'str' = '', entry: 'str' = 'index.html', has_python: 'bool' = False) -> None

A validated panel.json descriptor and the folder it came from.

id, api_version, contexts, types, priority, name, description, version, and entry are the descriptor's fields after validation. root is the resolved panel folder, owner_kind and owner_name record the tier and owner it was discovered under, and has_python is true when a panel.py sits beside the descriptor. The local root path never leaves the backend.

Members

  • to_dict(self) -> 'dict[str, Any]' — unmarked — no runtime stability marker — Return the public catalog descriptor without local paths.

PanelRegistry — class

Stability: provisional · Since 0.3.5

class PanelRegistry
PanelRegistry() -> 'None'

The panels one discovery pass found, keyed by panel id.

panels maps each id to the winning PanelDescriptor; when two tiers ship the same id, the project wins over the user library, the user library over a package, and a package over core. shadowed lists the descriptors that lost, and diagnostics holds one message per refused folder, shadowed panel, or failed entry point. A registry holds descriptors only: what a panel may do is decided by the context it opens in, never by its descriptor.

Members

  • get(self, panel_id: 'str') -> 'PanelDescriptor | None' — unmarked — no runtime stability marker — Return the winning descriptor for panel_id, or None.

discover_panels — function

Stability: provisional · Since 0.3.5

discover_panels(project_dir: 'Path | None' = None, *, registered_types: 'Collection[str] | None' = None) -> 'PanelRegistry'

Discover every panel the application would see and return the registry.

Scans the project's panel folder when project_dir is given, the user library, every package's scistudio.panels entry point, and the built-in panels. A package entry point is a callable returning a list of panel folder paths. registered_types defaults to the types registered for the project. A failure in one folder or entry point becomes a diagnostic on the returned PanelRegistry and never stops discovery.

parse_descriptor — function

Stability: provisional · Since 0.3.5

parse_descriptor(directory: 'Path', *, owner_kind: 'OwnerKind', owner_name: 'str', registered_types: 'Collection[str]') -> 'tuple[PanelDescriptor, list[str]]'

Validate the panel folder directory and return its descriptor.

registered_types is the set of data type names the panel may claim; a claim outside it is refused. Returns the PanelDescriptor and a list of non-fatal notes, such as unknown keys that were ignored. Raises ValueError with a diagnostic when the descriptor is invalid: the id does not equal the folder name, the api_version major is not served, the contexts or types are malformed, or entry does not name an HTML file inside the folder.

validate_external_references — function

Stability: provisional · Since 0.3.5

validate_external_references(root: 'Path') -> 'list[str]'

Check the external references in a panel folder's HTML, CSS, and scripts.

Every URL must be https on an allowlisted CDN host (cdn.jsdelivr.net, cdnjs.cloudflare.com, unpkg.com). Returns a note for each CDN reference without a pinned x.y.z version. Raises ValueError for a reference outside the allowlist, a symlink that escapes the folder, or a source file over the 16 MiB validation budget.

validate_interactive_panel — function

Stability: provisional · Since 0.3.5

validate_interactive_panel(manifest: 'object', registry: 'PanelRegistry | None' = None) -> 'None'

Check that an interactive block's panel declaration can open.

manifest is the block's panel declaration (its panel_id). The panel must resolve, in registry or in a fresh discovery, to a panel whose contexts include interactive; otherwise ValueError is raised.