fastapi-fullstack 0.1.7__py3-none-any.whl

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/api/versioning.py

@@ -0,0 +1,221 @@
+"""API versioning utilities and deprecation handling.
+
+This module provides tools for managing API version deprecation:
+- Deprecation middleware for entire API versions
+- Deprecation decorator for individual endpoints
+- RFC 8594 compliant deprecation headers
+"""
+
+from collections.abc import Callable
+from datetime import datetime
+from functools import wraps
+
+import logfire
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+
+
+class VersionDeprecationMiddleware(BaseHTTPMiddleware):
+    """Middleware to add deprecation headers for deprecated API versions.
+
+    Adds RFC 8594 compliant headers:
+    - Deprecation: Indicates the version is deprecated
+    - Sunset: Indicates when the version will be removed
+    - Link: Points to migration documentation
+
+    Usage in main.py:
+        app.add_middleware(
+            VersionDeprecationMiddleware,
+            deprecated_versions={"v1": {"sunset": "2025-06-01", "link": "/docs/migration/v2"}},
+        )
+    """
+
+    def __init__(
+        self,
+        app,
+        deprecated_versions: dict[str, dict] | None = None,
+    ):
+        """Initialize the middleware.
+
+        Args:
+            app: The ASGI application.
+            deprecated_versions: Dict mapping version prefixes to deprecation info.
+                Each entry should have:
+                - sunset: ISO date string when version will be removed (optional)
+                - link: URL to migration documentation (optional)
+                - message: Custom deprecation message (optional)
+
+        Example:
+            {
+                "v1": {
+                    "sunset": "2025-06-01",
+                    "link": "https://api.example.com/docs/migration/v2",
+                    "message": "Please migrate to API v2",
+                }
+            }
+        """
+        super().__init__(app)
+        self.deprecated_versions = deprecated_versions or {}
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """Process the request and add deprecation headers if needed."""
+        response = await call_next(request)
+
+        # Check if request path matches a deprecated version
+        path = request.url.path
+        for version, info in self.deprecated_versions.items():
+            if f"/api/{version}/" in path or path.endswith(f"/api/{version}"):
+                self._add_deprecation_headers(response, version, info)
+                self._log_deprecated_usage(request, version)
+                break
+
+        return response
+
+    def _add_deprecation_headers(
+        self, response: Response, version: str, info: dict
+    ) -> None:
+        """Add RFC 8594 deprecation headers to the response."""
+        # Deprecation header - indicates the API is deprecated
+        response.headers["Deprecation"] = "true"
+
+        # Sunset header - when the API will be removed
+        if sunset := info.get("sunset"):
+            # Convert to HTTP date format
+            sunset_date = datetime.fromisoformat(sunset)
+            response.headers["Sunset"] = sunset_date.strftime("%a, %d %b %Y %H:%M:%S GMT")
+
+        # Link header - documentation for migration
+        if link := info.get("link"):
+            response.headers["Link"] = f'<{link}>; rel="deprecation"'
+
+        # Custom warning header
+        message = info.get("message", f"API {version} is deprecated")
+        response.headers["X-API-Deprecation-Warning"] = message
+
+    def _log_deprecated_usage(self, request: Request, version: str) -> None:
+        """Log usage of deprecated API version for monitoring."""
+        logfire.warn(
+            "Deprecated API version accessed",
+            version=version,
+            path=request.url.path,
+            method=request.method,
+            client_ip=request.client.host if request.client else None,
+            user_agent=request.headers.get("User-Agent"),
+        )
+
+
+def deprecated(
+    sunset: str | None = None,
+    message: str | None = None,
+    link: str | None = None,
+):
+    """Decorator to mark an endpoint as deprecated.
+
+    Adds deprecation headers to responses from the decorated endpoint.
+    Use this for deprecating individual endpoints within an active API version.
+
+    Args:
+        sunset: ISO date string when endpoint will be removed.
+        message: Custom deprecation message.
+        link: URL to migration documentation.
+
+    Usage:
+        @router.get("/old-endpoint")
+        @deprecated(
+            sunset="2025-06-01",
+            message="Use /new-endpoint instead",
+            link="/docs/migration",
+        )
+        async def old_endpoint():
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # Get the response from the endpoint
+            result = await func(*args, **kwargs)
+
+            # Find Response object in args (FastAPI injects it)
+            response = None
+            for arg in args:
+                if isinstance(arg, Response):
+                    response = arg
+                    break
+            for value in kwargs.values():
+                if isinstance(value, Response):
+                    response = value
+                    break
+
+            # If we have a Response object, add headers
+            if response:
+                response.headers["Deprecation"] = "true"
+                if sunset:
+                    sunset_date = datetime.fromisoformat(sunset)
+                    response.headers["Sunset"] = sunset_date.strftime(
+                        "%a, %d %b %Y %H:%M:%S GMT"
+                    )
+                if link:
+                    response.headers["Link"] = f'<{link}>; rel="deprecation"'
+                if message:
+                    response.headers["X-API-Deprecation-Warning"] = message
+
+            return result
+
+        # Add deprecation info to OpenAPI schema
+        wrapper.__doc__ = (
+            f"{func.__doc__ or ''}\n\n"
+            f"**DEPRECATED**"
+            f"{f': {message}' if message else ''}"
+            f"{f' (Sunset: {sunset})' if sunset else ''}"
+        )
+
+        return wrapper
+
+    return decorator
+
+
+# Example usage documentation
+"""
+## Adding a New API Version
+
+1. Create a new version folder:
+   ```
+   app/api/routes/v2/
+   ├── __init__.py
+   ├── health.py
+   ├── auth.py
+   └── ...
+   ```
+
+2. Create the v2 router in `v2/__init__.py`:
+   ```python
+   from fastapi import APIRouter
+   v2_router = APIRouter()
+   # Include routes...
+   ```
+
+3. Add the v2 router in `app/api/router.py`:
+   ```python
+   from app.api.routes.v2 import v2_router
+
+   api_router.include_router(v1_router, prefix="/v1")
+   api_router.include_router(v2_router, prefix="/v2")
+   ```
+
+4. Mark v1 as deprecated in `main.py`:
+   ```python
+   app.add_middleware(
+       VersionDeprecationMiddleware,
+       deprecated_versions={
+           "v1": {
+               "sunset": "2025-12-31",
+               "link": "/docs/migration/v2",
+               "message": "Please migrate to API v2",
+           }
+       },
+   )
+   ```
+"""

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/clients/__init__.py

@@ -0,0 +1,14 @@
+"""External service clients.
+
+This module contains thin wrappers around external services like Redis.
+"""
+{%- if cookiecutter.enable_redis %}
+
+from app.clients.redis import RedisClient
+{%- endif %}
+
+__all__ = [
+{%- if cookiecutter.enable_redis %}
+    "RedisClient",
+{%- endif %}
+]

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/clients/redis.py

@@ -0,0 +1,88 @@
+{%- if cookiecutter.enable_redis %}
+"""Redis client wrapper.
+
+Provides a class-based Redis client for connection management and operations.
+"""
+
+from redis import asyncio as aioredis
+
+from app.core.config import settings
+
+
+class RedisClient:
+    """Redis client wrapper for connection lifecycle management.
+
+    Usage in FastAPI lifespan:
+        async with contextmanager():
+            redis = RedisClient(settings.REDIS_URL)
+            await redis.connect()
+            yield {"redis": redis}
+            await redis.close()
+    """
+
+    def __init__(self, url: str | None = None):
+        self.url = url or settings.REDIS_URL
+        self.client: aioredis.Redis | None = None
+
+    async def connect(self) -> None:
+        """Connect to Redis server."""
+        self.client = aioredis.from_url(
+            self.url,
+            encoding="utf-8",
+            decode_responses=True,
+        )
+
+    async def close(self) -> None:
+        """Close Redis connection."""
+        if self.client:
+            await self.client.close()
+            self.client = None
+
+    async def get(self, key: str) -> str | None:
+        """Get a value by key."""
+        if not self.client:
+            raise RuntimeError("Redis client not connected")
+        return await self.client.get(key)
+
+    async def set(
+        self,
+        key: str,
+        value: str,
+        ttl: int | None = None,
+    ) -> None:
+        """Set a value with optional TTL (in seconds)."""
+        if not self.client:
+            raise RuntimeError("Redis client not connected")
+        await self.client.set(key, value, ex=ttl)
+
+    async def delete(self, key: str) -> int:
+        """Delete a key. Returns number of keys deleted."""
+        if not self.client:
+            raise RuntimeError("Redis client not connected")
+        return await self.client.delete(key)
+
+    async def exists(self, key: str) -> bool:
+        """Check if key exists."""
+        if not self.client:
+            raise RuntimeError("Redis client not connected")
+        return bool(await self.client.exists(key))
+
+    async def ping(self) -> bool:
+        """Ping Redis server. Returns True if connected."""
+        if not self.client:
+            return False
+        try:
+            await self.client.ping()
+            return True
+        except Exception:
+            return False
+
+    @property
+    def raw(self) -> aioredis.Redis:
+        """Access the underlying aioredis client for advanced operations."""
+        if not self.client:
+            raise RuntimeError("Redis client not connected")
+        return self.client
+{%- else %}
+"""Redis client - not configured."""
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/commands/__init__.py

@@ -0,0 +1,117 @@
+"""
+Custom commands system with auto-discovery.
+
+This module provides a Django-like custom commands system for FastAPI + Click.
+Commands are auto-discovered from this package and registered to the CLI.
+
+Usage:
+    # In app/commands/my_command.py
+    from app.commands import command
+    import click
+
+    @command("my-command", help="Description of my command")
+    @click.option("--option", "-o", help="Some option")
+    def my_command(option: str):
+        click.echo(f"Running with {option}")
+
+    # Then use it:
+    # project cmd my-command --option value
+"""
+
+import importlib
+import pkgutil
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+
+# Registry for custom commands
+_commands: list[click.Command] = []
+_discovered = False
+
+
+def command(name: str | None = None, **kwargs) -> Callable:
+    """
+    Decorator to register a custom command.
+
+    Args:
+        name: Command name (defaults to function name with underscores replaced by hyphens)
+        **kwargs: Additional arguments passed to click.command()
+
+    Example:
+        @command("seed", help="Seed database with initial data")
+        @click.option("--count", "-c", default=10)
+        def seed_data(count: int):
+            click.echo(f"Seeding {count} records...")
+    """
+
+    def decorator(func: Callable) -> click.Command:
+        cmd_name = name or func.__name__.replace("_", "-")
+        cmd = click.command(cmd_name, **kwargs)(func)
+        _commands.append(cmd)
+        return cmd
+
+    return decorator
+
+
+def discover_commands() -> list[click.Command]:
+    """
+    Auto-discover all commands in this package.
+
+    Imports all modules in the app.commands package (except those starting with _)
+    which triggers the @command decorator to register them.
+
+    Returns:
+        List of discovered click.Command objects
+    """
+    global _discovered
+
+    if _discovered:
+        return _commands
+
+    package_dir = Path(__file__).parent
+
+    for _, module_name, _ in pkgutil.iter_modules([str(package_dir)]):
+        if module_name.startswith("_"):
+            continue
+
+        try:
+            importlib.import_module(f"app.commands.{module_name}")
+        except ImportError as e:
+            click.secho(f"Warning: Failed to import command module '{module_name}': {e}", fg="yellow")
+
+    _discovered = True
+    return _commands
+
+
+def register_commands(cli: click.Group) -> None:
+    """
+    Register all discovered commands to a CLI group.
+
+    Args:
+        cli: The click.Group to add commands to
+    """
+    commands = discover_commands()
+
+    for cmd in commands:
+        cli.add_command(cmd)
+
+
+def success(message: str) -> None:
+    """Print success message in green."""
+    click.secho(message, fg="green")
+
+
+def error(message: str) -> None:
+    """Print error message in red."""
+    click.secho(message, fg="red")
+
+
+def warning(message: str) -> None:
+    """Print warning message in yellow."""
+    click.secho(message, fg="yellow")
+
+
+def info(message: str) -> None:
+    """Print info message."""
+    click.echo(message)

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/commands/cleanup.py

@@ -0,0 +1,75 @@
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite -%}
+"""
+Cleanup old or stale data from the database.
+
+This command is useful for maintenance tasks.
+"""
+
+import asyncio
+from datetime import datetime, timedelta
+
+import click
+
+from app.commands import command, info, success, warning
+
+
+@command("cleanup", help="Clean up old data from the database")
+@click.option("--days", "-d", default=30, type=int, help="Delete records older than N days")
+@click.option("--dry-run", is_flag=True, help="Show what would be deleted without making changes")
+@click.option("--force", "-f", is_flag=True, help="Skip confirmation prompt")
+def cleanup(days: int, dry_run: bool, force: bool) -> None:
+    """
+    Remove old records from the database.
+
+    Example:
+        project cmd cleanup --days 90
+        project cmd cleanup --days 30 --dry-run
+        project cmd cleanup --days 7 --force
+    """
+    cutoff_date = datetime.utcnow() - timedelta(days=days)
+
+    if dry_run:
+        info(f"[DRY RUN] Would delete records older than {cutoff_date}")
+        return
+
+    if not force and not click.confirm(f"Delete all records older than {days} days ({cutoff_date})?"):
+        warning("Aborted.")
+        return
+
+{%- if cookiecutter.use_postgresql %}
+    from app.db.session import async_session_maker
+
+    async def _cleanup():
+        async with async_session_maker() as _session:
+            info(f"Cleaning up records older than {cutoff_date}...")
+
+            # Add your cleanup logic here
+            # Example:
+            # result = await session.execute(
+            #     delete(YourModel).where(YourModel.created_at < cutoff_date)
+            # )
+            # await session.commit()
+            # deleted_count = result.rowcount
+
+            deleted_count = 0  # Replace with actual count
+            success(f"Deleted {deleted_count} records.")
+
+    asyncio.run(_cleanup())
+{%- elif cookiecutter.use_sqlite %}
+    from app.db.session import SessionLocal
+
+    with SessionLocal() as _session:
+        info(f"Cleaning up records older than {cutoff_date}...")
+
+        # Add your cleanup logic here
+        # Example:
+        # result = session.execute(
+        #     delete(YourModel).where(YourModel.created_at < cutoff_date)
+        # )
+        # session.commit()
+        # deleted_count = result.rowcount
+
+        deleted_count = 0  # Replace with actual count
+        success(f"Deleted {deleted_count} records.")
+{%- endif %}
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/commands/example.py

@@ -0,0 +1,28 @@
+"""
+Example custom command.
+
+This is a template showing how to create custom CLI commands.
+Copy this file and modify it to create your own commands.
+"""
+
+import click
+
+from app.commands import command, info, success
+
+
+@command("hello", help="Example command that greets the user")
+@click.option("--name", "-n", default="World", help="Name to greet")
+@click.option("--count", "-c", default=1, type=int, help="Number of greetings")
+def hello(name: str, count: int) -> None:
+    """
+    Greet someone multiple times.
+
+    Example:
+        project cmd hello --name Alice --count 3
+    """
+    info(f"Greeting {name} {count} time(s)...")
+
+    for i in range(count):
+        click.echo(f"  [{i + 1}] Hello, {name}!")
+
+    success("Done!")