On this page

Preview

Component examples, layouts, and metadata for command-owned preview pages. Experimental, so these names and the citry ext run preview commands may change in a minor release.

`PreviewExtension` class

Bases: Extension

Declare component previews and expose them only through CLI-owned servers.

Install with Citry(extensions=[PreviewExtension]). Components configure examples through a nested Preview class. Ordinary application adapters receive no routes from this extension.

Experimental
The preview extension, everything citry.ext.preview exports, and the citry ext run preview commands are experimental. They may change in a minor release without a deprecation period.

`name` attribute

`class_name` attribute

`Config` attribute

`render_cache_mode` attribute

`render_cache_version` attribute

`on_extension_created` function

on_extension_created(_ctx: OnExtensionCreatedContext) -> None

`validate_config_fields` function

validate_config_fields(fields: Mapping[str, Any], component: type[Component] | None = None) -> None

`on_component_class_created` function

on_component_class_created(ctx: OnComponentClassCreatedContext) -> None

`file_path` function

file_path(component: type[Component] | None, field: str, path: str | Path) -> Path

Resolve a file beside its declaration, retaining inherited provenance.

`previews` function

previews(selection: Selection | None = None) -> tuple[_Preview, ...]

Resolve an ordered selection with fresh variant inputs on each call.

`variant` function

variant(slug: str, label: str, description: str = '', params: Mapping[str, Any] | None = None, viewport: Viewport | None = None) -> Variant

Declare one preview variant with metadata and component or template params.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`Variant` class

One named example with display metadata and ordinary Python inputs.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

Parameters

slug str - Stable lowercase name, using letters, digits, and single hyphens.
label str - Human-readable example label.
description str - Plain-text explanation of the example.
params Mapping[str, Any] - Inputs for the component or variables for its preview template.
viewport Viewport | None - Optional browser dimensions overriding component defaults.

`slug` attribute

slug: str

`label` attribute

label: str

`description` attribute

description: str

`params` attribute

params: Mapping[str, Any]

`viewport` attribute

viewport: Viewport | None

`Viewport` class

Browser dimensions and pixel scale used to capture one variant.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

Parameters

width int - CSS width from 1 through 8192 pixels.
height int - CSS height from 1 through 8192 pixels.
device_scale_factor float - Finite pixel scale greater than zero, at most four.

`width` attribute

width: int

`height` attribute

height: int

`device_scale_factor` attribute

device_scale_factor: float

`Layout` class

Wrap preview content with one template or component class.

Exactly one source is required. The layout receives preview and a named content slot. Component classes must belong to the rendering app.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

Parameters

template str | None - Trusted inline Citry template source.
template_file str | Path | None - UTF-8 template path relative to the declaring class.
component type[Component] | None - Component class accepting preview metadata and content.

`template` attribute

template: str | None

`template_file` attribute

template_file: str | Path | None

`component` attribute

component: type[Component] | None

`PreviewError` class

Bases: ValueError

A preview declaration, selection, or rendering request is invalid.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`PreviewComponent` class

Display metadata for one component, without its live class or inputs.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`id` attribute

id: str

`name` attribute

name: str

`group` attribute

group: str | None

`PreviewVariant` class

Display metadata for one variant, without its Python params.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`slug` attribute

slug: str

`label` attribute

label: str

`description` attribute

description: str

`viewport` attribute

viewport: Viewport

`url` attribute

url: str

`PreviewMetadata` class

Component and variant metadata supplied to an example or variant layout.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`component` attribute

component: PreviewComponent

`variant` attribute

variant: PreviewVariant

`PreviewItem` class

Variant metadata paired with lazily rendered content for a page layout.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`variant` attribute

variant: PreviewVariant

`content` attribute

content: Slot

`PreviewGroup` class

One component's metadata and ordered preview items.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`component` attribute

component: PreviewComponent

`items` attribute

items: tuple[PreviewItem, ...]

`PreviewPage` class

Ordered component groups supplied to a single-preview or gallery layout.

Experimental
Part of the experimental citry.ext.preview extension, which may change in a minor release without a deprecation period. See PreviewExtension.

`selection` attribute

selection: Literal['variant', 'component', 'all']

`components` attribute

components: tuple[PreviewGroup, ...]