Universal Hypermedia System for Starlette & FastAPI
Project description
StarLive
Universal Hypermedia System for Starlette & FastAPI
Build dynamic, real-time web applications with automatic HTMX/Turbo detection and WebSocket streaming
StarLive automatically detects HTMX/Turbo clients and provides unified streaming responses with real-time WebSocket updates.
Features
- Universal API: One codebase for both HTMX and Turbo
- Auto-detection: Framework detection via request headers
- Real-time: WebSocket streaming to all clients
- Zero config: Works out of the box
Installation
pip install starlive
Quick Start
from starlette.applications import Starlette
from starlette.responses import HTMLResponse
from starlette.routing import Route
from starlive import StarLive, StarLiveMiddleware
starlive = StarLive()
async def homepage(request):
return HTMLResponse(f"""
<html>
<head>{starlive.get_scripts()}</head>
<body>
<div id="content">
<button hx-post="/update" hx-target="#content">Update</button>
</div>
</body>
</html>
""")
async def update_content(request):
if request.state.can_stream():
content = '<div>Updated!</div>'
if request.state.hypermedia_type == "htmx":
return HTMLResponse(content)
else: # Turbo
stream = starlive.update(content, "#content",
hypermedia_type=request.state.hypermedia_type)
return starlive.stream(stream, request.state.hypermedia_type)
return HTMLResponse("Updated!")
app = Starlette(routes=[
Route("/", homepage),
Route("/update", update_content, methods=["POST"]),
])
app.add_middleware(StarLiveMiddleware, starlive=starlive)
app.router.routes.append(starlive.create_websocket_route())
FastAPI
from fastapi import FastAPI, Request
from starlive import StarLive, StarLiveMiddleware
starlive = StarLive()
app = FastAPI()
app.add_middleware(StarLiveMiddleware, starlive=starlive)
@app.websocket(starlive.ws_route)
async def websocket_endpoint(websocket):
await starlive._websocket_endpoint(websocket)
# Use same handlers as Starlette example
Stream Operations
# All work with both HTMX and Turbo
starlive.append(content, "#target")
starlive.prepend(content, "#target")
starlive.replace(content, "#target")
starlive.update(content, "#target")
starlive.remove("#target")
starlive.before(content, "#target")
starlive.after(content, "#target")
Real-time Updates
# Broadcast to all clients
await starlive.push(
starlive.append('<div>New message</div>', "#messages"),
to=None
)
# Custom user identification
@starlive.user_id
def get_user_id():
return request.session.get("user_id", "anonymous")
Request Detection
if request.state.hypermedia_type == "htmx":
return HTMLResponse("<div>HTMX response</div>")
elif request.state.hypermedia_type == "turbo":
return starlive.stream(starlive.update(content, "#target"), "turbo")
else:
return JSONResponse({"data": "value"})
Templates
from starlette.templating import Jinja2Templates
from starlive import starlive_context_processor
templates = Jinja2Templates(directory="templates")
templates.env.globals.update(starlive_context_processor(starlive)())
<head>
{{ starlive.get_scripts() }}
</head>
Examples
# Interactive demo
uv run starlive-dev
# Specific frameworks
uv run starlive-dev --framework starlette # http://localhost:8001
uv run starlive-dev --framework fastapi # http://localhost:8002
Development
git clone https://github.com/yourusername/starlive.git
cd starlive
uv sync --dev
Testing
uv run starlive-test # All tests
uv run starlive-test --framework fastapi # FastAPI only
uv run starlive-test --type e2e # End-to-end only
uv run starlive-test --coverage # With coverage
Code Quality
uv run ruff check src/ tests/ examples/
uv run ruff format src/ tests/ examples/
License
Apache 2.0 License. See LICENSE for details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
starlive-0.2.0.tar.gz
(32.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
starlive-0.2.0-py3-none-any.whl
(15.2 kB
view details)
File details
Details for the file starlive-0.2.0.tar.gz.
File metadata
- Download URL: starlive-0.2.0.tar.gz
- Upload date:
- Size: 32.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fa7f973ec3b06af0a621b50d29f219454fe8d2ca61384f6cce04684e8c336496
|
|
| MD5 |
b8b14319491c9f96eb8c3f4e04ee1d97
|
|
| BLAKE2b-256 |
6d994d186ca29022190c3e0a11bfa86df4b4728ee1186d0ebd8ba949e39502f6
|
Provenance
The following attestation bundles were made for starlive-0.2.0.tar.gz:
Publisher:
release.yml on PsiACE/starlive
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlive-0.2.0.tar.gz -
Subject digest:
fa7f973ec3b06af0a621b50d29f219454fe8d2ca61384f6cce04684e8c336496 - Sigstore transparency entry: 226948864
- Sigstore integration time:
-
Permalink:
PsiACE/starlive@590540cbcb30f1ec54d4993638fb597028d647e9 -
Branch / Tag:
refs/tags/0.2.0 - Owner: https://github.com/PsiACE
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@590540cbcb30f1ec54d4993638fb597028d647e9 -
Trigger Event:
push
-
Statement type:
File details
Details for the file starlive-0.2.0-py3-none-any.whl.
File metadata
- Download URL: starlive-0.2.0-py3-none-any.whl
- Upload date:
- Size: 15.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9b6995f2c8da3e0189b9d03ac33750b0ffb617d014bfebb6656167f08352fe70
|
|
| MD5 |
656a03332d5c3f25c1ac6ce65537f666
|
|
| BLAKE2b-256 |
7b2945aba3644b2e810726bf043c473cbcc3d13ef2dc151b85dced5a83da705e
|
Provenance
The following attestation bundles were made for starlive-0.2.0-py3-none-any.whl:
Publisher:
release.yml on PsiACE/starlive
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
starlive-0.2.0-py3-none-any.whl -
Subject digest:
9b6995f2c8da3e0189b9d03ac33750b0ffb617d014bfebb6656167f08352fe70 - Sigstore transparency entry: 226948867
- Sigstore integration time:
-
Permalink:
PsiACE/starlive@590540cbcb30f1ec54d4993638fb597028d647e9 -
Branch / Tag:
refs/tags/0.2.0 - Owner: https://github.com/PsiACE
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@590540cbcb30f1ec54d4993638fb597028d647e9 -
Trigger Event:
push
-
Statement type:
