Storage & Schema¶

Schema-driven per-device configuration rendered as UI forms by the host. DeviceStorage plus the JsonSchema* shapes.

camera_ui_sdk.storage ¶

PluginConfig `module-attribute` ¶

PluginConfig = dict[str, Any]

Plugin configuration type.

OnSetCallback `module-attribute` ¶

OnSetCallback = Callable[[Any, Any], None | Any] | Callable[[Any, Any], Awaitable[None | Any]] | Callable[[Any, Any], Coroutine[Any, Any, None | Any]]

Callback type for onSet handlers.

OnGetCallback `module-attribute` ¶

OnGetCallback = Callable[[], None | Any] | Callable[[], Awaitable[None | Any]] | Callable[[], Coroutine[Any, Any, None | Any]]

Callback type for onGet handlers.

JsonSchemaType `module-attribute` ¶

JsonSchemaType = Literal['string', 'number', 'boolean', 'array', 'object', 'button', 'submit']

Available schema field types for configuration UI.

StringFormat `module-attribute` ¶

StringFormat = Literal['date-time', 'date', 'time', 'email', 'uuid', 'ipv4', 'ipv6', 'password', 'textarea', 'qrCode', 'image']

String format types for validation/display.

Used on string-typed schemas to render a specialized UI control:

date-time: ISO 8601 date+time picker.
date: date-only picker.
time: time-only picker.
email: email input with format validation.
uuid: UUID input with format validation.
ipv4: IPv4 address input.
ipv6: IPv6 address input.
password: masked input that hides characters.
textarea: multi-line text area for longer free text.
qrCode: value is rendered as a QR code (read-only display).
image: value is a data URL or path; rendered as a thumbnail.

ButtonColor `module-attribute` ¶

ButtonColor = Literal['success', 'info', 'warn', 'danger']

Button color variants.

SchemaConditionOperator `module-attribute` ¶

SchemaConditionOperator = Literal['eq', 'neq', 'gt', 'lt', 'in', 'nin']

Comparison operators for conditional field visibility.

T `module-attribute` ¶

T = TypeVar('T', str, int, float, bool, list[str], list[int], list[float], list[bool], str | list[str])

Generic type variable for schema default values.

V1 `module-attribute` ¶

V1 = ExtTypeVar('V1', default=str)

TypeVar for generic getValue return type.

V2 `module-attribute` ¶

V2 = ExtTypeVar('V2', bound=Mapping[str, Any], default=dict[str, Any])

TypeVar for generic storage values type. Compatible with TypedDict.

JsonSchema `module-attribute` ¶

JsonSchema = JsonSchemaString | JsonSchemaNumber | JsonSchemaBoolean | JsonSchemaEnum | JsonSchemaArray | JsonSchemaObject | JsonSchemaButton | JsonSchemaSubmit

Union of every top-level schema type (with callbacks).

Use this when defining the schemas you pass to defineSchemas, addSchema, or changeSchema. Each entry describes one configurable field rendered in the UI; the discriminator is the type property.

JsonSchemaWithoutKey `module-attribute` ¶

JsonSchemaWithoutKey = JsonSchemaString | JsonSchemaNumber | JsonSchemaBoolean | JsonSchemaEnum | JsonSchemaArray | JsonSchemaObject | JsonSchemaButton | JsonSchemaSubmit

Schema accepted where the key is supplied externally, e.g. as a dict property.

JsonSchemaWithoutCallbacks `module-attribute` ¶

JsonSchemaWithoutCallbacks = JsonSchemaStringWithoutCallbacks | JsonSchemaNumberWithoutCallbacks | JsonSchemaBooleanWithoutCallbacks | JsonSchemaEnumWithoutCallbacks | JsonSchemaArrayWithoutCallbacks | JsonSchemaObjectWithoutCallbacks

Union type of schemas without callbacks. Use this for nested schemas (e.g., array items).

SchemaCondition ¶

Bases: TypedDict

Condition that controls when a field is visible. The field is shown only when the condition evaluates to true against the current form values.

Combine multiple conditions on a field via a list: all must pass (logical AND).

Example

Show apiKey only when authMode equals token::

{
    "key": "apiKey",
    "type": "string",
    "title": "API Key",
    "description": "",
    "condition": {"key": "authMode", "value": "token"},
}

Show port only when protocol is one of the listed values::

{"key": "protocol", "operator": "in", "value": ["http", "https"]}

key `instance-attribute` ¶

key: Required[str]

Key of another field whose value drives visibility.

value `instance-attribute` ¶

value: Required[Any]

Expected value: a single value, or a list for in / nin.

operator `instance-attribute` ¶

operator: SchemaConditionOperator

Comparison operator (default: eq).

JsonFactorySchema ¶

Bases: TypedDict

Base schema interface for all schema types. Contains common fields like type, key, title, description.

type `instance-attribute` ¶

type: JsonSchemaType

Field type.

key `instance-attribute` ¶

key: str

Unique field identifier.

title `instance-attribute` ¶

title: str

Display title.

description `instance-attribute` ¶

description: str

Field description/help text.

JsonBaseSchemaWithoutCallbacks ¶

Bases: JsonFactorySchema, Generic[T]

Base schema without callbacks, used for nested schemas. Extends factory schema with common display options.

group `instance-attribute` ¶

group: str

Optional group name for organizing fields.

hidden `instance-attribute` ¶

hidden: bool

Hide field from UI.

required `instance-attribute` ¶

required: bool

Mark field as required.

readonly `instance-attribute` ¶

readonly: bool

Make field read-only.

placeholder `instance-attribute` ¶

placeholder: str

Placeholder text for empty fields.

defaultValue `instance-attribute` ¶

defaultValue: T

Default value when not set.

condition `instance-attribute` ¶

condition: SchemaCondition | list[SchemaCondition]

Condition for conditional field visibility. List = all must be true (AND).

JsonBaseSchema ¶

Bases: JsonBaseSchemaWithoutCallbacks[T], Generic[T]

Base schema with callbacks, the full schema interface. Adds storage and callback options for dynamic behavior.

store `instance-attribute` ¶

store: bool

Whether to persist this field to storage.

onSet `instance-attribute` ¶

onSet: OnSetCallback

Called after setValue writes the key, changed or not. setConfig calls it only for keys that changed. Receives (new_value, old_value).

onGet `instance-attribute` ¶

onGet: OnGetCallback

Callback to get computed value.

JsonStringSchema ¶

Bases: TypedDict

String-specific schema options.

type `instance-attribute` ¶

type: Literal['string']

Schema type discriminator.

format `instance-attribute` ¶

format: StringFormat

String format for validation/display. See StringFormat for behavior per format.

minLength `instance-attribute` ¶

minLength: int

Minimum string length (inclusive).

maxLength `instance-attribute` ¶

maxLength: int

Maximum string length (inclusive).

JsonNumberSchema ¶

Bases: TypedDict

Number-specific schema options.

type `instance-attribute` ¶

type: Literal['number']

Schema type discriminator.

minimum `instance-attribute` ¶

minimum: int | float

Minimum value.

maximum `instance-attribute` ¶

maximum: int | float

Maximum value.

step `instance-attribute` ¶

step: int | float

Step increment for number input.

JsonBooleanSchema ¶

Bases: TypedDict

Boolean-specific schema options.

type `instance-attribute` ¶

type: Literal['boolean']

Schema type discriminator.

JsonEnumSchema ¶

Bases: TypedDict

Enum/select schema options.

type `instance-attribute` ¶

type: Literal['string']

Schema type discriminator.

enum `instance-attribute` ¶

enum: list[str]

Available options.

enumLabels `instance-attribute` ¶

enumLabels: dict[str, str]

Display labels per enum value; values without a label show the raw value.

multiple `instance-attribute` ¶

multiple: bool

Allow multiple selection.

minItems `instance-attribute` ¶

minItems: int

Minimum number of selected values (multiple only).

JsonArraySchema ¶

Bases: TypedDict

Array schema options.

type `instance-attribute` ¶

type: Literal['array']

Schema type discriminator.

opened `instance-attribute` ¶

opened: bool

Whether array items are expanded by default.

minItems `instance-attribute` ¶

minItems: int

Minimum number of entries.

items `instance-attribute` ¶

items: JsonSchemaWithoutCallbacks

Schema for array items.

JsonObjectSchema ¶

Bases: TypedDict

Object schema options.

The value is a plain dict; each property is its own keyed sub-field. As array items this yields structured lists, e.g. [{"name", "cameras"}].

type `instance-attribute` ¶

type: Literal['object']

Schema type discriminator.

properties `instance-attribute` ¶

properties: list[JsonSchemaWithoutCallbacks]

Sub-fields of the object value.

JsonSchemaString ¶

Bases: JsonBaseSchema[str]

Complete string schema with callbacks.

format `instance-attribute` ¶

format: StringFormat

String format for validation/display. See StringFormat for behavior per format.

minLength `instance-attribute` ¶

minLength: int

Minimum string length (inclusive).

maxLength `instance-attribute` ¶

maxLength: int

Maximum string length (inclusive).

JsonSchemaStringWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[str]

String schema without callbacks (for nested use).

JsonSchemaNumber ¶

Bases: JsonBaseSchema[int | float]

Complete number schema with callbacks.

JsonSchemaNumberWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[int | float]

Number schema without callbacks (for nested use).

JsonSchemaBoolean ¶

Bases: JsonBaseSchema[bool]

Complete boolean schema with callbacks.

JsonSchemaBooleanWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[bool]

Boolean schema without callbacks (for nested use).

JsonSchemaEnum ¶

Bases: JsonBaseSchema[str | list[str]]

Complete enum schema with callbacks.

JsonSchemaEnumWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[str | list[str]]

Enum schema without callbacks (for nested use).

JsonSchemaArray ¶

Bases: JsonBaseSchema[list[str] | list[int] | list[float] | list[bool]]

Complete array schema with callbacks.

JsonSchemaArrayWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[list[str] | list[int] | list[float] | list[bool]]

Array schema without callbacks (for nested use).

JsonSchemaObject ¶

Bases: JsonBaseSchema[dict[str, Any]]

Complete object schema with callbacks.

JsonSchemaObjectWithoutCallbacks ¶

Bases: JsonBaseSchemaWithoutCallbacks[dict[str, Any]]

Object schema without callbacks (for nested use).

JsonSchemaButton ¶

Bases: TypedDict

Button schema: triggers an action without storing a value.

type `instance-attribute` ¶

type: Required[Literal['button']]

Schema type discriminator.

key `instance-attribute` ¶

key: Required[str]

Unique field identifier.

title `instance-attribute` ¶

title: Required[str]

Display title.

description `instance-attribute` ¶

description: Required[str]

Field description/help text.

onSet `instance-attribute` ¶

onSet: Callable[[], Awaitable[None]] | Callable[[], None]

Click handler.

group `instance-attribute` ¶

group: str

Optional group name for organizing fields.

color `instance-attribute` ¶

color: ButtonColor

Button color variant.

JsonSchemaSubmit ¶

Bases: TypedDict

Submit button schema: submits form data and can return an updated schema.

type `instance-attribute` ¶

type: Required[Literal['submit']]

Schema type discriminator.

key `instance-attribute` ¶

key: Required[str]

Unique field identifier.

title `instance-attribute` ¶

title: Required[str]

Display title.

description `instance-attribute` ¶

description: Required[str]

Field description/help text.

onClick `instance-attribute` ¶

onClick: Required[Callable[[Any], Awaitable[FormSubmitResponse | None]]]

Submit handler; receives form values, can return toast/schema updates.

group `instance-attribute` ¶

group: str

Optional group name for organizing fields.

color `instance-attribute` ¶

color: ButtonColor

Button color variant.

ToastMessage ¶

Bases: TypedDict

Toast notification message.

Returned from a submit handler (JsonSchemaSubmit.onClick) inside a FormSubmitResponse to surface a transient banner in the UI, for example to confirm that a credential check succeeded or failed.

type `instance-attribute` ¶

type: Literal['info', 'success', 'warning', 'error']

Severity, controls the icon and color of the banner.

message `instance-attribute` ¶

message: str

Human-readable message text.

FormSubmitSchema ¶

Bases: TypedDict

Form submit input data.

config `instance-attribute` ¶

config: dict[str, Any]

Form configuration values.

FormSubmitResponse ¶

Bases: TypedDict

Form submit response, returned by JsonSchemaSubmit.onClick.

Used to react to a user-triggered submit (e.g. "Test connection", "Pair device") with optional UI feedback. Either field may be set:

toast shows a transient banner.
schema replaces the current form schema, useful for multi-step flows where the next step depends on the submitted values.

toast `instance-attribute` ¶

toast: ToastMessage

Optional toast banner to display after the submit completes.

schema `instance-attribute` ¶

schema: list[JsonSchemaWithoutCallbacks]

Optional updated schema definitions (full replacement of fields).

SchemaConfig ¶

Bases: TypedDict

Schema configuration bundle. Contains both schema definitions and current values.

schema `instance-attribute` ¶

schema: list[JsonSchema]

Schema definitions.

config `instance-attribute` ¶

config: dict[str, Any]

Current configuration values.

DeviceStorage ¶

Bases: Protocol, Generic[V2]

Device storage interface for plugin/camera configuration.

Provides methods to read/write configuration values and manage schemas. Each plugin and camera can have its own storage instance.

Example

# Get a value with default
threshold = await storage.getValue("motionThreshold", 50)

# Set a value
await storage.setValue("motionThreshold", 75)

# Add a new schema field
await storage.addSchema(
    {
        "type": "number",
        "key": "sensitivity",
        "title": "Sensitivity",
        "description": "Detection sensitivity (0-100)",
        "minimum": 0,
        "maximum": 100,
        "defaultValue": 50,
    }
)

schemas `instance-attribute` ¶

schemas: list[JsonSchema]

Current schema definitions.

values `instance-attribute` ¶

values: V2

Current configuration values.

getValue `async` ¶

getValue(key: str) -> V1 | None

getValue(key: str, default_value: V1) -> V1

getValue(key: str, default_value: V1 | None = None) -> V1 | None

Get a configuration value.

If the schema declares an onGet callback, its result is returned as-is, with no fallback. Otherwise resolves in order: the stored value, then the schema default, then the provided default.

Parameters:

Name	Type	Description	Default
`key`	`str`	Configuration key	required
`default_value`	`V1 \| None`	Default value if key doesn't exist	`None`

Returns:

Type	Description
`V1 \| None`	The configuration value or default

setValue `async` ¶

setValue(key: str, new_value: Any) -> None

Set a configuration value.

Takes effect only if a schema exists for the key. Passing None deletes the key: it reads as never-set again and the schema default applies. For a field whose schema opts into storage (store: True) the value is durably persisted before the coroutine completes; the schema's onSet fires afterwards.

Parameters:

Name	Type	Description	Default
`key`	`str`	Configuration key	required
`new_value`	`Any`	New value to set, or `None` to delete the key	required

submitValue `async` ¶

submitValue(key: str, new_value: Any) -> FormSubmitResponse | None

Submit a value (for submit-type schemas).

Parameters:

Name	Type	Description	Default
`key`	`str`	Schema key	required
`new_value`	`Any`	Submitted value	required

Returns:

Type	Description
`FormSubmitResponse \| None`	Optional response with toast/schema updates

hasValue ¶

hasValue(key: str) -> bool

Check if a configuration value exists.

Parameters:

Name	Type	Description	Default
`key`	`str`	Configuration key	required

getConfig `async` ¶

getConfig() -> SchemaConfig

Get the full schema configuration.

Returns:

Type	Description
`SchemaConfig`	Schema definitions and current values

setConfig `async` ¶

setConfig(new_config: V2) -> None

Merge configuration values into the current config.

Only keys present in new_config are updated (not a full replace); arrays are replaced, not merged. Values are durably persisted before the coroutine completes; onSet fires for each key whose value changed.

Parameters:

Name	Type	Description	Default
`new_config`	`V2`	Configuration values to merge in	required

defineSchemas ¶

defineSchemas(schemas: list[JsonSchema]) -> None

Define all schemas for this storage.

Parameters:

Name	Type	Description	Default
`schemas`	`list[JsonSchema]`	Array of schema definitions	required

addSchema `async` ¶

addSchema(schema: JsonSchema) -> None

Add a new schema field.

Parameters:

Name	Type	Description	Default
`schema`	`JsonSchema`	Schema definition to add	required

removeSchema `async` ¶

removeSchema(key: str) -> None

Remove a schema field.

The field's stored value is deleted along with the schema; the removal is durably persisted when the coroutine completes.

Parameters:

Name	Type	Description	Default
`key`	`str`	Schema key to remove	required

changeSchema `async` ¶

changeSchema(key: str, new_schema: dict[str, Any]) -> None

Replace an existing schema field with a full schema.

The whole schema is replaced, individual fields are not merged. It is a no-op when no schema with that key is registered (use addSchema to add a new field). The passed key always wins.

Parameters:

Name	Type	Description	Default
`key`	`str`	Schema key to replace	required
`new_schema`	`dict[str, Any]`	Full schema definition that replaces the current one	required

getSchema ¶

getSchema(key: str) -> JsonSchema | None

Get a schema definition by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	Schema key	required

Returns:

Type	Description
`JsonSchema \| None`	Schema or None

hasSchema ¶

hasSchema(key: str) -> bool

Check if a schema exists.

Parameters:

Name	Type	Description	Default
`key`	`str`	Schema key	required

setInternalValue `async` ¶

setInternalValue(key: str, value: Any) -> None

Set a system-internal value (e.g. _displayName) without requiring a schema and persist it.

When the coroutine completes, the value is durably persisted. Passing None deletes the key; it reads as never-set again.

Parameters:

Name	Type	Description	Default
`key`	`str`	Internal key (typically prefixed with '_')	required
`value`	`Any`	Value to set, or `None` to delete the key	required

save `async` ¶

save() -> None

Persist all changes to storage.

When the coroutine completes, all values are durably persisted.

Storage & Schema¶

camera_ui_sdk.storage ¶

PluginConfig module-attribute ¶

OnSetCallback module-attribute ¶

OnGetCallback module-attribute ¶

JsonSchemaType module-attribute ¶

StringFormat module-attribute ¶

ButtonColor module-attribute ¶

SchemaConditionOperator module-attribute ¶

T module-attribute ¶

V1 module-attribute ¶

V2 module-attribute ¶

JsonSchema module-attribute ¶

JsonSchemaWithoutKey module-attribute ¶

JsonSchemaWithoutCallbacks module-attribute ¶

SchemaCondition ¶

key instance-attribute ¶

value instance-attribute ¶

operator instance-attribute ¶

JsonFactorySchema ¶

type instance-attribute ¶

key instance-attribute ¶

title instance-attribute ¶

description instance-attribute ¶

JsonBaseSchemaWithoutCallbacks ¶

group instance-attribute ¶

hidden instance-attribute ¶

required instance-attribute ¶

readonly instance-attribute ¶

placeholder instance-attribute ¶

defaultValue instance-attribute ¶

condition instance-attribute ¶

JsonBaseSchema ¶

store instance-attribute ¶

onSet instance-attribute ¶

onGet instance-attribute ¶

JsonStringSchema ¶

type instance-attribute ¶

format instance-attribute ¶

minLength instance-attribute ¶

maxLength instance-attribute ¶

JsonNumberSchema ¶

type instance-attribute ¶

minimum instance-attribute ¶

maximum instance-attribute ¶

step instance-attribute ¶

JsonBooleanSchema ¶

type instance-attribute ¶

JsonEnumSchema ¶

type instance-attribute ¶

enum instance-attribute ¶

enumLabels instance-attribute ¶

multiple instance-attribute ¶

minItems instance-attribute ¶

JsonArraySchema ¶

type instance-attribute ¶

opened instance-attribute ¶

minItems instance-attribute ¶

items instance-attribute ¶

JsonObjectSchema ¶

type instance-attribute ¶

properties instance-attribute ¶

JsonSchemaString ¶

format instance-attribute ¶

minLength instance-attribute ¶

maxLength instance-attribute ¶

JsonSchemaStringWithoutCallbacks ¶

JsonSchemaNumber ¶

JsonSchemaNumberWithoutCallbacks ¶

JsonSchemaBoolean ¶

JsonSchemaBooleanWithoutCallbacks ¶

JsonSchemaEnum ¶

JsonSchemaEnumWithoutCallbacks ¶

JsonSchemaArray ¶

JsonSchemaArrayWithoutCallbacks ¶

JsonSchemaObject ¶

JsonSchemaObjectWithoutCallbacks ¶

JsonSchemaButton ¶

type instance-attribute ¶

key instance-attribute ¶

PluginConfig `module-attribute` ¶

OnSetCallback `module-attribute` ¶

OnGetCallback `module-attribute` ¶

JsonSchemaType `module-attribute` ¶

StringFormat `module-attribute` ¶

ButtonColor `module-attribute` ¶

SchemaConditionOperator `module-attribute` ¶

T `module-attribute` ¶

V1 `module-attribute` ¶

V2 `module-attribute` ¶

JsonSchema `module-attribute` ¶

JsonSchemaWithoutKey `module-attribute` ¶

JsonSchemaWithoutCallbacks `module-attribute` ¶

key `instance-attribute` ¶

value `instance-attribute` ¶

operator `instance-attribute` ¶

type `instance-attribute` ¶

key `instance-attribute` ¶

title `instance-attribute` ¶

description `instance-attribute` ¶

group `instance-attribute` ¶

hidden `instance-attribute` ¶

required `instance-attribute` ¶

readonly `instance-attribute` ¶

placeholder `instance-attribute` ¶

defaultValue `instance-attribute` ¶

condition `instance-attribute` ¶

store `instance-attribute` ¶

onSet `instance-attribute` ¶

onGet `instance-attribute` ¶

type `instance-attribute` ¶

format `instance-attribute` ¶

minLength `instance-attribute` ¶

maxLength `instance-attribute` ¶

type `instance-attribute` ¶

minimum `instance-attribute` ¶

maximum `instance-attribute` ¶

step `instance-attribute` ¶

type `instance-attribute` ¶

type `instance-attribute` ¶

enum `instance-attribute` ¶

enumLabels `instance-attribute` ¶

multiple `instance-attribute` ¶

minItems `instance-attribute` ¶

type `instance-attribute` ¶

opened `instance-attribute` ¶

minItems `instance-attribute` ¶

items `instance-attribute` ¶

type `instance-attribute` ¶

properties `instance-attribute` ¶

format `instance-attribute` ¶

minLength `instance-attribute` ¶

maxLength `instance-attribute` ¶

type `instance-attribute` ¶

key `instance-attribute` ¶

title `instance-attribute` ¶

description `instance-attribute` ¶

onSet `instance-attribute` ¶

group `instance-attribute` ¶

color `instance-attribute` ¶

type `instance-attribute` ¶

key `instance-attribute` ¶

title `instance-attribute` ¶

description `instance-attribute` ¶

onClick `instance-attribute` ¶

group `instance-attribute` ¶

color `instance-attribute` ¶

type `instance-attribute` ¶

message `instance-attribute` ¶

config `instance-attribute` ¶

toast `instance-attribute` ¶

schema `instance-attribute` ¶

schema `instance-attribute` ¶

config `instance-attribute` ¶

schemas `instance-attribute` ¶

values `instance-attribute` ¶

getValue `async` ¶

setValue `async` ¶

submitValue `async` ¶

getConfig `async` ¶