PyDataUI Core API & Methods Reference
Comprehensive specification of all core classes, methods, signatures, decorators, storage engines, and CLI tools in PyDataUI.
Table of Contents
- Application Core (
App) - State & Reactivity (
state,State,ProceduralState) - Authentication & Security (
AuthManager) - Storage Engines & Cluster Persistence (
storage) - Data Ingestion & Tabular Sniffing (
DataTable) - Pydantic Form Generator (
ShadForm) - Terminal User Interface Engine (
tui,run_tui) - CLI Command Reference
- Internal HTTP & Event Wire Protocol
1. Application Core (App)
class App(...)
Located in pydataui.app.App. The central orchestrator integrating routing, state snapshots, REST APIs, middleware, and the HTTP server engine.
from pydataui import App, AppConfig
app = App(
title="Enterprise AI Operations",
description="Internal control plane for SLM clusters",
version="1.2.2",
debug=False,
secret_key="your-32-byte-production-secret-key-goes-here",
session_store=None, # Defaults to SQLite or Memory
auth_store=None, # Defaults to SQLite or Memory
max_request_size=10 * 1024 * 1024 # 10 MB limit
)
Constructor Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
title |
str |
"PyDataUI App" |
The title shown in HTML document <title> and TUI dashboard headers. |
description |
str |
"" |
App description for OpenAPI metadata and page headers. |
version |
str |
"1.2.2" |
Semantic application version for telemetry and API catalogs. |
debug |
bool |
False |
Enables verbose stack traces and development logs. |
secret_key |
Optional[str] |
None |
Cryptographic secret for signing session cookies and JWT tokens. |
session_store |
Optional[BaseSessionStore] |
None |
Storage backend for user sessions (Memory, SQLite, Postgres). |
auth_store |
Optional[BaseAuthStore] |
None |
Storage backend for users and API keys (Memory, SQLite, Postgres). |
max_request_size |
int |
10485760 |
Max request body size in bytes (10MB). Rejects oversized requests with HTTP 413. |
Methods on App
app.page(path: str, title: Optional[str] = None, layout: Optional[Callable] = None)
Decorator that registers a Server-Side Rendered (SSR) page route.
- Parameters:
path(str): URL pattern (e.g.'/','/dashboard','/model/{model_id}').title(Optional[str]): Custom<title>override for this page.layout(Optional[Callable]): Wrapper layout function receiving the page content component.- Handler Return Value: Must return a
Componentinstance (e.g.Container,DashboardLayout,Card) or valid HTML string. - Example:
app.api(path: str, method: str = 'GET', public: bool = False, roles: tuple = (), **kwargs)
Decorator that registers a high-speed custom REST API endpoint on the underlying engine.
- Parameters:
path(str): REST endpoint path (e.g.'/api/v1/telemetry').method(str): HTTP verb ('GET','POST','PUT','DELETE').public(bool): IfTrue, bypasses authentication. Default isFalse.roles(tuple[str]): List of required role names (e.g.(Role.ADMIN,)).- Example:
app.setup_auth(auth_manager: AuthManager, allow_registration: bool = False)
Mounts standard /api/auth/* endpoints (/login, /logout, /me, /keys) and binds authentication middleware.
- Parameters:
auth_manager(AuthManager): Initialized authentication manager.allow_registration(bool): IfTrue, enables public/api/auth/register.
app.mount(path: str, asgi_app: Any)
Mounts an external ASGI application (such as an existing FastAPI, Starlette, or LangGraph backend) under a sub-path prefix.
- Parameters:
path(str): Prefix path (e.g.'/sub-api').asgi_app(Any): Valid ASGI-compatible app.
app.run(host: str = "127.0.0.1", port: int = 8000, reload: bool = False, workers: int = 1, share: bool = False)
Starts the production or development HTTP server.
- Parameters:
host(str): IP address to bind to ("127.0.0.1"for local,"0.0.0.0"for all interfaces).port(int): Port number.reload(bool): IfTrue, enables live auto-reloading on code edits.workers(int): Number of parallel multi-threaded worker processes.share(bool): Launches a public internet tunnel and prints the public HTTPS URL.
app.build_openapi() -> Dict[str, Any]
Generates an OpenAPI 3.0-compliant JSON dictionary documenting all registered REST APIs and state actions.
2. State & Reactivity
PyDataUI provides two state management models:
1. Procedural State (state()): Zero-class procedural hook ideal for scripts, internal dashboards, and prototypes.
2. Object-Oriented State (class State): Class-based reactive store for multi-model enterprise applications.
Procedural State Hook: state(**defaults) -> ProceduralState
from pydataui import state
# 1. Initialize state with default values
s = state(
counter=0,
active_node="Node-A",
messages=[{"role": "assistant", "content": "Welcome!"}],
loading=False
)
# 2. Register reactive action
@s.action
def increment():
s.counter += 1
@s.action
async def set_node(node_name: str = "", **kwargs):
s.active_node = node_name or kwargs.get("node", "Node-A")
Methods & Attributes on ProceduralState
@s.action: Decorator registering a function as an interactive server action callable via HTMX or the TUI.s.<variable_name>:- Inside
@s.actionhandlers: Resolves to the active session value and permits direct mutation. - Inside
@app.pagelayout declarations: Evaluates to aStateVarRefdescriptor that renders reactive bindings. s.to_dict() -> Dict[str, Any]: Returns a JSON-serializable dictionary of current state variables.s.reset(): Resets all values back to the original initial values.
Class-Based Reactive State: class State
from pydataui import State, StateVar
class ClusterState(State):
node_count: int = 8
region: str = "us-east-1"
is_busy: bool = False
def scale_up(self):
self.node_count += 1
def scale_down(self):
if self.node_count > 1:
self.node_count -= 1
Lifecycle & Session Isolation
- Each browser session / cookie receives an independent instance of
ClusterState. ClusterState.node_countaccessed on the class returns aStateVarReffor declarative component binding.self.node_countaccessed inside methods operates on the session's isolated instance.
3. Authentication & Security (AuthManager)
class AuthManager(secret_key, token_expire_hours=24, store=None, enable_throttling=True, ...)
Located in pydataui.auth.AuthManager. Implements production security:
- Password hashing with PBKDF2-HMAC-SHA256 (600,000 rounds) + unique salt.
- Signed JSON Web Tokens (JWT) with HMAC-SHA256.
- Brute-force rate limiting and lockout protection.
- Scoped API keys with prefix pdu_live_.
from pydataui import AuthManager, Role
from pydataui.storage import SQLiteAuthStore
auth = AuthManager(
secret_key="your-32-byte-secret-key-at-least-32-bytes-long",
token_expire_hours=24,
store=SQLiteAuthStore("auth.db"),
enable_throttling=True,
max_login_attempts=5,
lockout_duration_seconds=300
)
Methods on AuthManager
| Method Signature | Return Type | Description |
|---|---|---|
add_user(username, password, email="", roles=None) |
User |
Provisions a new user. Hashes password with unique salt. Raises ValueError if username exists. |
get_or_create_user(username, password, email="", roles=None) |
User |
Idempotently retrieves existing user or creates a new one. |
authenticate(username, password, client_ip=None) |
Optional[str] |
Validates credentials against password hash. If valid, returns signed JWT token string; if invalid or throttled, returns None or raises AuthenticationThrottledError. |
verify_token(token: str) |
Optional[User] |
Decodes and verifies a JWT token. Returns User object if valid, or None if expired/tampered. |
create_api_key(name, user_id, scopes=None, expires_days=None) |
APIKey |
Generates a scoped API key string starting with pdu_live_ and stores SHA256 key hash. |
verify_api_key(raw_key: str) |
Optional[APIKey] |
Validates an API key, checks expiration, updates last_used timestamp, and increments usage counter. |
revoke_api_key(key_id: str) |
bool |
Deactivates an API key. |
list_api_keys(user_id: str) |
List[APIKey] |
Returns all API keys belonging to a user. |
set_user_password(user_id: str, new_password: str) |
bool |
Resets user password to new salted hash. |
delete_user(user_id: str) |
bool |
Permanently deletes user from identity store. |
Security Decorators
@require_auth: Protects an endpoint or page; redirects unauthenticated requests to/login.@require_role(Role.ADMIN): Requires specific role clearance.@require_api_key(scopes=["read:telemetry"]): Enforces valid API key inX-API-KeyorAuthorizationheader.
4. Storage Engines & Cluster Persistence (storage)
PyDataUI supports swappable session and authentication storage backends:
from pydataui.storage import (
MemorySessionStore, SQLiteSessionStore, PostgresSessionStore,
MemoryAuthStore, SQLiteAuthStore, PostgresAuthStore
)
Storage Backends Comparison
| Store | Durability | Multi-Process / Cluster Safe | Best For |
|---|---|---|---|
| Memory | Ephemeral | No (single process only) | Unit testing, local development |
| SQLite | Persistent disk | Yes (WAL mode with SQLite lock management) | Single-node production, embedded appliances |
| PostgreSQL | Distributed | Yes (cluster-wide shared identity & sessions) | Multi-node Kubernetes, high-availability deployments |
5. Data Ingestion & Tabular Sniffing (DataTable)
sniff_tabular_data(data: Any) -> Tuple[List[Dict[str, Any]], List[str]]
Automatically sniffs, extracts columns, and normalizes tabular data from:
- pandas.DataFrame
- polars.DataFrame
- duckdb.PyRelation
- pyarrow.Table
- list[pydantic.BaseModel]
- list[dict]
import polars as pl
from pydataui import DataTable
df = pl.DataFrame({
"cluster": ["us-east", "eu-west", "ap-south"],
"nodes": [12, 8, 16],
"status": ["HEALTHY", "HEALTHY", "WARNING"]
})
DataTable(
data=df,
searchable=True,
paginated=True,
page_size=10,
bordered=True
)
6. Pydantic Form Generator (ShadForm)
ShadForm.from_pydantic(model_cls, on_submit, submit_label="Submit", ...)
Generates validated input fields matching Pydantic type annotations:
- str -> Text <input>
- int, float -> Number <input>
- bool -> <switch> or <checkbox>
- datetime.date -> <input type="date">
- Enum -> <select> dropdown
- Field(description="...") -> Helper description text
- Field(ge=..., le=...) -> Min / max HTML validation constraints
7. Terminal User Interface Engine (tui)
PyDataUI includes a built-in terminal dashboard engine (pydataui.tui.run_tui):
Keyboard Navigation & Commands
| Input Command | Action in TUI Mode |
|---|---|
[1-N] |
Switches directly to page index number 1 through N. |
<action_name> |
Executes a registered state action method. |
input <text> |
Passes input string to active page handler. |
set <key>=<value> |
Updates a state variable directly from the terminal prompt. |
r |
Refreshes terminal dashboard rendering. |
q or quit |
Cleanly exits the TUI session without double confirmation. |
Interactive AI Chat in TUI
When a page contains a Chat component, the TUI activates conversational chat mode:
- Number keys (1, 2, 3) instantly execute numbered suggestion chips.
- /clear invokes the on_clear handler and resets conversation history.
- q cleanly exits back to the terminal prompt.
8. CLI Command Reference
The pydataui CLI provides commands for the full application lifecycle:
# 1. Create a new application from template
pydataui new my_app --template ml-dashboard
# 2. Start local development server with auto-reload
pydataui dev app.py --port 8000 --reload
# 3. Run production server
pydataui run app.py --host 0.0.0.0 --port 8000 --workers 4
# 4. Run interactive Terminal UI (TUI)
pydataui run --tui app.py
# 5. Share via secure public HTTPS tunnel
pydataui run app.py --share
# 6. Syntax and routing validation check
pydataui check app.py
# 7. Generate production API key
pydataui generate key --name "TelemetryWorker"
# 8. Show installed framework version
pydataui version
9. Internal HTTP & Event Wire Protocol
PyDataUI uses clean REST endpoints and HTMX partial swap protocols:
| Route Pattern | Method | Purpose | Response Format |
|---|---|---|---|
GET / |
GET |
SSR HTML Page initial load | text/html |
POST /_pdu/event/{State}/{action} |
POST |
Reactive UI event trigger | text/html (DOM Partial) |
GET /api/{State} |
GET |
State variable snapshot | application/json |
POST /api/{State}/{action} |
POST |
Headless REST action trigger | application/json |
POST /api/auth/login |
POST |
User credential authentication | application/json (JWT Token) |
POST /api/auth/logout |
POST |
Session termination | application/json |
GET /api/auth/me |
GET |
Authenticated user profile | application/json |
GET /_pdu/health |
GET |
Infrastructure health check | application/json |
GET /docs |
GET |
OpenAPI Swagger documentation | text/html |