streamtree 0.1.0__py3-none-any.whl

streamtree/__init__.py

@@ -0,0 +1,19 @@
+"""Streamtree: declarative, typed composition for Streamlit."""
+
+from streamtree import elements, state, testing
+from streamtree.core import ComponentCall, Element, Fragment, component, fragment, render
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ComponentCall",
+    "Element",
+    "Fragment",
+    "__version__",
+    "component",
+    "elements",
+    "fragment",
+    "render",
+    "state",
+    "testing",
+]

streamtree/core/__init__.py

@@ -0,0 +1,13 @@
+"""Core primitives: elements, components, render."""
+
+from streamtree.core.component import component, render
+from streamtree.core.element import ComponentCall, Element, Fragment, fragment
+
+__all__ = [
+    "ComponentCall",
+    "Element",
+    "Fragment",
+    "component",
+    "fragment",
+    "render",
+]

streamtree/core/component.py

@@ -0,0 +1,36 @@
+"""@component decorator and public render entrypoint."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from streamtree.core.context import render_context
+from streamtree.core.element import ComponentCall, Element
+from streamtree.renderers.streamlit import render_element as _render_streamlit
+
+P = ParamSpec("P")
+R = TypeVar("R", bound=Element)
+
+
+def component(fn: Callable[P, R]) -> Callable[P, ComponentCall]:
+    """Mark a function as a Streamtree component.
+
+    The function body runs when the tree is rendered (each Streamlit rerun),
+    not when building the virtual tree from call sites like ``Page(Counter())``.
+    """
+
+    @wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> ComponentCall:
+        kw = dict(kwargs)
+        key = kw.pop("key", None)  # type: ignore[assignment]
+        return ComponentCall(fn=fn, args=args, kwargs=kw, key=key)  # type: ignore[arg-type]
+
+    return wrapper  # type: ignore[return-value]
+
+
+def render(root: Element, *, context_root: str = "app") -> None:
+    """Render a virtual element tree using the Streamlit backend."""
+    with render_context(context_root):
+        _render_streamlit(root)

streamtree/core/context.py

@@ -0,0 +1,66 @@
+"""Render-time context for stable keys and nested component paths."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+
+_ctx: ContextVar[RenderContext | None] = ContextVar("streamtree_render_context", default=None)
+
+
+@dataclass
+class RenderContext:
+    """Stacked path segments and a per-scope counter for anonymous state slots."""
+
+    parent: RenderContext | None
+    segment: str
+    _counter: int = field(default=0, repr=False)
+
+    def child(self, segment: str) -> RenderContext:
+        return RenderContext(parent=self, segment=segment)
+
+    def next_anonymous_index(self) -> int:
+        i = self._counter
+        self._counter += 1
+        return i
+
+    def path(self) -> str:
+        if self.parent is None:
+            return self.segment
+        base = self.parent.path()
+        return f"{base}.{self.segment}" if base else self.segment
+
+
+def current_context() -> RenderContext:
+    c = _ctx.get()
+    if c is None:
+        raise RuntimeError("streamtree: no active render context; call from inside render()")
+    return c
+
+
+@contextmanager
+def render_context(root_segment: str = "app") -> Iterator[RenderContext]:
+    parent = _ctx.get()
+    ctx = (
+        RenderContext(parent=parent, segment=root_segment)
+        if parent
+        else RenderContext(parent=None, segment=root_segment)
+    )
+    token = _ctx.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _ctx.reset(token)
+
+
+@contextmanager
+def push_segment(segment: str) -> Iterator[RenderContext]:
+    parent = current_context()
+    ctx = parent.child(segment)
+    token = _ctx.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _ctx.reset(token)

streamtree/core/element.py

@@ -0,0 +1,51 @@
+"""Virtual element tree nodes."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, TypeAlias
+
+
+@dataclass(frozen=True)
+class Element:
+    """Base class for virtual tree nodes."""
+
+    key: str | None = None
+
+
+ElementChild: TypeAlias = Element | Sequence[Element | None] | None
+
+
+@dataclass(frozen=True)
+class Fragment(Element):
+    """Group multiple children without a Streamlit container."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+
+def normalize_children(children: tuple[ElementChild, ...]) -> tuple[Element, ...]:
+    out: list[Element] = []
+    for ch in children:
+        if ch is None:
+            continue
+        if isinstance(ch, Element):
+            out.append(ch)
+        elif isinstance(ch, Sequence) and not isinstance(ch, (str, bytes)):
+            out.extend(normalize_children(tuple(ch)))  # type: ignore[arg-type]
+        else:
+            raise TypeError(f"Invalid child type: {type(ch)!r}")
+    return tuple(out)
+
+
+def fragment(*children: ElementChild, key: str | None = None) -> Fragment:
+    return Fragment(key=key, children=normalize_children(children))
+
+
+@dataclass(frozen=True)
+class ComponentCall(Element):
+    """Deferred invocation of a @component function."""
+
+    fn: Callable[..., Element] = field(kw_only=True, repr=False)
+    args: tuple[Any, ...] = field(default_factory=tuple, kw_only=True)
+    kwargs: dict[str, Any] = field(default_factory=dict, kw_only=True)

streamtree/elements/__init__.py

@@ -0,0 +1,59 @@
+"""Declarative layout and widget primitives."""
+
+from streamtree.core.element import Element, Fragment, fragment
+from streamtree.elements.layout import (
+    Card,
+    Columns,
+    Expander,
+    Form,
+    Grid,
+    HStack,
+    Page,
+    Sidebar,
+    Spacer,
+    Tabs,
+    VStack,
+)
+from streamtree.elements.widgets import (
+    Button,
+    Checkbox,
+    DataFrame,
+    Divider,
+    Image,
+    Markdown,
+    NumberInput,
+    Selectbox,
+    Subheader,
+    Text,
+    TextInput,
+    Title,
+)
+
+__all__ = [
+    "Button",
+    "Card",
+    "Checkbox",
+    "Columns",
+    "DataFrame",
+    "Divider",
+    "Element",
+    "Expander",
+    "Form",
+    "Fragment",
+    "Grid",
+    "HStack",
+    "Image",
+    "Markdown",
+    "NumberInput",
+    "Page",
+    "Selectbox",
+    "Sidebar",
+    "Spacer",
+    "Subheader",
+    "Tabs",
+    "Text",
+    "TextInput",
+    "Title",
+    "VStack",
+    "fragment",
+]

streamtree/elements/layout.py

@@ -0,0 +1,164 @@
+"""Layout primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from streamtree.core.element import Element, ElementChild, normalize_children
+
+
+@dataclass(frozen=True)
+class VStack(Element):
+    """Render children vertically in order."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(self, *children: ElementChild, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class HStack(Element):
+    """Render children in a horizontal row of equal columns."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+    gap: str | None = None
+
+    def __init__(
+        self,
+        *children: ElementChild,
+        gap: str | None = None,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "gap", gap)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Columns(Element):
+    """Render children in weighted columns (``weights`` length must match children)."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+    weights: tuple[float, ...] = field(default_factory=tuple)
+
+    def __init__(
+        self,
+        *children: ElementChild,
+        weights: tuple[float, ...] | None = None,
+        key: str | None = None,
+    ) -> None:
+        ch = normalize_children(children)
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "children", ch)
+        if weights is None:
+            object.__setattr__(self, "weights", tuple(1.0 for _ in ch))
+        else:
+            object.__setattr__(self, "weights", weights)
+
+
+@dataclass(frozen=True)
+class Grid(Element):
+    """Render children left-to-right in a fixed column count."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+    columns: int = 2
+
+    def __init__(self, *children: ElementChild, columns: int = 2, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "columns", max(1, columns))
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Card(Element):
+    """Group content in a bordered container when supported by Streamlit."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(self, *children: ElementChild, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Page(Element):
+    """Top-level page container (column layout)."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(self, *children: ElementChild, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Tabs(Element):
+    """Named tabs; each entry is (title, child_element)."""
+
+    tabs: tuple[tuple[str, Element], ...] = ()
+
+    def __init__(self, *tabs: tuple[str, Element], key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "tabs", tabs)
+
+
+@dataclass(frozen=True)
+class Sidebar(Element):
+    """Render children in ``st.sidebar``."""
+
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(self, *children: ElementChild, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Form(Element):
+    """Streamlit form boundary."""
+
+    form_key: str = "form"
+    clear_on_submit: bool = False
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(
+        self,
+        *children: ElementChild,
+        form_key: str = "form",
+        clear_on_submit: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "form_key", form_key)
+        object.__setattr__(self, "clear_on_submit", clear_on_submit)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Expander(Element):
+    """Collapsible section."""
+
+    label: str = ""
+    expanded: bool = False
+    children: tuple[Element, ...] = field(default_factory=tuple)
+
+    def __init__(
+        self,
+        label: str,
+        *children: ElementChild,
+        expanded: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "expanded", expanded)
+        object.__setattr__(self, "children", normalize_children(children))
+
+
+@dataclass(frozen=True)
+class Spacer(Element):
+    """Vertical breathing room."""
+
+    height: int | None = None

streamtree/elements/widgets.py

@@ -0,0 +1,235 @@
+"""Leaf widgets and controls."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from streamtree.core.element import Element
+from streamtree.state import FormState, StateVar, ToggleState
+
+
+@dataclass(frozen=True)
+class Text(Element):
+    body: str = ""
+
+    def __init__(self, body: str, *, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "body", body)
+
+
+@dataclass(frozen=True)
+class Markdown(Element):
+    body: str = ""
+    unsafe_allow_html: bool = False
+
+    def __init__(
+        self,
+        body: str,
+        *,
+        unsafe_allow_html: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "body", body)
+        object.__setattr__(self, "unsafe_allow_html", unsafe_allow_html)
+
+
+@dataclass(frozen=True)
+class Button(Element):
+    label: str = ""
+    on_click: Callable[[], None] | None = None
+    disabled: bool = False
+    submit: bool = False
+    help: str | None = None
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        on_click: Callable[[], None] | None = None,
+        disabled: bool = False,
+        submit: bool = False,
+        help: str | None = None,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "on_click", on_click)
+        object.__setattr__(self, "disabled", disabled)
+        object.__setattr__(self, "submit", submit)
+        object.__setattr__(self, "help", help)
+
+
+@dataclass(frozen=True)
+class TextInput(Element):
+    label: str = ""
+    value: str | StateVar[str] | FormState[str] | None = None
+    placeholder: str | None = None
+    disabled: bool = False
+    type: Literal["default", "password"] = "default"
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        value: str | StateVar[str] | FormState[str] | None = None,
+        placeholder: str | None = None,
+        disabled: bool = False,
+        type: Literal["default", "password"] = "default",
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "value", value)
+        object.__setattr__(self, "placeholder", placeholder)
+        object.__setattr__(self, "disabled", disabled)
+        object.__setattr__(self, "type", type)
+
+
+@dataclass(frozen=True)
+class NumberInput(Element):
+    label: str = ""
+    value: int | float | StateVar[int] | StateVar[float] | None = None
+    min_value: int | float | None = None
+    max_value: int | float | None = None
+    step: int | float | None = None
+    format: str | None = None
+    disabled: bool = False
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        value: int | float | StateVar[int] | StateVar[float] | None = None,
+        min_value: int | float | None = None,
+        max_value: int | float | None = None,
+        step: int | float | None = None,
+        format: str | None = None,
+        disabled: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "value", value)
+        object.__setattr__(self, "min_value", min_value)
+        object.__setattr__(self, "max_value", max_value)
+        object.__setattr__(self, "step", step)
+        object.__setattr__(self, "format", format)
+        object.__setattr__(self, "disabled", disabled)
+
+
+@dataclass(frozen=True)
+class Selectbox(Element):
+    label: str = ""
+    options: Sequence[Any] = ()
+    index: int | StateVar[int] | None = None
+    format_func: Callable[[Any], str] | None = None
+    disabled: bool = False
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        options: Sequence[Any],
+        index: int | StateVar[int] | None = 0,
+        format_func: Callable[[Any], str] | None = None,
+        disabled: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "options", tuple(options))
+        object.__setattr__(self, "index", index)
+        object.__setattr__(self, "format_func", format_func)
+        object.__setattr__(self, "disabled", disabled)
+
+
+@dataclass(frozen=True)
+class Checkbox(Element):
+    label: str = ""
+    value: bool | StateVar[bool] | ToggleState | None = None
+    disabled: bool = False
+
+    def __init__(
+        self,
+        label: str,
+        *,
+        value: bool | StateVar[bool] | ToggleState | None = None,
+        disabled: bool = False,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "label", label)
+        object.__setattr__(self, "value", value)
+        object.__setattr__(self, "disabled", disabled)
+
+
+@dataclass(frozen=True)
+class DataFrame(Element):
+    data: Any = None
+    width: int | None = None
+    height: int | None = None
+
+    def __init__(
+        self,
+        data: Any,
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "data", data)
+        object.__setattr__(self, "width", width)
+        object.__setattr__(self, "height", height)
+
+
+@dataclass(frozen=True)
+class Image(Element):
+    image: Any = None
+    caption: str | None = None
+    width: int | None = None
+    use_column_width: bool | Literal["auto", "always", "never"] | None = None
+
+    def __init__(
+        self,
+        image: Any,
+        *,
+        caption: str | None = None,
+        width: int | None = None,
+        use_column_width: bool | Literal["auto", "always", "never"] | None = None,
+        key: str | None = None,
+    ) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "image", image)
+        object.__setattr__(self, "caption", caption)
+        object.__setattr__(self, "width", width)
+        object.__setattr__(self, "use_column_width", use_column_width)
+
+
+@dataclass(frozen=True)
+class Divider(Element):
+    """Horizontal rule."""
+
+    def __init__(self, *, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+
+
+@dataclass(frozen=True)
+class Title(Element):
+    text: str = ""
+
+    def __init__(self, text: str, *, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "text", text)
+
+
+@dataclass(frozen=True)
+class Subheader(Element):
+    text: str = ""
+
+    def __init__(self, text: str, *, key: str | None = None) -> None:
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "text", text)

streamtree/renderers/__init__.py

@@ -0,0 +1,5 @@
+"""Rendering backends."""
+
+from streamtree.renderers.streamlit import render_element
+
+__all__ = ["render_element"]