Astral Primitives

mismatched concrete subclass discriminators raise ValidationError; valid wire round trips remain unchanged.

Composable, serializable UI primitives for Python. Describe UI as plain Python objects, then serialize them to a dict/JSON for storage or for a server-driven UI to render.

Install

pip install -e ".[dev]"   # editable install with test deps

Quick start

from astralprims import Button

button = Button(
    label="the button text",
    action="open",
    css={"background-color": "white", "color": "#000000"},
)

button.to_dict()
# {
#   "type": "button",
#   "css": {"background-color": "white", "color": "#000000"},
#   "label": "the button text",
#   "action": "open",
#   "payload": {},
#   "variant": "primary",
# }

button.to_json()  # -> JSON string

None and empty css are dropped from the output, so payloads stay clean.

Composing layouts

from astralprims import Card, Container, Text, Button

page = Container(css={"display": "flex"}, direction="column").add(
    Text(content="Welcome", variant="h1"),
    Card(title="Sign up").add(
        Text(content="Enter your details below."),
        Button(label="Get started", action="signup"),
    ),
)
page.to_dict()  # children/content serialize recursively

Round-tripping from data

Already have a primitive as a dict (from storage or an API)? Rebuild it — including the full nested tree:

from astralprims import Primitive

spec = {"type": "button", "label": "Buy", "action": "checkout"}
button = Primitive.from_dict(spec)   # -> Button(...)

Child dictionary compatibility in 0.7.0

Every child mapping in Container.children, Card.content, Grids.children, Collapsible.content, TabItem.content and ActionGroup.buttons must carry a registered, non-empty string type. Missing, empty, malformed and unknown discriminators raise a Pydantic ValidationError instead of producing an empty generic primitive. This narrows accepted input and therefore bumps the minor version.

Tagged children retain their concrete type and fields across lists, tuples, deques and generators, including mapping wrappers. Existing primitive instances retain their identity. Valid serialized wire dictionaries, aliases, defaults and trusted attributes precedence remain unchanged; callers using untagged child dictionaries must add the intended concrete type before upgrading.

Finite-number compatibility in 0.9.0

Wire serialization rejects NaN, positive infinity and negative infinity with a field path. The check applies to to_dict(), model_dump(), to_json() and from_dict(), including nested charts, payloads, trusted attributes, numeric mapping keys, models and dataclasses after their serializers expand them. to_json(allow_nan=True) raises ValueError; callers cannot opt into non-standard numeric tokens.

This narrows accepted input and therefore bumps the minor version. Finite numbers, serialized defaults, aliases, omission rules and trusted attributes precedence retain their existing wire representation. Consumers adopting this package must replace non-finite values with an application-defined finite or nullable value before crossing the wire boundary. This policy does not introduce conversions for other Python objects that standard JSON cannot encode.

Shipping a response

from astralprims import create_ui_response, Text, Button

create_ui_response([Text(content="hi"), Button(label="ok", action="go")])
# {"_ui_components": [{...}, {...}], "_data": None}

A FastAPI endpoint can return primitive.to_dict() or create_ui_response(...) directly.

Wire schema

Version 0.8.0 adds the public wire_schema() Python API. It describes the existing serialized vocabulary; it does not add a primitive or change wire output. Consumers adopt the new package release through their own version pins.

wire_schema() returns a JSON Schema (draft 2020-12) describing the canonical to_dict() output of every built-in primitive in this release. Each wire type gets an entry under $defs, and the root schema validates any serialized component directly:

from astralprims import wire_schema

schema = wire_schema()
schema["x-astralprims-version"]  # matches astralprims.__version__
schema["$defs"]["button"]        # the wire shape of Button output

Fields set to None are omitted from wire output entirely, as is an empty css block, so those properties do not accept an explicit top-level null in the schema; nested values permitted by a field's own type, such as entries in unconstrained lists or dictionaries, may still contain null. Non-None defaults of declared wire properties are always emitted and appear as the schema default of their property. attributes is a trusted escape hatch merged last into the top-level object: extra keys are always accepted, but overriding a declared key, including type, may intentionally produce output outside this baseline schema. Validating output against this schema is not sanitization, and never a security boundary, because attributes can carry any trusted keys — only trusted data may enter it. Custom registered primitives stay supported through Primitive.from_dict() but are not part of this versioned baseline.

Built-in primitives

Composite readouts

Six types describe a whole readout rather than a single value, so a server can send the shape it means instead of assembling it from loose parts.

from astralprims import ActionGroup, Button, Gauge, StatGroup

Gauge(label="Humidity", value=0.62, display_value="62%",
      thresholds=[{"at": 0.0, "variant": "success"},
                  {"at": 0.8, "variant": "warning"}])

StatGroup(title="This week", columns=3, items=[
    {"label": "Requests", "value": "1,284", "delta": "+12%", "trend": "up"},
    {"label": "Errors", "value": "3", "trend": "down", "variant": "success"},
    {"label": "p95", "value": "412 ms"},
])

ActionGroup(label="Result actions", align="end", buttons=[
    Button(label="Save", action="save_result"),
    Button(label="Export", action="export_result", variant="secondary"),
])

None of these carry a color. Variant strings name a semantic role and the renderer resolves it from the active theme.

Primitive reference

Every primitive serializes to a dict with its wire type first, then the common fields, then its own fields. Fields left at None and an empty css are dropped; every other default is emitted and is part of the wire contract. The wire type does not always match the class name: CodeBlock is code, ProgressBar is progress, MetricCard is metric, List_ is list, KeyValue is keyvalue, and Grid is an alias of Grids, which is grid. In a type, Primitive means any nested primitive; a nested dict is rebuilt as the class registered for its type.

Common fields

Primitives

Nested models

attributes is never emitted as a key: its entries are merged into the top level last and can overwrite any field, including type, so it must carry only trusted keys, never user or model input.

This reference is generated from the models. After changing a primitive, run uv run --frozen python tooling/python-ci/primitive_reference.py to regenerate it; tests/test_readme_reference.py fails while it is stale.

Defining your own primitive

Primitives are pydantic models; declare the wire type as a Literal default and subclassing auto-registers it for from_dict — no manual map. Pick a type string that does not collide with a built-in:

from typing import Literal, Optional
from astralprims import Primitive, rebuild_primitive_union

class Ribbon(Primitive):
    type: Literal["ribbon"] = "ribbon"   # registered automatically
    label: str = ""
    count: Optional[int] = None

rebuild_primitive_union()  # refresh AnyPrimitive/primitive_adapter

Collision errors and validation

Every primitive subclass must declare a type field with a non-empty string default that matches any Literal annotation choices. Wire types must be globally unique across built-in and custom primitives. Attempting to register a wire type that is already bound to another class raises PrimitiveTypeCollisionError before modifying the registry. Failed registrations abort cleanly without altering _REGISTRY or existing primitive_adapter instances.

Unregistering and rebuild ordering

To remove an extension primitive or prepare for a replacement, unregister the wire type name using unregister_primitive() and then call rebuild_primitive_union():

from astralprims import unregister_primitive, rebuild_primitive_union

unregister_primitive("ribbon")
rebuild_primitive_union()

Reload policy

Re-registering the exact same class object (for example, in interactive environments) is permitted. However, module reloads create a new, distinct class object for the same wire type, which triggers PrimitiveTypeCollisionError. To reload a module defining custom primitives, call unregister_primitive() on the custom wire types before reloading the module, then call rebuild_primitive_union().

Tests

pytest

License

Apache-2.0