Skip to main content

🚀 Tachyon API

Version Python License Python

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 — singleton services and request correlation context
  • 🛡️ Security headers + opt-in CORS allow-list
  • 🚨 Custom exception handler for the KYCException hierarchy
  • 🧪 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}

👉 Full DI documentation


🔐 Security

from tachyon_api.security import HTTPBearer, OAuth2PasswordBearer

bearer = HTTPBearer()

@app.get("/protected")
async def protected(credentials = Depends(bearer)):
    return {"token": credentials.credentials}

👉 Full Security documentation


⚡ 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.

👉 Full CLI documentation


🧪 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

👉 Full Testing documentation


📝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Run tests (pytest tests/ example/tests/ -v)
  4. Commit your changes
  5. Push to the branch (git push origin feature/amazing-feature)
  6. 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 StreamingResponse already 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)

Source distribution for tachyon-api 1.4.0
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)

Table of built distributions (wheels) for tachyon-api 1.4.0
File Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page