Metadata-Version: 2.5
Name: hedron
Version: 0.57.0
Summary: FastAPI-native typed component framework for HTML and HTMX
Project-URL: Homepage, https://github.com/eddiethedean/hedron
Project-URL: Repository, https://github.com/eddiethedean/hedron
Project-URL: Issues, https://github.com/eddiethedean/hedron/issues
Project-URL: Changelog, https://github.com/eddiethedean/hedron/blob/main/packages/hedron/CHANGELOG.md
Project-URL: Documentation, https://hedron.readthedocs.io/en/latest/
Author-email: Odos Matthews <odosmatthews@gmail.com>
Maintainer-email: Odos Matthews <odosmatthews@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: components,fastapi,html,htmx,server-rendered,typed
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: fastapi<0.150,>=0.141.1
Requires-Dist: hedron-core<0.58,>=0.57.0
Requires-Dist: itsdangerous>=2.2
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic<2.15,>=2.13.4
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: auth
Requires-Dist: authlib>=1.3; extra == 'auth'
Requires-Dist: httpx>=0.28; extra == 'auth'
Provides-Extra: browser
Requires-Dist: axe-playwright-python>=0.1.4; extra == 'browser'
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: charts
Requires-Dist: hedron-charts<0.3,>=0.2.0; extra == 'charts'
Provides-Extra: code
Requires-Dist: pygments>=2.17; extra == 'code'
Provides-Extra: conformance
Requires-Dist: hedron-conformance<0.58,>=0.57.0; extra == 'conformance'
Provides-Extra: data
Requires-Dist: hedron-data<0.58,>=0.57.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: hedron-explorer<0.58,>=0.57.0; extra == 'dev'
Provides-Extra: elements
Requires-Dist: hedron-elements<0.58,>=0.57.0; extra == 'elements'
Provides-Extra: email
Requires-Dist: email-validator>=2.0; extra == 'email'
Provides-Extra: experimental-ui
Requires-Dist: hedron-extras[experimental-ui]<0.58,>=0.57.0; extra == 'experimental-ui'
Provides-Extra: extras
Requires-Dist: hedron-extras<0.58,>=0.57.0; extra == 'extras'
Provides-Extra: gradio
Requires-Dist: hedron-gradio<0.3,>=0.2.0; extra == 'gradio'
Provides-Extra: images
Requires-Dist: pillow>=10.0; extra == 'images'
Provides-Extra: jinja
Requires-Dist: hedron-jinja<0.58,>=0.57.0; extra == 'jinja'
Provides-Extra: maps
Requires-Dist: hedron-maps<0.2,>=0.1.0; extra == 'maps'
Provides-Extra: markdown
Requires-Dist: markdown>=3.5; extra == 'markdown'
Requires-Dist: nh3>=0.2; extra == 'markdown'
Provides-Extra: mcp
Requires-Dist: hedron-mcp<0.3,>=0.2.0; extra == 'mcp'
Provides-Extra: native
Requires-Dist: hedron-native<0.2,>=0.1.2; extra == 'native'
Provides-Extra: notebook
Requires-Dist: hedron-notebook<0.2,>=0.1.0; extra == 'notebook'
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2,>=1.27; extra == 'otel'
Provides-Extra: posit
Requires-Dist: hedron-posit<0.58,>=0.57.0; extra == 'posit'
Provides-Extra: sanitize
Requires-Dist: nh3>=0.2; extra == 'sanitize'
Provides-Extra: workbench
Requires-Dist: hedron-workbench<0.58,>=0.57.0; extra == 'workbench'
Description-Content-Type: text/markdown

# Hedron

[![PyPI](https://img.shields.io/pypi/v/hedron.svg)](https://pypi.org/project/hedron/)
[![Python](https://img.shields.io/pypi/pyversions/hedron.svg)](https://pypi.org/project/hedron/)
[![CI](https://img.shields.io/github/actions/workflow/status/eddiethedean/hedron/ci.yml?branch=main&label=CI)](https://github.com/eddiethedean/hedron/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/eddiethedean/hedron/blob/main/LICENSE)

**Build admin tools, CRUD apps, and dashboards in Python—without building a separate
frontend.**

Hedron is a typed, server-rendered UI framework for FastAPI. Routes return Python
components, Hedron renders safe HTML, and HTMX updates just the part of the page that
changed. You keep FastAPI's routing, dependency injection, middleware, and JSON APIs;
you do not need a Node.js toolchain or a full-script rerun model.

![A Hedron app with a status panel updated by HTMX](https://raw.githubusercontent.com/eddiethedean/hedron/main/docs/assets/hello-refresh.jpg)

Requires Python 3.11–3.14. Pin the published `hedron>=0.56.0,<0.58` release from PyPI.
The repository checkout tip is `v0.57.0` (PyPI still `0.56.0`; Git tag/PyPI upload for 0.57.0 is deferred). The fastest path uses
[`uv`](https://docs.astral.sh/uv/getting-started/installation/):

```bash
uvx --from "hedron>=0.56.0,<0.58" hedron new my-hedron-app
cd my-hedron-app
uv sync
uv run uvicorn app:app --reload
```

Open [http://127.0.0.1:8000](http://127.0.0.1:8000), then click **Refresh status**.
Only the status region is returned and swapped into the page.

The generated app (from `hedron new`) is ordinary Python:

```python
import os
from datetime import UTC, datetime

from hedron import Hedron, Page, Stack, Text, html

app = Hedron(
    title="Hedron App",
    security="standard",
    explorer="off",
    session_secret=os.environ.get("HEDRON_SESSION_SECRET", "replace-in-production"),
)


@app.refreshable("/status")
def status():
    stamp = datetime.now(UTC).strftime("%H:%M:%S UTC")
    return html.div(
        Text(f"All systems operational · refreshed {stamp}"),
        role="status",
        aria={"live": "polite"},
    )


@app.command(fallback="/")
def ping():
    from hedron import refresh

    return refresh(status).toast("Refreshed")


@app.page("/")
def home() -> Page:
    return Page(
        Stack(
            Text("Hello from hedron new"),
            status(),
            status.refresh_button("Refresh status"),
            ping.button("Ping"),
        ),
        title="Home",
    )
```

Undeclared HTMX targets fail closed.

[Follow the first-app walkthrough](https://hedron.readthedocs.io/en/latest/getting-started/quickstart/)
or browse the
[single-file examples](https://hedron.readthedocs.io/en/latest/examples/single-file/).

## What Hedron gives you

| Need | Hedron provides |
|---|---|
| Server-rendered UI | Typed pages, layouts, forms, tables, dialogs, status views, and media components |
| Partial-page interaction | Declared HTMX fragments, out-of-band updates, progressive-enhancement paths, and target allowlists |
| FastAPI integration | Normal routes, dependencies, middleware, lifespan hooks, responses, and OpenAPI alongside UI routes |
| Safer defaults | Contextual escaping, typed URL/HTML trust boundaries, CSRF profiles, and conservative caching |
| Production building blocks | Polling jobs, diagnostics, testing helpers, build manifests, deployment guidance, and Flask/Django adapters |

Your application still owns authentication, authorization, persistence, tenancy, and
deployment. Hedron is not an ORM, identity provider, hosted service, or client-side SPA
runtime.

## When it fits

Choose Hedron when you want to build forms, internal tools, admin surfaces, or dashboards
as a conventional web application while keeping most UI code in typed Python. It is
especially useful when raw FastAPI plus Jinja plus HTMX would leave you assembling the
same rendering, fragment, CSRF, asset, and component conventions yourself.

Choose Streamlit for notebook-style, full-script-rerun data apps. Choose raw FastAPI and
templates when you do not want a component framework. Choose a client-side framework when
the product genuinely needs a large browser-side state model.

Coming from Streamlit? Start with the
[migration center](https://hedron.readthedocs.io/en/latest/guides/streamlit-migration/).

## Install

The latest installable PyPI release is `hedron>=0.56.0,<0.58`. The repository contains
the published `0.56.x` train; use `uv sync` when working from a checkout.

```bash
uv add "hedron>=0.56.0,<0.58" "uvicorn[standard]"
# or
python -m pip install "hedron>=0.56.0,<0.58" "uvicorn[standard]"
```

**Package maturity:** Beta · **Repository train:** `0.56.x` · **Latest PyPI release:** `0.56.0` · **Application pin:** `>=0.56.0,<0.58`

Before deploying, read
[What's ready today](https://hedron.readthedocs.io/en/latest/guides/whats-ready/) and the
[shipping guide](https://hedron.readthedocs.io/en/latest/guides/ship/). Polling is the
supported production status-update path; SSE and WebSocket helpers remain experimental.

## Add only what you need

The base package includes the FastAPI application, typed UI, HTML renderer, HTMX
interactions, security profiles, and CLI. Integrations are optional:

| Install | Adds |
|---|---|
| `hedron[data]` | DataTable and DataEditor |
| `hedron[charts]` | Charts with a compatible satellite floor |
| `hedron[maps]` | First-class maps (`hedron-maps`) |
| `hedron[jinja]` | Optional `.hdj` templates |
| `hedron[dev]` | Component Explorer |
| `hedron[extras]` | Curated workbenches |
| `hedron[auth]` | Authlib OIDC helpers |
| `hedron[markdown]` | Markdown rendering and sanitization |
| `hedron[native]` | Optional Beta native acceleration |
| `hedron[mcp]` | Beta MCP projection (Supported inventory; mutations Experimental) |
| `hedron[notebook]` | Beta tooling-grade localhost preview; not a production server |
| `hedron[gradio]` | Beta allowlisted Gradio/Hugging Face client interoperability |
| `hedron[elements]` | Beta Web Component ABI (Supported inventory only) |

For example:

```bash
uv add "hedron[data,dev]>=0.56.0,<0.58"
```

Charts require the fixed compatible floor:

```bash
uv add "hedron[charts]>=0.56.0,<0.58"
```

See the full
[installation and extras guide](https://hedron.readthedocs.io/en/latest/getting-started/installation/)
and the
[compatibility matrix](https://hedron.readthedocs.io/en/latest/COMPATIBILITY/).

## Already have a FastAPI app?

You can mount Hedron's router and static assets without replacing your application:

```python
from fastapi import FastAPI
from hedron import HTML, HedronRouter, Text, hedron_response, mount_hedron_static
from hedron.security.policy import SecurityPolicy

app = FastAPI()
app.state.hedron_security = SecurityPolicy.from_name("standard")
mount_hedron_static(app)

ui = HedronRouter()


@ui.get("/hello", **hedron_response())
def hello():
    return HTML(Text("Hello from Hedron"))


app.include_router(ui)
```

[Read the existing-FastAPI guide](https://hedron.readthedocs.io/en/latest/guides/plain-fastapi/).
Flask and Django hosts are available through
[`hedron-flask`](https://pypi.org/project/hedron-flask/) and
[`hedron-django`](https://pypi.org/project/hedron-django/); both share the framework-neutral
[`hedron-core`](https://pypi.org/project/hedron-core/) renderer.

## CLI

```bash
python -m hedron new demoapp
python -m hedron --app app:app routes
python -m hedron --app app:app components
python -m hedron --app app:app preview home
python -m hedron --app app:app check
python -m hedron --app app:app graph
```

## Learn more

- [Documentation](https://hedron.readthedocs.io/en/latest/)
- [Learning path](https://hedron.readthedocs.io/en/latest/getting-started/learning-path/)
- [Architecture](https://hedron.readthedocs.io/en/latest/ARCHITECTURE/)
- [Components](https://hedron.readthedocs.io/en/latest/components/)
- [Changelog](https://github.com/eddiethedean/hedron/blob/main/packages/hedron/CHANGELOG.md)
- [Source](https://github.com/eddiethedean/hedron/tree/main/packages/hedron)
- [Issues](https://github.com/eddiethedean/hedron/issues)

## License

MIT. See the [license](https://github.com/eddiethedean/hedron/blob/main/LICENSE).
