tachyon-api 0.9.0__py3-none-any.whl

tachyon_api/testing.py

@@ -0,0 +1,110 @@
+"""
+Tachyon Testing Utilities
+
+Provides test clients and utilities for testing Tachyon applications.
+"""
+
+from typing import Optional
+from starlette.testclient import TestClient
+from httpx import AsyncClient, ASGITransport
+
+
+class TachyonTestClient(TestClient):
+    """
+    Synchronous test client for Tachyon applications.
+
+    A wrapper around Starlette's TestClient that provides a convenient
+    interface for testing Tachyon applications.
+
+    Example:
+        from tachyon_api.testing import TachyonTestClient
+
+        def test_hello():
+            app = Tachyon()
+
+            @app.get("/hello")
+            def hello():
+                return {"message": "Hello!"}
+
+            client = TachyonTestClient(app)
+            response = client.get("/hello")
+            assert response.status_code == 200
+            assert response.json() == {"message": "Hello!"}
+
+    Note:
+        For async testing, use AsyncTachyonTestClient instead.
+    """
+
+    def __init__(
+        self,
+        app,
+        base_url: str = "http://test",
+        raise_server_exceptions: bool = True,
+        **kwargs,
+    ):
+        """
+        Initialize the test client.
+
+        Args:
+            app: The Tachyon application instance
+            base_url: Base URL for requests (default: "http://test")
+            raise_server_exceptions: Whether to raise exceptions from the app
+            **kwargs: Additional arguments passed to TestClient
+        """
+        super().__init__(
+            app,
+            base_url=base_url,
+            raise_server_exceptions=raise_server_exceptions,
+            **kwargs,
+        )
+
+
+class AsyncTachyonTestClient:
+    """
+    Async test client for Tachyon applications.
+
+    Wraps httpx.AsyncClient with ASGITransport for async testing.
+
+    Example:
+        from tachyon_api.testing import AsyncTachyonTestClient
+
+        @pytest.mark.asyncio
+        async def test_hello():
+            app = Tachyon()
+
+            @app.get("/hello")
+            async def hello():
+                return {"message": "Hello!"}
+
+            async with AsyncTachyonTestClient(app) as client:
+                response = await client.get("/hello")
+                assert response.status_code == 200
+    """
+
+    def __init__(self, app, base_url: str = "http://test", **kwargs):
+        """
+        Initialize the async test client.
+
+        Args:
+            app: The Tachyon application instance
+            base_url: Base URL for requests (default: "http://test")
+            **kwargs: Additional arguments passed to AsyncClient
+        """
+        self._app = app
+        self._base_url = base_url
+        self._kwargs = kwargs
+        self._client: Optional[AsyncClient] = None
+
+    async def __aenter__(self) -> AsyncClient:
+        """Enter async context manager."""
+        self._client = AsyncClient(
+            transport=ASGITransport(app=self._app),
+            base_url=self._base_url,
+            **self._kwargs,
+        )
+        return self._client
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Exit async context manager."""
+        if self._client:
+            await self._client.aclose()

tachyon_api/utils/__init__.py

@@ -0,0 +1,15 @@
+"""
+Tachyon API - Utilities Module
+
+This package contains utility functions and classes that provide common functionality
+across the Tachyon framework, including type conversion, validation, and helper functions.
+"""
+
+from .type_utils import TypeUtils, OPENAPI_TYPE_MAP
+from .type_converter import TypeConverter
+
+__all__ = [
+    "TypeUtils",
+    "TypeConverter",
+    "OPENAPI_TYPE_MAP",
+]

tachyon_api/utils/type_converter.py

@@ -0,0 +1,113 @@
+"""
+Tachyon API - Type Converter
+
+This module provides functionality for converting string values to appropriate Python types
+with proper error handling. Used primarily for converting URL parameters and query strings
+to typed values expected by endpoint functions.
+"""
+
+from typing import Type, Union, Any
+from starlette.responses import JSONResponse
+
+from ..responses import validation_error_response
+from .type_utils import TypeUtils
+
+
+class TypeConverter:
+    """
+    Handles conversion of string values to target Python types.
+
+    This class provides methods to convert string representations of values
+    (typically from URL parameters or query strings) to their appropriate
+    Python types with comprehensive error handling.
+    """
+
+    @staticmethod
+    def convert_value(
+        value_str: str,
+        target_type: Type,
+        param_name: str,
+        is_path_param: bool = False,
+    ) -> Union[Any, JSONResponse]:
+        """
+        Convert a string value to the target type with appropriate error handling.
+
+        This method handles type conversion for query and path parameters,
+        including special handling for boolean values and proper error responses.
+
+        Args:
+            value_str: The string value to convert
+            target_type: The target Python type to convert to
+            param_name: Name of the parameter (for error messages)
+            is_path_param: Whether this is a path parameter (affects error response)
+
+        Returns:
+            The converted value, or a JSONResponse with appropriate error code
+
+        Note:
+            - Boolean conversion accepts: "true", "1", "t", "yes" (case-insensitive)
+            - Path parameter errors return 404, query parameter errors return 422
+
+        Examples:
+            >>> TypeConverter.convert_value("123", int, "limit")
+            123
+            >>> TypeConverter.convert_value("true", bool, "active")
+            True
+            >>> TypeConverter.convert_value("invalid", int, "limit")
+            JSONResponse({"success": False, "error": "Invalid value for integer conversion", ...})
+        """
+        # Unwrap Optional/Union[T, None]
+        target_type, _ = TypeUtils.unwrap_optional(target_type)
+
+        try:
+            if target_type is bool:
+                return value_str.lower() in ("true", "1", "t", "yes")
+            elif target_type is not str:
+                return target_type(value_str)
+            else:
+                return value_str
+        except (ValueError, TypeError):
+            if is_path_param:
+                return JSONResponse({"detail": "Not Found"}, status_code=404)
+            else:
+                type_name = TypeUtils.get_type_name(target_type)
+                return validation_error_response(
+                    f"Invalid value for {type_name} conversion"
+                )
+
+    @staticmethod
+    def convert_list_values(
+        values: list[str], item_type: Type, param_name: str, is_path_param: bool = False
+    ) -> Union[list[Any], JSONResponse]:
+        """
+        Convert a list of string values to the target item type.
+
+        Args:
+            values: List of string values to convert
+            item_type: Target type for each item
+            param_name: Parameter name for error messages
+            is_path_param: Whether this is a path parameter
+
+        Returns:
+            List of converted values or error response
+        """
+        base_item_type, item_is_optional = TypeUtils.unwrap_optional(item_type)
+        converted_list = []
+
+        for value_str in values:
+            # Handle null/empty values for optional items
+            if item_is_optional and (value_str == "" or value_str.lower() == "null"):
+                converted_list.append(None)
+                continue
+
+            converted_value = TypeConverter.convert_value(
+                value_str, base_item_type, param_name, is_path_param
+            )
+
+            # If conversion failed, return the error response
+            if isinstance(converted_value, JSONResponse):
+                return converted_value
+
+            converted_list.append(converted_value)
+
+        return converted_list

tachyon_api/utils/type_utils.py

@@ -0,0 +1,162 @@
+"""
+Tachyon API - Type Utilities
+
+This module provides utility functions for working with Python types,
+particularly for handling Optional types, Union types, and generic types
+used throughout the Tachyon framework.
+
+This is the centralized module for all type-related utilities to avoid
+code duplication across the framework.
+"""
+
+import typing
+from typing import Type, Tuple, Union, Dict, Any
+
+
+# Centralized type mapping from Python types to OpenAPI schema types
+# Used by openapi.py and app.py for schema generation
+OPENAPI_TYPE_MAP: Dict[Type, str] = {
+    int: "integer",
+    str: "string",
+    bool: "boolean",
+    float: "number",
+}
+
+
+class TypeUtils:
+    """
+    Utility class for type inspection and manipulation.
+
+    Provides static methods to analyze Python type annotations,
+    particularly useful for handling Optional[T], Union types,
+    and generic types in parameter processing.
+    """
+
+    @staticmethod
+    def unwrap_optional(python_type: Type) -> Tuple[Type, bool]:
+        """
+        Unwrap Optional[T] types to get the inner type and optionality flag.
+
+        This method analyzes a type annotation and determines if it represents
+        an Optional type (Union[T, None]). It returns the inner type and a
+        boolean indicating whether the type is optional.
+
+        Args:
+            python_type: The type annotation to analyze
+
+        Returns:
+            Tuple containing:
+            - inner_type: The unwrapped type (T from Optional[T])
+            - is_optional: Boolean indicating if the type was Optional
+
+        Examples:
+            >>> TypeUtils.unwrap_optional(Optional[str])
+            (str, True)
+            >>> TypeUtils.unwrap_optional(str)
+            (str, False)
+            >>> TypeUtils.unwrap_optional(Union[int, None])
+            (int, True)
+        """
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+
+        if origin is Union and args:
+            non_none = [a for a in args if a is not type(None)]  # noqa: E721
+            if len(non_none) == 1:
+                return non_none[0], True
+
+        return python_type, False
+
+    @staticmethod
+    def is_list_type(python_type: Type) -> Tuple[bool, Type]:
+        """
+        Check if a type is a List type and extract the item type.
+
+        Args:
+            python_type: The type annotation to check
+
+        Returns:
+            Tuple containing:
+            - is_list: Boolean indicating if the type is a List
+            - item_type: The type of list items (str if not a list or no args)
+
+        Examples:
+            >>> TypeUtils.is_list_type(List[str])
+            (True, str)
+            >>> TypeUtils.is_list_type(str)
+            (False, str)
+        """
+        origin = typing.get_origin(python_type)
+        args = typing.get_args(python_type)
+
+        if origin in (list, typing.List):
+            item_type = args[0] if args else str
+            return True, item_type
+
+        return False, str
+
+    @staticmethod
+    def get_type_name(python_type: Type) -> str:
+        """
+        Get a human-readable name for a type.
+
+        Args:
+            python_type: The type to get the name for
+
+        Returns:
+            Human-readable type name
+
+        Examples:
+            >>> TypeUtils.get_type_name(int)
+            'integer'
+            >>> TypeUtils.get_type_name(str)
+            'string'
+        """
+        return OPENAPI_TYPE_MAP.get(
+            python_type, getattr(python_type, "__name__", str(python_type))
+        )
+
+    @staticmethod
+    def get_openapi_type(python_type: Type) -> str:
+        """
+        Convert Python type to OpenAPI schema type string.
+
+        Args:
+            python_type: The Python type to convert
+
+        Returns:
+            OpenAPI type string ('integer', 'string', 'boolean', 'number')
+
+        Examples:
+            >>> TypeUtils.get_openapi_type(int)
+            'integer'
+            >>> TypeUtils.get_openapi_type(str)
+            'string'
+        """
+        return OPENAPI_TYPE_MAP.get(python_type, "string")
+
+    @staticmethod
+    def get_origin(python_type: Type) -> Any:
+        """
+        Get the origin of a generic type (wrapper for typing.get_origin).
+
+        Args:
+            python_type: The type to get the origin for
+
+        Returns:
+            The origin type or None
+        """
+        return typing.get_origin(python_type)
+
+    @staticmethod
+    def get_args(python_type: Type) -> Tuple:
+        """
+        Get the arguments of a generic type (wrapper for typing.get_args).
+
+        Args:
+            python_type: The type to get the arguments for
+
+        Returns:
+            Tuple of type arguments
+        """
+        return typing.get_args(python_type)

tachyon_api-0.9.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: tachyon-api
+Version: 0.9.0
+Summary: A lightweight, FastAPI-inspired web framework
+License: GPL-3.0-or-later
+License-File: LICENSE
+Author: Juan Manuel Panozzo Zénere
+Author-email: jm.panozzozenere@gmail.com
+Requires-Python: >=3.9,<3.14
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: python-multipart (>=0.0.20,<0.0.21)
+Requires-Dist: ruff (==0.14.9)
+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.9.0-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)
+![Tests](https://img.shields.io/badge/tests-235%20passed-brightgreen.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.
+
+## 🚀 Quick Start
+
+```python
+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}
+```
+
+```bash
+pip install tachyon-api
+uvicorn app:app --reload
+```
+
+📖 **Docs:** http://localhost:8000/docs
+
+---
+
+## ✨ Features
+
+| Category | Features |
+|----------|----------|
+| **Core** | Decorators API, Routers, Middlewares, ASGI compatible |
+| **Parameters** | Path, Query, Body, Header, Cookie, Form, File |
+| **Validation** | msgspec Struct (ultra-fast), automatic 422 errors |
+| **DI** | `@injectable` (implicit), `Depends()` (explicit) |
+| **Security** | HTTPBearer, HTTPBasic, OAuth2, API Keys |
+| **Async** | Background Tasks, WebSockets |
+| **Performance** | orjson serialization, @cache decorator |
+| **Docs** | OpenAPI 3.0, Scalar UI, Swagger, ReDoc |
+| **CLI** | Project scaffolding, code generation, linting |
+| **Testing** | TachyonTestClient, dependency_overrides |
+
+---
+
+## 📚 Documentation
+
+Complete documentation is available in the [`docs/`](./docs/) folder:
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/01-getting-started.md) | Installation and first project |
+| [Architecture](./docs/02-architecture.md) | Clean architecture patterns |
+| [Dependency Injection](./docs/03-dependency-injection.md) | `@injectable` and `Depends()` |
+| [Parameters](./docs/04-parameters.md) | Path, Query, Body, Header, Cookie, Form, File |
+| [Validation](./docs/05-validation.md) | msgspec Struct validation |
+| [Security](./docs/06-security.md) | JWT, Basic, OAuth2, API Keys |
+| [Caching](./docs/07-caching.md) | `@cache` decorator |
+| [Lifecycle Events](./docs/08-lifecycle.md) | Startup/Shutdown |
+| [Background Tasks](./docs/09-background-tasks.md) | Async task processing |
+| [WebSockets](./docs/10-websockets.md) | Real-time communication |
+| [Testing](./docs/11-testing.md) | TachyonTestClient |
+| [CLI Tools](./docs/12-cli.md) | Scaffolding and generation |
+| [Request Lifecycle](./docs/13-request-lifecycle.md) | How requests are processed |
+| [Migration from FastAPI](./docs/14-migration-fastapi.md) | Migration guide |
+| [Best Practices](./docs/15-best-practices.md) | Recommended patterns |
+
+---
+
+## 🏦 Example: KYC Demo API
+
+A complete example demonstrating all Tachyon features is available in [`example/`](./example/):
+
+```bash
+cd example
+pip install -r requirements.txt
+uvicorn example.app:app --reload
+```
+
+The KYC Demo implements:
+- 🔐 JWT Authentication
+- 👤 Customer CRUD
+- 📋 KYC Verification with Background Tasks
+- 📁 Document Uploads
+- 🌐 WebSocket Notifications
+- 🧪 12 Tests with Mocks
+
+**Demo credentials:** `demo@example.com` / `demo123`
+
+👉 See [example/README.md](./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 |
+
+---
+
+## 💉 Dependency Injection
+
+```python
+from tachyon_api import injectable, Depends
+
+@injectable
+class UserService:
+    def get_user(self, id: str):
+        return {"id": id}
+
+@app.get("/users/{id}")
+def get_user(id: str, service: UserService = Depends()):
+    return service.get_user(id)
+```
+
+👉 [Full DI documentation](./docs/03-dependency-injection.md)
+
+---
+
+## 🔐 Security
+
+```python
+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](./docs/06-security.md)
+
+---
+
+## ⚡ Background Tasks
+
+```python
+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](./docs/09-background-tasks.md)
+
+---
+
+## 🌐 WebSockets
+
+```python
+@app.websocket("/ws")
+async def websocket(ws):
+    await ws.accept()
+    data = await ws.receive_text()
+    await ws.send_text(f"Echo: {data}")
+```
+
+👉 [Full WebSockets documentation](./docs/10-websockets.md)
+
+---
+
+## 🔧 CLI Tools
+
+```bash
+# Create new project
+tachyon new my-api
+
+# Generate module
+tachyon generate service users --crud
+
+# Code quality
+tachyon lint all
+```
+
+👉 [Full CLI documentation](./docs/12-cli.md)
+
+---
+
+## 🧪 Testing
+
+```python
+from tachyon_api.testing import TachyonTestClient
+
+def test_hello():
+    client = TachyonTestClient(app)
+    response = client.get("/")
+    assert response.status_code == 200
+```
+
+```bash
+pytest tests/ -v
+```
+
+👉 [Full Testing documentation](./docs/11-testing.md)
+
+---
+
+## 📊 Why Tachyon?
+
+| Feature | Tachyon | FastAPI |
+|---------|---------|---------|
+| **Serialization** | msgspec + orjson | pydantic |
+| **Performance** | ⚡⚡⚡ Ultra-fast | ⚡ Fast |
+| **Bundle Size** | Minimal | Larger |
+| **Learning Curve** | Easy (FastAPI-like) | Easy |
+| **Type Safety** | Full | Full |
+
+---
+
+## 📝 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/ -v`)
+4. Commit your changes (`git commit -m 'Add some amazing feature'`)
+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](LICENSE) file for details.
+
+---
+
+## 🔮 What's Next
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+Upcoming features:
+- Response streaming
+- GraphQL support
+- More deployment guides
+- Performance benchmarks
+
+---
+
+*Built with 💜 by developers, for developers*
+