Components API Reference¶

Complete reference for the Pytonium reactive components system.

from Pytonium.components import (
    Component, State, Computed, Element,
    Div, Span, P, H1, H2, H3, H4, H5, H6,
    Button, Input, Textarea, Select, Option, Label, Form,
    A, Img, Ul, Ol, Li, Table, Tr, Td, Th, Thead, Tbody,
    Header, Footer, Nav, Section, Article, Main,
    Pre, Code, Hr, Br, Strong, Em,
    Show, Switch, EventData,
)

Component¶

Base class for reactive components. Subclass it, define State fields, and implement render().

setup¶

@staticmethod
Component.setup(pytonium) -> None

Pre-register event handlers and the page-ready sentinel with CEF. Must be called before pytonium.initialize().

__init__¶

Component(**kwargs)

Create a component instance. Keyword arguments matching State field names set initial values.

counter = Counter(count=10)

render¶

render() -> Element

Return the element tree for this component. Called once during mount(). Must be overridden by subclasses.

mount¶

mount(pytonium, container_id: str | None = None) -> None

Mount the component into a browser. Calls render(), injects HTML, analyzes dependencies, and registers events.

unmount¶

unmount() -> None

Unmount the component. Removes event handlers, cleans up the dependency graph, and calls on_unmount().

on_mount¶

on_mount() -> None

Lifecycle hook called after mount() completes. Override to initialize resources.

on_update¶

on_update(changed_fields: set[str]) -> None

Lifecycle hook called after state changes are applied to the DOM.

on_unmount¶

on_unmount() -> None

Lifecycle hook called when the component is unmounted. Override to clean up resources.

State¶

Reactive state descriptor. Declare as a class attribute on a Component subclass.

State(default=None)

class Counter(Component):
    count = State(0)
    name = State("World")
    items = State([])

Reads trigger dependency tracking during render(). Writes trigger DOM updates through the dependency graph.

Computed¶

Cached, auto-invalidating derived property.

@Computed
def property_name(self) -> Any:
    ...

The return value is cached until any upstream State field changes. DOM bindings that reference the Computed property update automatically.

class Cart(Component):
    items = State([])

    @Computed
    def total(self):
        return sum(item["price"] for item in self.items)

Element¶

HTML element builder with fluent API.

Constructor¶

Element(tag: str, **attrs) -> Element

Create an element with the given HTML tag. Keyword arguments set static HTML attributes.

Element("div", class_name="container", data_role="main")
# → <div class="container" data-role="main" data-pyt-id="...">

child¶

child(element: Element) -> Element

Append a single child element. Returns self.

children¶

children(*elements: Element) -> Element

Append multiple child elements. Returns self.

text¶

text(content: str | Callable) -> Element

Set text content. Pass a string for static content or a lambda for reactive content.

attr¶

attr(name: str, value: str | Callable) -> Element

Set an HTML attribute. Pass a lambda for reactive attributes.

id¶

id(html_id: str) -> Element

Set the HTML id attribute.

class_name¶

class_name(name: str) -> Element

Add one or more static CSS classes (space-separated).

class_toggle¶

class_toggle(name: str, condition: Callable) -> Element

Toggle a CSS class based on a reactive boolean condition.

style¶

style(prop: str, value: str | Callable) -> Element

Set an inline style property. Pass a lambda for reactive styles.

bind_value¶

bind_value(component: Component, field_name: str, debounce_ms: int = 0) -> Element

Two-way binding between an input element's value and a State field.

Event Methods¶

All event methods take a single handler parameter and return self.

on_click(handler: Callable) -> Element
on_dblclick(handler: Callable) -> Element
on_keydown(handler: Callable) -> Element
on_keyup(handler: Callable) -> Element
on_input(handler: Callable) -> Element
on_change(handler: Callable) -> Element
on_submit(handler: Callable) -> Element
on_mouseenter(handler: Callable) -> Element
on_mouseleave(handler: Callable) -> Element
on_focus(handler: Callable) -> Element
on_blur(handler: Callable) -> Element

Handlers may take zero arguments or one EventData argument.

children_from¶

children_from(source: Callable, key: Callable, render_item: Callable) -> Element

Render dynamic children from a reactive list source with keyed reconciliation.

to_html¶

to_html() -> str

Generate the HTML string with data-pyt-id markers. Reactive bindings are evaluated once for initial values.

Convenience Constructors¶

Functions that return Element(tag). All accept **attrs.

EventData¶

Deserialized DOM event data passed to Python handlers.

@dataclass
class EventData:
    type: str = ""
    value: str = ""
    key: str = ""
    key_code: int = 0
    client_x: float = 0.0
    client_y: float = 0.0
    shift_key: bool = False
    ctrl_key: bool = False
    alt_key: bool = False
    meta_key: bool = False
    checked: bool = False

Show¶

Conditional rendering element with two branches.

Show(when: Callable, then: Callable, fallback: Callable | None = None)

Renders as a <div> placeholder. When the condition changes, the old branch is unmounted and the new branch is mounted in its place.

Switch¶

Multi-branch conditional rendering element.

Switch(selector: Callable)

case¶

case(value: Any, element_fn: Callable) -> Switch

Register a branch for a specific selector value. Returns self for chaining.

default¶

default(element_fn: Callable) -> Switch

Register the fallback branch (when no case matches). Returns self.

EventRouter¶

Routes DOM events from JavaScript to Python handlers. Typically used internally by Component, but available for advanced use.

prepare¶

@classmethod
EventRouter.prepare(pytonium) -> None

Pre-register the global event handler with CEF. Called by Component.setup(). Must be called before pytonium.initialize().

register_events¶

register_events(element: Element, bind_to_js: bool = True) -> None

Register event listeners for an element tree. Walks the tree recursively.

cleanup¶

cleanup() -> None

Remove all handlers and unregister this router.

DependencyTracker¶

Tracks dependencies between State fields and DOM bindings. All methods are classmethods operating on shared class state.

reset¶

@classmethod
DependencyTracker.reset() -> None

Reset all tracking state. Used in tests and between mounts.

register_component¶

@classmethod
DependencyTracker.register_component(component: Component) -> None

Register a component for dependency tracking. Called during mount().

unregister_component¶

@classmethod
DependencyTracker.unregister_component(component: Component) -> None

Remove all dependency mappings for a component. Called during unmount().

UpdateType¶

Enum of DOM mutation types used internally by the MutationCompiler.

class UpdateType(Enum):
    SET_TEXT_CONTENT = "text_content"
    SET_ATTRIBUTE = "set_attribute"
    REMOVE_ATTRIBUTE = "remove_attribute"
    ADD_CLASS = "add_class"
    REMOVE_CLASS = "remove_class"
    TOGGLE_CLASS = "toggle_class"
    SET_STYLE = "set_style"
    SET_VALUE = "set_value"
    INSERT_CHILD = "insert_child"
    REMOVE_CHILD = "remove_child"
    MOVE_CHILD = "move_child"
    REPLACE_INNER_HTML = "replace_inner_html"