Skip to content

PyDataUI — Quick Reference Card

Minimal App

from pydataui import App, State
from pydataui.components import Container, Button, Heading

class MyState(State):
    count: int = 0
    def increment(self): self.count += 1

app = App(title="My App")

@app.page("/")
def home():
    return Container(
        Heading(MyState.count),
        Button("+", on_click=MyState.increment),
    )

app.run()

State Rules

class AppState(State):
    # Reactive variables — type-annotated
    name: str = "World"
    count: int = 0
    items: list = []
    active: bool = True

    # Event handlers — regular methods
    def update_name(self, name: str = ""):
        self.name = name

    def add_item(self, text: str = ""):
        self.items.append(text)
  • Class access AppState.name → StateVarRef (reactive, use in components)
  • Class access AppState.update_name → EventHandler (use in event props)
  • Instance access AppState().name → actual Python value

URL Routes

URL What it does
GET / Your page (from @app.page("/"))
GET /docs Swagger UI
GET /api/docs Swagger UI (alternate)
GET /api REST API catalog (all states)
GET /api/health Health check
GET /api/{State} Full state JSON
GET /api/{State}/{field} Single field
PUT /api/{State} Update state (JSON body)
DELETE /api/{State} Reset to defaults
POST /api/{State}/{method} Call method (JSON args in body)
POST /_pdu/event/{State}/{method} HTMX internal event (SSR)
GET /_pdu/static/htmx.min.js Bundled HTMX
GET /_pdu/static/pydataui.css Bundled CSS

Event Binding

# Direct method reference
Button("Click", on_click=MyState.do_something)

# With captured argument
Button("Del", on_click=lambda id=item_id: MyState.delete(id))

# With options
from pydataui.event import EventSpec
Button("Save", on_click=EventSpec(
    MyState.save,
    confirm="Are you sure?",
    debounce=500,
))

Component Quick Reference

Layout

Container(child, max_width="lg")
Flex(a, b, gap="md", justify="center", align="center")
Grid(a, b, c, columns=3, gap="md")
Box(child, padding="lg", margin="sm")
HStack(a, b, gap="md")
VStack(a, b, gap="md")
Divider()
Spacer()

Typography

Heading("Title", level=1)       # h1-h6
Text("Body text", color="muted")
Paragraph("Long text...")
Code("print('hello')")
Link("Click", href="/page")

Forms

Button("Click", variant="primary", on_click=State.method)
# variants: primary | secondary | success | danger | warning | outline | ghost
# sizes: xs | sm | md | lg | xl

Input("Label", type="text", bind=State.field, placeholder="...")
# types: text | email | password | number | date | tel | url

TextArea("Label", bind=State.content, rows=5)
Select("Label", options=["A","B","C"], bind=State.choice)
Checkbox("Agree", bind=State.agreed)
Switch("Dark Mode", bind=State.dark)

Data

Table(columns=["Name","Email"], data=[["A","a@x.com"]])
Badge("Active", variant="success")
Stat(label="Revenue", value="$12,345", change="+23%", trend="up")
Progress(value=75, max=100)

Feedback

Alert("Message", variant="success")  # success | warning | danger | info
Spinner(size="md")
Skeleton(width="100%", height="20px")

Overlay

Modal(title="...", is_open=State.show, on_close=State.close, children=[...])
Drawer(title="...", is_open=State.show, position="right", children=[...])

Charts

BarChart(labels=["Q1","Q2"], datasets=[{"label":"Sales","data":[100,200]}])
LineChart(labels=[...], datasets=[...])
PieChart(labels=[...], datasets=[...])
Navbar(title="App", links=[("Home","/"),("API","/api")])
Sidebar(links=[("Dashboard","/"),("Users","/users")])
Tabs(Tab("Tab1", content=...), Tab("Tab2", content=...))
Breadcrumb(items=[("Home","/"),("Users","/users"),("John",None)])

REST API (curl examples)

# Get state
curl http://localhost:8000/api/MyState

# Call method with no args
curl -X POST http://localhost:8000/api/MyState/increment

# Call method with args
curl -X POST http://localhost:8000/api/MyState/add_item \
  -H "Content-Type: application/json" \
  -d '{"text": "New item"}'

# Update state
curl -X PUT http://localhost:8000/api/MyState \
  -H "Content-Type: application/json" \
  -d '{"count": 99}'

# Reset state
curl -X DELETE http://localhost:8000/api/MyState

# Get single field
curl http://localhost:8000/api/MyState/count

# API catalog
curl http://localhost:8000/api

Custom Endpoints

@app.api("/export", method="GET")
def export_csv(request):
    return {"data": [...]}

@app.api("/webhook", method="POST")
def handle_webhook(request):
    data = request.json()
    return {"received": True}