🚀 Tachyon API
A lightweight, high-performance API framework for Python with the elegance of FastAPI and the speed of light.
Tachyon API combines decorator-based routing, msgspec validation, and ASGI integration on Starlette. Endpoint metadata is prepared at registration to reduce request-time introspection.
1.4.0 is validated through the local release process. Native wheels are built and tested on macOS ARM64; the portable wheel supplies the Python fallback for platforms without a matching native wheel. Other operating systems are not validated by the local Mac runs.
The 1.4 migration guide describes execution, body limits, resource lifetime, schema support and packaging changes.
🚀 Quick Start
from tachyon_api import Tachyon, Struct, Body, Query
app = Tachyon()
class User(Struct):
name: str
email: str
@app.get("/")
def hello():
return {"message": "Tachyon is running at lightspeed!"}
@app.post("/users")
def create_user(user: User = Body()):
return {"created": user.name}
@app.get("/search")
def search(q: str = Query(...), limit: int = Query(10)):
return {"query": q, "limit": limit}
pip install tachyon-api
# Testing helpers: pip install "tachyon-api[test]"
tachyon run # uvloop + httptools + reload, served at :8000
📖 Docs: http://localhost:8000/docs
⚡ Performance and builds
Tachyon precompiles endpoint metadata and provides optional native Cython
extensions. Performance depends on the application, workload, and deployment.
Benchmarks must compare equivalent handler execution and dependency scopes. See
benchmark/ for the benchmark harness and its limitations.
The planned native wheel matrix targets CPython 3.10–3.13 on Linux x86_64/aarch64, macOS arm64, and Windows AMD64. On other platforms pip builds from source, requiring a C compiler. Compilation errors fail the build explicitly. For a portable pure Python installation from source:
TACHYON_SKIP_CYTHON=1 pip install --no-binary=tachyon-api tachyon-api
The environment variable controls builds; it does not disable native modules
already installed. [fast] supplies Cython for development; isolated source
builds already install Cython as a build dependency. See the
Cython build guide.
✨ Features
| Category | Features |
|---|---|
| Core | Decorators API, Routers, Middlewares, ASGI compatible |
| Parameters | Path, Query, Body (items: list[Model] = Body()), Header, Cookie, Form, File; alias= only on Header/Cookie/Form/File |
| Validation | msgspec Struct (ultra-fast), automatic 422 errors, configurable body size limit (default 2 MiB) |
| DI | @injectable (3 scopes: singleton / request / transient), Depends() (sync + async), circular dep detection |
| Security | HTTPBearer, HTTPBasic, OAuth2, API Keys (Header / Query / Cookie), SecurityHeadersMiddleware (X-Frame-Options, CSP, HSTS, …) |
| Async | Background Tasks (failures logged, not silenced), WebSockets with typed path params + DI |
| Performance | orjson serialization, @cache decorator, endpoint pre-compilation, optional Cython extensions |
| Docs | OpenAPI 3.0 (incl. List[Struct] arrays + multipart/form-data), Scalar UI, Swagger, ReDoc (XSS-safe HTML generation) |
| CLI | Project scaffolding, code generation, linting, AI-agent skill installer |
| Testing | TachyonTestClient (sync), create_client() (async, full httpx kwargs), dependency_overrides |
| Architecture | Atomic SRP modules across app/, processing/, responses/, openapi/, security/ — optional native modules for the hot path |
📚 Documentation
| Guide | Description |
|---|---|
| Getting Started | Installation and first project |
| Architecture | Clean architecture patterns |
| Dependency Injection | @injectable and Depends() |
| Parameters | Path, Query, Body, Header, Cookie, Form, File |
| Validation | msgspec Struct validation |
| Security | JWT, Basic, OAuth2, API Keys |
| Caching | @cache decorator |
| Lifecycle Events | Startup/Shutdown |
| Background Tasks | Async task processing |
| WebSockets | Real-time communication |
| Testing | TachyonTestClient |
| CLI Tools | Scaffolding and generation |
| Request Lifecycle | How requests are processed |
| Migration from FastAPI | Migration guide |
| Best Practices | Recommended patterns |
| Cython Build | Precompiled wheels, source builds, and the .py/.pyx fallback model |
🏦 Example: KYC Demo API
An example demonstrating selected Tachyon features is available in example/:
# From the repository root
pip install -r example/requirements.txt
tachyon run example.app:app
The KYC Demo exercises:
- 🔐 JWT Authentication + API Keys
- 👤 Customer CRUD and list response models
- 📋 KYC Verification with Background Tasks
- 🌐 Customer notification WebSocket with a string customer ID
- 💉 DI scopes —
singletonservices andrequestcorrelation context - 🛡️ Security headers + opt-in CORS allow-list
- 🚨 Custom exception handler for the
KYCExceptionhierarchy - 🧪 HTTP, async-client, WebSocket and lifespan tests (
pytest example/tests/)
Demo credentials: demo@example.com / demo123
👉 See example/README.md for full details.
🔌 Core Dependencies
| Package | Purpose |
|---|---|
starlette |
ASGI framework |
msgspec |
Ultra-fast validation/serialization |
orjson |
High-performance JSON |
uvicorn |
ASGI server |
🏛️ Architecture
The normal HTTP request path is composed from these collaborators:
Tachyon.__call__ → ASGIEntry → MiddlewareStack → TachyonDispatcher
→ route guards → ParameterProcessor → DependencyResolver
→ ResponseProcessor → request-owned ASGI response messages
WebSocket and lifespan scopes delegate to Starlette. HTTPDispatcher supports
the Starlette compatibility flow. Registration prepares signatures, converters
and decoders. Trie matching prefers complete static matches and may explore
alternative branches when a static prefix reaches a dead end. Error responses
are created per call; immutable payload bytes and bounded header tables may be
shared. Response messages and mutable headers belong to each send.
The hot path has Python implementations with optional native Cython siblings. Python prefers native modules when installed. See the build guide for explicit pure Python builds.
👉 Full architecture documentation
💉 Dependency Injection
from tachyon_api import injectable, Depends
@injectable # singleton (default) — one per app
class DB:
def __init__(self):
self.pool = "..."
@injectable(scope="request") # one per HTTP request
class RequestContext:
def __init__(self):
import uuid
self.correlation_id = str(uuid.uuid4())
@injectable(scope="transient") # new instance every time it's injected
class IdGenerator:
def __init__(self):
self._seq = 0
@app.get("/users/{id}")
def get_user(id: str, db: DB = Depends(), ctx: RequestContext = Depends()):
return {"id": id, "trace": ctx.correlation_id}
🔐 Security
from tachyon_api.security import HTTPBearer, OAuth2PasswordBearer
bearer = HTTPBearer()
@app.get("/protected")
async def protected(credentials = Depends(bearer)):
return {"token": credentials.credentials}
⚡ Background Tasks
from tachyon_api.background import BackgroundTasks
@app.post("/notify")
def notify(background_tasks: BackgroundTasks):
background_tasks.add_task(send_email, "user@example.com")
return {"status": "queued"}
👉 Full Background Tasks documentation
🌐 WebSockets
import uuid
from tachyon_api import injectable, Depends
@injectable
class RoomBroadcaster:
async def join(self, ws, room_key: str): ...
@app.websocket("/ws/rooms/{room_id}") # typed UUID path param
async def room(
websocket,
room_id: uuid.UUID, # auto-converted; 1008 on mismatch
broadcaster: RoomBroadcaster = Depends(), # @injectable DI in WS
):
await broadcaster.join(websocket, str(room_id))
while True:
await websocket.send_json({"room": str(room_id)})
👉 Full WebSockets documentation
🔧 CLI Tools
# Create project (generates .env.example, config.py with dotenv, clean arch)
tachyon new my-api
# Start development server (uvloop + httptools auto-detected, reload on)
tachyon run
# List all registered routes
tachyon routes
# Generate a full CRUD module
tachyon g service user --crud
# Generate an ASGI middleware skeleton
tachyon g middleware auth
# Code quality
tachyon lint all
Name validation: hyphens auto-converted to underscores (my-api → my_api), Python keywords rejected with a clear error.
AI Agent Integration
Teach your AI coding assistant (Claude Code, Cursor, Copilot, OpenCode, Codex) how to write correct Tachyon code:
tachyon install-skill # generates context files for all tools
tachyon install-skill --cursor # only .cursorrules
tachyon install-skill --claude # only CLAUDE.md
tachyon install-skill --copilot # only .github/copilot-instructions.md
Installs knowledge about Body() requirement, Struct vs BaseModel, DI patterns, CLI commands, and anti-patterns. Safe to run multiple times.
🧪 Testing
# Sync — Starlette TestClient compatible
from tachyon_api.testing import TachyonTestClient
def test_hello():
client = TachyonTestClient(app)
assert client.get("/").status_code == 200
# Async — httpx.AsyncClient over ASGI transport
import pytest
from tachyon_api.testing import create_client
@pytest.mark.asyncio
async def test_hello_async():
async with create_client(app, headers={"X-Trace": "abc"}) as client:
response = await client.get("/")
assert response.status_code == 200
pytest tests/ example/tests/ -v
📝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
pytest tests/ example/tests/ -v) - Commit your changes
- Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📜 License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
🔮 What's Next
See CHANGELOG.md for version history.
Upcoming:
- A dedicated streaming API; Starlette
StreamingResponsealready passes through the ASGI response path - GraphQL support
- Multi-worker benchmarks
- Benchmark suite vs Litestar / BlackSheep / Robyn
- SQLAlchemy async integration guide
Built with 💜 by developers, for developers
Metadata
Release files for tachyon-api 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tachyon_api-1.4.0.tar.gz | 153.9 kB | Without provenance | Details for tachyon_api-1.4.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| tachyon_api-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for tachyon_api-1.4.0-py3-none-any.whl |
| tachyon_api-1.4.0-cp313-cp313-macosx_11_0_arm64.whl | CPython 3.13 | CPython 3.13 | macOS 11.0+ ARM64 | Details for tachyon_api-1.4.0-cp313-cp313-macosx_11_0_arm64.whl |
| tachyon_api-1.4.0-cp312-cp312-macosx_11_0_arm64.whl | CPython 3.12 | CPython 3.12 | macOS 11.0+ ARM64 | Details for tachyon_api-1.4.0-cp312-cp312-macosx_11_0_arm64.whl |
| tachyon_api-1.4.0-cp311-cp311-macosx_11_0_arm64.whl | CPython 3.11 | CPython 3.11 | macOS 11.0+ ARM64 | Details for tachyon_api-1.4.0-cp311-cp311-macosx_11_0_arm64.whl |
| tachyon_api-1.4.0-cp310-cp310-macosx_11_0_arm64.whl | CPython 3.10 | CPython 3.10 | macOS 11.0+ ARM64 | Details for tachyon_api-1.4.0-cp310-cp310-macosx_11_0_arm64.whl |
Total release size: 4.4 MB
Release files / tachyon_api-1.4.0.tar.gz
| Download URL | tachyon_api-1.4.0.tar.gz |
|---|---|
| Size | 153.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f07035a2e348990be4e6260767bb3a27d56bc8c01c8a8e56de042cc5e14d4930
|
|
BLAKE2b-256 checksum How to use checksums |
4a080fd411192baa7cb08eb050e7788db3f3952498228204a99f68c8c9383bb6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tachyon_api-1.4.0-py3-none-any.whl
| Download URL | tachyon_api-1.4.0-py3-none-any.whl |
|---|---|
| Size | 110.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d689e5ed70d87d3265e97bf6da8606ae67552087a022340988ade38037fab8b
|
|
BLAKE2b-256 checksum How to use checksums |
b83c283c206d42c48da8c04e0549d2de5cdb30e0f3fb968626b81e089fa9b444
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tachyon_api-1.4.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | tachyon_api-1.4.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
09ef2aa78f1e28049d82a9777ba946e5ac230de2ec3c5e98d6f4b058b39924d4
|
|
BLAKE2b-256 checksum How to use checksums |
518b0c82cc5c78ee05a9c942aab5781ac0fdb9b585110082fa8459adf2993fa2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tachyon_api-1.4.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | tachyon_api-1.4.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
af623681b224c987cf64bab74f9c2cf40302124a6863f22d45d0e3b0dac75d34
|
|
BLAKE2b-256 checksum How to use checksums |
20c09ce2c2b2627df978e1febf1e6d04f6de94ef9f2a1213d78a040dfec73f0c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tachyon_api-1.4.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | tachyon_api-1.4.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.0 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ba044c9a3a8f3e85de8a6c6f608c7adfbb43845ecb2bb49e9111a1b7c7fe7ec0
|
|
BLAKE2b-256 checksum How to use checksums |
52f9c58846f8cc867b7cfd7fd357eaf08a59f4605d5275d0a88cc929030da247
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tachyon_api-1.4.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | tachyon_api-1.4.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.1 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
aa673b2948f00750e9ed3803762bec52e8807cc3ca7c05fd8d38c45422081d21
|
|
BLAKE2b-256 checksum How to use checksums |
e2fd14ac5604863238176592904c94ea43db9bf0a3ae521e199a4e871e441bc3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for tachyon-api 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.