Minimal Python framework for building static websites with component-style APIs.
Project description
Astris
Astris is a minimal Python framework for building static websites using component-style APIs.
Documentation
- User documentation (for building websites):
docs/user - Internal framework-maintainer documentation:
docs/internal
Installation
pip install astris
Quick start with CLI
Create a new project scaffold:
uvx astris new my-project
cd my-project
uv sync
uv run python main.py
Generated projects use pyproject.toml for dependency management (UV-first), without requirements.txt.
Build static files:
uv run astris build
Deploy to Cloudflare Pages:
uv sync
uv run astris deploy
astris deploy reads deployment settings from pyproject.toml under [tool.astris].
Basic usage
from astris import Astris
from astris.lib import Body, H1, Html
app = Astris()
@app.page("/")
def home():
return Html(children=[
Body(children=[
H1(children=["Hello from Astris"]),
])
])
if __name__ == "__main__":
app.run_dev()
HTML tags API
astris.lib now provides wrappers for the modern standard HTML tag set (A to Z).
Each wrapper class includes an English docstring describing the underlying HTML element.
Void elements (for example Img, Br, Input, Meta) render without closing tags.
Layout helpers (Container, Column, Row) live in astris.layout.
from astris.layout import Container, Column, Row
JSON content collections (read-only)
You can register a folder of .json files as a read-only collection and generate detail pages from a Python template.
from astris import Astris, Text, register_json_collection
from astris.lib import Body, Div, Html
app = Astris()
def post_template(entry: dict):
return Html(children=[
Body(children=[
Div(children=[Text(entry["title"])]),
])
])
posts = register_json_collection(
app,
name="posts",
directory="content/posts",
template=post_template,
api_prefix="/api/content",
)
print(posts.page_links())
Generated output:
- Static detail pages:
/posts/<slug>(built asdist/posts/<slug>.html) - Dev JSON API (read-only):
GET /api/content/postsGET /api/content/posts/<slug>
Deployment configuration (pyproject.toml)
[tool.astris.build]
output_dir = "dist"
clean_urls = true
[tool.astris.deploy]
provider = "cloudflare"
[tool.astris.deploy.cloudflare]
project_name = "your-cloudflare-pages-project"
For full deployment options (CLI deploy and Git-based Cloudflare setup), see docs/user/deployment.md.
Head assets (CDN)
You can register external CSS and JavaScript files that Astris injects into the page <head>.
This works in both run_dev() and build() outputs.
from astris import Astris
app = Astris()
app.add_head_link(
"https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css"
)
app.add_head_script(
"https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"
)
Development
uv sync --group dev
uv pip install -e .
uv run --group dev pytest
Documentation (local)
Build user documentation in strict mode:
make docs
Serve user documentation with live reload:
make docs-serve
Continuous Integration
GitHub Actions runs tests on push and pull request events targeting main using Python 3.11, 3.12, and 3.13.
The workflow is defined in .github/workflows/tests.yml.
Release checklist
make release-check
Equivalent manual commands:
uv sync --group dev
uv run --group dev pytest
uv run --group dev python -m build
uv run --group dev twine check dist/*.whl dist/*.tar.gz
example.py in this repository is an internal framework demo and not the standard end-user workflow.
Agent skill: release-prep-astris
This repository includes a workspace skill at .agent/skills/release-prep-astris.
Use this skill when preparing a new Astris version and you want a repeatable release-prep workflow that covers:
- Version alignment across project metadata.
- Changelog and internal release notes updates.
- Local validation checks (
pytest,pyright,release-check).
By default, this skill prepares the repository for release but does not publish artifacts to TestPyPI or PyPI unless explicitly requested.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
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
File details
Details for the file astris-0.1.4.tar.gz.
File metadata
- Download URL: astris-0.1.4.tar.gz
- Upload date:
- Size: 24.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
524507d309924d98de8dbc9b8efe5d4ab34485b52d92b3d686a99f3a03647fa7
|
|
| MD5 |
64a78c3f5b5be36a9b45312dea06cb17
|
|
| BLAKE2b-256 |
96dcd6d19fe34a6d086a14ff9e1b23bd9369cfb143122482bd8a989f9fcaab6e
|
File details
Details for the file astris-0.1.4-py3-none-any.whl.
File metadata
- Download URL: astris-0.1.4-py3-none-any.whl
- Upload date:
- Size: 19.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
77d5e4ffa34816bbecb798c583bad8b9697151f7abce203e5a0d2054ed9964ca
|
|
| MD5 |
a1be69408e38d9ad318dc3ca64a943a7
|
|
| BLAKE2b-256 |
5a6b90225906d814fdb6c5ca363f49a42d8540bb1c9bd04a200a4bb42afb41d4
|
