Metadata-Version: 2.3
Name: tachyon-api
Version: 0.5.5
Summary: A lightweight, FastAPI-inspired web framework
License: GPL-3.0-or-later
Author: Juan Manuel Panozzo Zénere
Author-email: jm.panozzozenere@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: msgspec (>=0.19.0,<0.20.0)
Requires-Dist: orjson (>=3.11.1,<4.0.0)
Requires-Dist: ruff (>=0.12.7,<0.13.0)
Requires-Dist: starlette (>=0.47.2,<0.48.0)
Requires-Dist: typer (>=0.16.0,<0.17.0)
Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
Description-Content-Type: text/markdown

# 🚀 Tachyon API

![Version](https://img.shields.io/badge/version-0.5.5-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-brightgreen.svg)
![License](https://img.shields.io/badge/license-GPL--3.0-orange.svg)
![Status](https://img.shields.io/badge/status-stable-brightgreen.svg)

**A lightweight, high-performance API framework for Python with the elegance of FastAPI and the speed of light.**

Tachyon API combines the intuitive decorator-based syntax you love with minimal dependencies and maximal performance. Built with Test-Driven Development from the ground up, it offers a cleaner, faster alternative with full ASGI compatibility.

```python
from tachyon_api import Tachyon
from tachyon_api.models import Struct

app = Tachyon()

class User(Struct):
    name: str
    age: int

@app.get("/")
def hello_world():
    return {"message": "Tachyon is running at lightspeed!"}

@app.post("/users")
def create_user(user: User):
    return {"created": user.name}
```

## ✨ Features

- 🔍 **Intuitive API** - Elegant decorator-based routing inspired by FastAPI
- 🧩 **Implicit & Explicit Dependency Injection** - Both supported for maximum flexibility
- 📚 **Automatic OpenAPI Documentation** - With Scalar UI, Swagger UI, and ReDoc support
- 🛠️ **Router System** - Organize your API endpoints with powerful route grouping
- 🧪 **Built with TDD** - Comprehensive test suite ensures stability and correctness
- 🔄 **Middleware Support** - Both class-based and decorator-based approaches
- 🚀 **High-Performance JSON** - Powered by msgspec and orjson for lightning-fast processing
- 🪶 **Minimal Dependencies** - Lean core with only what you really need

## 📦 Installation

Tachyon API is currently in beta. The package will be available on PyPI and Poetry repositories soon!

### From source (Currently the only method)

```bash
git clone https://github.com/jmpanozzoz/tachyon_api.git
cd tachyon-api
pip install -r requirements.txt
```

> **Note:** The `pip install tachyon-api` and `poetry add tachyon-api` commands will be available once the package is published to PyPI.

## 🔍 Key Differences from FastAPI

While inspired by FastAPI's elegant API design, Tachyon API takes a different approach in several key areas:

| Feature | Tachyon API | FastAPI |
|---------|------------|---------|
| **Core Dependencies** | Minimalist: Starlette + msgspec + orjson | Pydantic + multiple dependencies |
| **Validation Engine** | msgspec (faster, lighter) | Pydantic (more features, heavier) |
| **Dependency Injection** | Both implicit and explicit | Primarily explicit |
| **Middleware Approach** | Dual API (class + decorator) | Class-based |
| **Development Approach** | Test-Driven from the start | Feature-driven |
| **Documentation UI** | Scalar UI (default), Swagger, ReDoc | Swagger UI (default), ReDoc |
| **Size** | Lightweight, focused | Comprehensive, full-featured |

## 🧪 Test-Driven Development

Tachyon API is built with TDD principles at its core:

- Every feature starts with a test
- Comprehensive test coverage
- Self-contained test architecture
- Clear test documentation

This ensures stability, maintainability, and prevents regressions as the framework evolves.

## 🔌 Core Dependencies

Tachyon API maintains a minimal, carefully selected set of dependencies:

- **[Starlette](https://www.starlette.io/)**: ASGI framework providing solid foundations
- **[msgspec](https://jcristharif.com/msgspec/)**: Ultra-fast serialization and validation
- **[orjson](https://github.com/ijl/orjson)**: High-performance JSON parser
- **[uvicorn](https://www.uvicorn.org/)**: ASGI server for development and production

These were chosen for their performance, lightweight nature, and focused functionality.

## 💉 Dependency Injection System

Tachyon API offers a flexible dependency injection system:

### Implicit Injection

```python
@injectable
class UserService:
    def __init__(self, repository: UserRepository):  # Auto-injected!
        self.repository = repository

@app.get("/users/{user_id}")
def get_user(user_id: int, service: UserService):  # Auto-injected!
    return service.get_user(user_id)
```

### Explicit Injection

```python
@app.get("/users/{user_id}")
def get_user(user_id: int, service: UserService = Depends()):
    return service.get_user(user_id)
```

## 🔄 Middleware Support

Tachyon API supports middlewares in two elegant ways:

### Class-based Approach

```python
from tachyon_api.middlewares import CORSMiddleware, LoggerMiddleware

# Add built-in CORS middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    allow_credentials=False,
)

# Add built-in Logger middleware
app.add_middleware(
    LoggerMiddleware,
    include_headers=True,
    redact_headers=["authorization"],
)
```

### Decorator-based Approach

```python
@app.middleware()
async def timing_middleware(scope, receive, send, app):
    start_time = time.time()
    await app(scope, receive, send)
    print(f"Request took {time.time() - start_time:.4f}s")
```

### Built-in Middlewares

- CORSMiddleware: Handles preflight requests and injects CORS headers into responses. Highly configurable with allow_origins, allow_methods, allow_headers, allow_credentials, expose_headers, and max_age.
- LoggerMiddleware: Logs request start/end, duration, status code, and optionally headers and a non-intrusive body preview.

Both middlewares are standard ASGI middlewares and can be used with `app.add_middleware(...)`.

## 📚 Example Application

For a complete example showcasing all features, see the [example directory](./example). It demonstrates:

- Clean architecture with models, services, and repositories
- Router organization
- Middleware implementation
- Dependency injection patterns
- OpenAPI documentation

Built-in CORS and Logger middlewares are integrated in the example for convenience. You can toggle settings in `example/app.py`.

Run the example with:

```bash
cd example
python app.py
```

Then visit:
- **API**: http://localhost:8000/
- **Documentation**: http://localhost:8000/docs

## 📝 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. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📜 License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

## 🔮 Roadmap

- [ ] **Exception System**: Standardized exception handling and error responses
- [ ] **Environment Management**: Built-in environment variable handling and uvicorn integration
- [ ] **CLI Tool**: Project scaffolding and service generation
  - Directory structure generation
  - Service and repository templates
  - API endpoint generation
- [ ] **Code Quality Tools**: Ruff integration for linting and formatting
- [ ] **Performance Optimization**: Cython compilation for service layer via CLI
- [ ] **Authentication Middleware**: Built-in auth patterns and middleware
- [ ] **Performance Benchmarks**: Comparisons against other frameworks
- [ ] **More Example Applications**: Demonstrating different use cases
- [ ] **Plugin System**: Extensibility through plugins
- [ ] **Deployment Guides**: Documentation for various deployment scenarios
- [ ] **And much more!**

---

*Built with 💜 by developers, for developers*

