tachyon-api 0.9.0__py3-none-any.whl

tachyon_api/background.py

@@ -0,0 +1,72 @@
+"""
+Tachyon Background Tasks Module
+
+Provides background task functionality for running tasks after response is sent.
+"""
+
+import asyncio
+from typing import Any, Callable, List, Tuple
+
+
+class BackgroundTasks:
+    """
+    Background tasks that run after the response has been sent.
+
+    Tasks are executed in order after the response is complete.
+    Errors in tasks are caught and logged but don't affect the response.
+
+    Example:
+        @app.get("/send-notification")
+        def send_notification(background_tasks: BackgroundTasks):
+            background_tasks.add_task(send_email, "user@example.com", "Hello!")
+            return {"message": "Notification scheduled"}
+    """
+
+    def __init__(self):
+        self._tasks: List[Tuple[Callable, tuple, dict]] = []
+
+    def add_task(
+        self,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Add a task to be run in the background.
+
+        Args:
+            func: The function to call. Can be sync or async.
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Example:
+            background_tasks.add_task(write_log, "User logged in")
+            background_tasks.add_task(send_email, to="user@example.com", subject="Hi")
+        """
+        self._tasks.append((func, args, kwargs))
+
+    async def run_tasks(self) -> None:
+        """
+        Execute all queued background tasks.
+
+        This method is called automatically after the response is sent.
+        Each task is run in order, and errors are caught to prevent
+        one failing task from stopping the others.
+        """
+        for func, args, kwargs in self._tasks:
+            try:
+                result = func(*args, **kwargs)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                # Log error but continue with other tasks
+                # In production, you'd want proper logging here
+                pass
+
+    def __len__(self) -> int:
+        """Return the number of pending tasks."""
+        return len(self._tasks)
+
+    def __bool__(self) -> bool:
+        """BackgroundTasks is always truthy (to allow `if background_tasks:`)."""
+        return True

tachyon_api/cache.py

@@ -0,0 +1,270 @@
+"""
+Cache utilities: decorator with TTL and pluggable backends.
+
+This module provides:
+- BaseCacheBackend protocol and an in-memory implementation
+- CacheConfig dataclass and helpers to set global/app config
+- cache decorator usable on any sync/async function (including routes)
+
+Design notes:
+- Key builder defaults to a stable representation of function + args/kwargs
+- Unless predicate allows opt-out per-call
+- TTL can be provided per-decorator or falls back to global default
+"""
+
+from __future__ import annotations
+
+import time
+import asyncio
+import hashlib
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, Optional, Tuple
+
+
+class BaseCacheBackend:
+    """Minimal cache backend interface."""
+
+    def get(self, key: str) -> Any:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def set(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def delete(self, key: str) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+    def clear(self) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class InMemoryCacheBackend(BaseCacheBackend):
+    """Simple in-memory cache with TTL using wall-clock time."""
+
+    def __init__(self) -> None:
+        self._store: dict[str, Tuple[float | None, Any]] = {}
+
+    def _is_expired(self, expires_at: float | None) -> bool:
+        return expires_at is not None and time.time() >= expires_at
+
+    def get(self, key: str) -> Any:
+        item = self._store.get(key)
+        if not item:
+            return None
+        expires_at, value = item
+        if self._is_expired(expires_at):
+            # Lazy expiration
+            try:
+                del self._store[key]
+            except KeyError:
+                pass
+            return None
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        expires_at = time.time() + ttl if ttl and ttl > 0 else None
+        self._store[key] = (expires_at, value)
+
+    def delete(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        self._store.clear()
+
+
+@dataclass
+class CacheConfig:
+    backend: BaseCacheBackend
+    default_ttl: float = 60.0
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None
+    enabled: bool = True
+
+
+_cache_config: Optional[CacheConfig] = None
+
+
+def _default_key_builder(func: Callable, args: tuple, kwargs: dict) -> str:
+    parts = [getattr(func, "__module__", ""), getattr(func, "__qualname__", ""), "|"]
+    # Stable kwargs order
+    items = [repr(a) for a in args] + [
+        f"{k}={repr(v)}" for k, v in sorted(kwargs.items())
+    ]
+    raw_key = ":".join(parts + items)
+    return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()
+
+
+def create_cache_config(
+    backend: Optional[BaseCacheBackend] = None,
+    default_ttl: float = 60.0,
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None,
+    enabled: bool = True,
+) -> CacheConfig:
+    """Create and set the global cache configuration.
+
+    Returns the created CacheConfig and sets it as the active global config.
+    """
+    global _cache_config
+    cfg = CacheConfig(
+        backend=backend or InMemoryCacheBackend(),
+        default_ttl=default_ttl,
+        key_builder=key_builder,
+        enabled=enabled,
+    )
+    _cache_config = cfg
+    return cfg
+
+
+def set_cache_config(config: CacheConfig) -> None:
+    """Set the global cache configuration object."""
+    global _cache_config
+    _cache_config = config
+
+
+def get_cache_config() -> CacheConfig:
+    """Get the current cache configuration, creating a default one if missing."""
+    global _cache_config
+    if _cache_config is None:
+        _cache_config = create_cache_config()
+    return _cache_config
+
+
+def cache(
+    TTL: Optional[float] = None,
+    *,
+    key_builder: Optional[Callable[[Callable, tuple, dict], str]] = None,
+    unless: Optional[Callable[[tuple, dict], bool]] = None,
+    backend: Optional[BaseCacheBackend] = None,
+):
+    """Cache decorator with TTL and pluggable backend.
+
+    Args:
+        TTL: Time-to-live in seconds for this decorator instance. Falls back to config.default_ttl.
+        key_builder: Optional custom function to build cache keys.
+        unless: Predicate receiving (args, kwargs). If returns True, skip cache for that call.
+        backend: Optional backend override for this decorator.
+    """
+
+    def decorator(func: Callable):
+        cfg = get_cache_config()
+        be = backend or cfg.backend
+        ttl_value = cfg.default_ttl if TTL is None else TTL
+        kb = (
+            key_builder
+            or cfg.key_builder
+            or (lambda f, a, kw: _default_key_builder(f, a, kw))
+        )
+
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                if not cfg.enabled or (unless and unless(args, kwargs)):
+                    return await func(*args, **kwargs)
+                key = kb(func, args, kwargs)
+                cached = be.get(key)
+                if cached is not None:
+                    return cached
+                result = await func(*args, **kwargs)
+                try:
+                    be.set(key, result, ttl_value)
+                except Exception:
+                    # Backend errors should not break the app
+                    pass
+                return result
+
+            return async_wrapper
+        else:
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                if not cfg.enabled or (unless and unless(args, kwargs)):
+                    return func(*args, **kwargs)
+                key = kb(func, args, kwargs)
+                cached = be.get(key)
+                if cached is not None:
+                    return cached
+                result = func(*args, **kwargs)
+                try:
+                    be.set(key, result, ttl_value)
+                except Exception:
+                    pass
+                return result
+
+            return wrapper
+
+    return decorator
+
+
+class RedisCacheBackend(BaseCacheBackend):
+    """Adapter backend for Redis-like clients.
+
+    Expects a client with .get(key) -> bytes|str|None and .set(key, value, ex=ttl_seconds).
+    The stored values should be JSON-serializable or pickled externally by the user.
+    """
+
+    def __init__(self, client) -> None:
+        self.client = client
+
+    def get(self, key: str) -> Any:
+        value = self.client.get(key)
+        # Many clients return bytes; decode if possible
+        if isinstance(value, bytes):
+            try:
+                return value.decode("utf-8")
+            except Exception:
+                return value
+        return value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        # Use ex (expire seconds) if available
+        kwargs = {}
+        if ttl and ttl > 0:
+            kwargs["ex"] = int(ttl)
+        # Best effort set
+        self.client.set(key, value, **kwargs)
+
+    def delete(self, key: str) -> None:
+        try:
+            self.client.delete(key)
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        # Not standardized; no-op by default
+        pass
+
+
+class MemcachedCacheBackend(BaseCacheBackend):
+    """Adapter backend for Memcached-like clients.
+
+    Expects a client with .get(key) and .set(key, value, expire=ttl_seconds).
+    """
+
+    def __init__(self, client) -> None:
+        self.client = client
+
+    def get(self, key: str) -> Any:
+        return self.client.get(key)
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        expire = int(ttl) if ttl and ttl > 0 else 0
+        try:
+            # pymemcache: set(key, value, expire=...)
+            self.client.set(key, value, expire=expire)
+        except TypeError:
+            # python-binary-memcached: set(key, value, time=...)
+            self.client.set(key, value, time=expire)
+
+    def delete(self, key: str) -> None:
+        try:
+            self.client.delete(key)
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        try:
+            self.client.flush_all()
+        except Exception:
+            pass

tachyon_api/cli/__init__.py

@@ -0,0 +1,9 @@
+"""
+Tachyon CLI - Command Line Interface
+
+NestJS-style CLI for scaffolding, code generation, and quality tools.
+"""
+
+from .main import app
+
+__all__ = ["app"]

tachyon_api/cli/__main__.py

@@ -0,0 +1,8 @@
+"""
+Entry point for `python -m tachyon_api.cli`
+"""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

tachyon_api/cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI Commands"""
+
+from . import new, generate, openapi, lint
+
+__all__ = ["new", "generate", "openapi", "lint"]

tachyon_api/cli/commands/generate.py

@@ -0,0 +1,190 @@
+"""
+tachyon generate - Generate components (service, controller, repository, dto)
+"""
+
+import typer
+from pathlib import Path
+from typing import Optional
+
+from ..templates import ServiceTemplates
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def _to_class_name(name: str) -> str:
+    """Convert snake_case or kebab-case to PascalCase."""
+    return "".join(word.capitalize() for word in name.replace("-", "_").split("_"))
+
+
+def _to_snake_case(name: str) -> str:
+    """Ensure name is in snake_case."""
+    return name.replace("-", "_").lower()
+
+
+def _create_file(path: Path, content: str, name: str):
+    """Create a file and print status."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    typer.echo(f"  📄 Created {name}")
+
+
+@app.command()
+def service(
+    name: str = typer.Argument(..., help="Service name (e.g., 'auth', 'users')"),
+    path: Optional[Path] = typer.Option(
+        None, "--path", "-p", help="Base path for modules (default: ./modules)"
+    ),
+    no_tests: bool = typer.Option(
+        False, "--no-tests", help="Skip test file generation"
+    ),
+    crud: bool = typer.Option(
+        False, "--crud", help="Generate with basic CRUD operations"
+    ),
+):
+    """
+    🔧 Generate a complete service module.
+
+    Creates: controller, service, repository, dto, and tests.
+
+    Example:
+        tachyon g service auth
+        tachyon g service products --crud
+        tachyon g service users --path src/modules
+    """
+    snake_name = _to_snake_case(name)
+    class_name = _to_class_name(name)
+
+    base_path = path or Path.cwd() / "modules"
+    service_path = base_path / snake_name
+
+    if service_path.exists():
+        typer.secho(f"❌ Module '{snake_name}' already exists!", fg=typer.colors.RED)
+        raise typer.Exit(1)
+
+    typer.echo(f"\n🔧 Generating service: {typer.style(snake_name, bold=True)}\n")
+
+    # Create directory
+    service_path.mkdir(parents=True, exist_ok=True)
+    tests_path = service_path / "tests"
+    tests_path.mkdir(exist_ok=True)
+
+    # Generate files
+    files = {
+        "__init__.py": ServiceTemplates.init(snake_name, class_name),
+        f"{snake_name}_controller.py": ServiceTemplates.controller(
+            snake_name, class_name, crud
+        ),
+        f"{snake_name}_service.py": ServiceTemplates.service(
+            snake_name, class_name, crud
+        ),
+        f"{snake_name}_repository.py": ServiceTemplates.repository(
+            snake_name, class_name, crud
+        ),
+        f"{snake_name}_dto.py": ServiceTemplates.dto(snake_name, class_name, crud),
+    }
+
+    for filename, content in files.items():
+        _create_file(service_path / filename, content, filename)
+
+    # Generate tests
+    if not no_tests:
+        _create_file(tests_path / "__init__.py", "", "tests/__init__.py")
+        _create_file(
+            tests_path / f"test_{snake_name}_service.py",
+            ServiceTemplates.test_service(snake_name, class_name),
+            f"tests/test_{snake_name}_service.py",
+        )
+
+    typer.echo(
+        f"\n✅ Service {typer.style(snake_name, bold=True, fg=typer.colors.GREEN)} generated!"
+    )
+    typer.echo("\n📖 Don't forget to register in app.py:")
+    typer.echo(f"   from modules.{snake_name} import router as {snake_name}_router")
+    typer.echo(f"   app.include_router({snake_name}_router)")
+    typer.echo()
+
+
+@app.command()
+def controller(
+    name: str = typer.Argument(..., help="Controller name"),
+    path: Optional[Path] = typer.Option(None, "--path", "-p"),
+):
+    """
+    📡 Generate a controller (router) file.
+
+    Example:
+        tachyon g controller users
+    """
+    snake_name = _to_snake_case(name)
+    class_name = _to_class_name(name)
+
+    base_path = path or Path.cwd() / "modules" / snake_name
+    base_path.mkdir(parents=True, exist_ok=True)
+
+    typer.echo(f"\n📡 Generating controller: {snake_name}\n")
+
+    _create_file(
+        base_path / f"{snake_name}_controller.py",
+        ServiceTemplates.controller(snake_name, class_name, False),
+        f"{snake_name}_controller.py",
+    )
+
+    typer.echo("\n✅ Controller generated!")
+
+
+@app.command("repo")
+@app.command("repository")
+def repository(
+    name: str = typer.Argument(..., help="Repository name"),
+    path: Optional[Path] = typer.Option(None, "--path", "-p"),
+):
+    """
+    🗄️  Generate a repository file.
+
+    Example:
+        tachyon g repository users
+        tachyon g repo products
+    """
+    snake_name = _to_snake_case(name)
+    class_name = _to_class_name(name)
+
+    base_path = path or Path.cwd() / "modules" / snake_name
+    base_path.mkdir(parents=True, exist_ok=True)
+
+    typer.echo(f"\n🗄️  Generating repository: {snake_name}\n")
+
+    _create_file(
+        base_path / f"{snake_name}_repository.py",
+        ServiceTemplates.repository(snake_name, class_name, False),
+        f"{snake_name}_repository.py",
+    )
+
+    typer.echo("\n✅ Repository generated!")
+
+
+@app.command()
+def dto(
+    name: str = typer.Argument(..., help="DTO name"),
+    path: Optional[Path] = typer.Option(None, "--path", "-p"),
+):
+    """
+    📦 Generate a DTO (Data Transfer Object) file.
+
+    Example:
+        tachyon g dto users
+    """
+    snake_name = _to_snake_case(name)
+    class_name = _to_class_name(name)
+
+    base_path = path or Path.cwd() / "modules" / snake_name
+    base_path.mkdir(parents=True, exist_ok=True)
+
+    typer.echo(f"\n📦 Generating DTO: {snake_name}\n")
+
+    _create_file(
+        base_path / f"{snake_name}_dto.py",
+        ServiceTemplates.dto(snake_name, class_name, False),
+        f"{snake_name}_dto.py",
+    )
+
+    typer.echo("\n✅ DTO generated!")