https://github.com/scriptogre/hyper
https://github.com/scriptogre/hyper
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/scriptogre/hyper
- Owner: scriptogre
- Created: 2025-11-14T13:07:36.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2025-12-20T09:00:29.000Z (6 months ago)
- Last Synced: 2025-12-22T14:47:17.236Z (6 months ago)
- Language: Python
- Size: 312 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Hyper
**A Python-powered static site generator built for speed**
Write static sites with Python 3.14's t-strings. Full Python ecosystem at build time. Zero runtime dependencies.
```python
# app/pages/index.py
t"""
Welcome to Hyper
Hello, Hyper!
Built with Python. Served as static HTML.
"""
```
---
## Key Features
### 🗂️ File-Based Routing
Your file structure **is** your URL structure.
```
app/pages/
index.py → /
about.py → /about
blog/
index.py → /blog
[slug].py → /blog/:slug
```
### 🎨 Native T-String Templates
Python 3.14's t-strings provide type-safe templates with zero learning curve.
```python
# app/pages/team.py
members = get_team_members()
t"""
Our Team
{[t'{member.name} - {member.role}' for member in members]}
"""
```
### 📝 Content Collections
Organize content with Python dataclasses or plain dictionaries.
```python
# app/content/__init__.py
from dataclasses import dataclass
from datetime import date
@dataclass
class Blog:
title: str
slug: str
date: date
class Meta:
path = "app/content/blog/*.md"
blogs: list[Blog]
```
```python
# app/pages/blog/index.py
from app.content import blogs
recent = sorted(blogs, key=lambda b: b.date, reverse=True)[:10]
t"""
Recent Posts
{[t'{post.title}' for post in recent]}
"""
```
### 🎯 Dynamic Routes
Generate pages from content automatically.
```python
# app/pages/blog/[slug].py
from typing import Literal
from app.content import blogs
# Path parameter (injected by framework)
slug: Literal[*[b.slug for b in blogs]]
# ---
post = next(b for b in blogs if b.slug == slug)
t"""
{post.title}
{post.html}
"""
```
### 🚀 The Power of Python
Use any Python library at build time.
```python
# app/pages/stats.py
from app.content import blogs
import pandas as pd
df = pd.DataFrame([{'date': b.date, 'words': len(b.content.split())} for b in blogs])
avg_words = df['words'].mean()
t"""
Blog Statistics
Average: {avg_words:.0f} words per post
"""
```
Need data analysis? Image processing? API calls? Just `pip install` and use it.
### 📄 Markdown Files
Write content in Markdown with frontmatter and Python execution blocks.
```markdown
---
title: "My Post"
date: 2025-01-15
---
# {frontmatter.title}
```python exec
recent_posts = get_recent_posts(5)
```
## Related Posts
{[t'
```
### ⚡ Built for Speed
- Rust CLI for millisecond builds
- Incremental builds
- Instant hot reload
- Single binary distribution
---
## Installation
```bash
# Via uv (recommended):
uvx hyper init myblog
cd myblog
uvx hyper dev
# Or install:
uv tool install hyper
hyper build
```
---
## Documentation
**Core Concepts** (SSG + SSR)
- [Routing](design/routing.md) - File-based routing, dynamic routes
- [Templates](design/templates.md) - t-strings, layouts, components
- [Content](design/content.md) - Content collections, markdown, frontmatter
**SSG-Specific**
- [Static Site Generation](design/ssg.md) - Building static HTML, path generation
**SSR-Specific** *(planned)*
- [Dependency Injection](design/dependency-injection.md) - Type-based injection
- [Forms](design/forms.md) - Form handling
- [Streaming](design/streaming.md) - SSE, streaming responses
- [SSR Patterns](design/ssr-patterns.md) - HTMX, middleware, sessions
**Planning**
- [Architecture](design/architecture.md) - Technical decisions and implementation plan
---
## What Makes Hyper Different?
**Compared to Hugo/Zola/Jekyll:**
- Full Python at build time (not template language)
- Any PyPI package available
- Python dataclasses for content
- Type-safe with IDE autocomplete
**Compared to Astro:**
- Simpler API - no `getStaticPaths()` boilerplate
- Python instead of JavaScript
- More flexible content organization
- Rust CLI for speed
**Compared to Python frameworks:**
- Zero runtime dependencies
- Pure static output
- No server needed
- Deploy anywhere
---
## Philosophy
### Simple Things Simple
```python
# app/content/__init__.py
blogs: list[dict] # That's it. No schema needed.
```
### Powerful When Needed
```python
@dataclass
class Blog:
title: str
date: date
class Meta:
path = "app/content/blog/*.md"
@property
def url(self) -> str:
return f"/blog/{self.slug}"
blogs: list[Blog] # Full validation, IDE autocomplete, type safety
```
---
## Modes
**SSG (Static Site Generation)** - Build static HTML at build time *(current focus)*
**SSR (Server-Side Rendering)** - Render HTML on-demand *(planned)*
Both modes share the same routing, templates, and content features.
## Status
**Current:** Planning & design phase
**Next:** Rust CLI implementation for SSG
See [design/architecture.md](design/architecture.md) for implementation roadmap.
---
## Links
- **Documentation:** [design/](design/)
- **GitHub:** https://github.com/scriptogre/hyper
- **Python 3.14 t-strings:** [PEP 750](https://peps.python.org/pep-0750/)
---
## License
MIT