fastapi-fullstack 0.1.2__py3-none-any.whl

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

@@ -0,0 +1,266 @@
+{%- if cookiecutter.use_postgresql or cookiecutter.use_sqlite -%}
+# ruff: noqa: I001 - Imports structured for Jinja2 template conditionals
+"""
+Seed database with sample data.
+
+This command is useful for development and testing.
+Uses random data generation - install faker for better data:
+    uv add faker --group dev
+"""
+
+import asyncio
+import random
+import string
+
+import click
+from sqlalchemy import delete, select
+
+from app.commands import command, info, success, warning
+
+# Try to import Faker for better data generation
+try:
+    from faker import Faker
+    fake = Faker()
+    HAS_FAKER = True
+except ImportError:
+    HAS_FAKER = False
+    fake = None
+
+
+def random_email() -> str:
+    """Generate a random email address."""
+    if HAS_FAKER:
+        return fake.email()
+    random_str = ''.join(random.choices(string.ascii_lowercase, k=8))
+    return f"{random_str}@example.com"
+
+
+def random_name() -> str:
+    """Generate a random full name."""
+    if HAS_FAKER:
+        return fake.name()
+    first_names = ["John", "Jane", "Bob", "Alice", "Charlie", "Diana", "Eve", "Frank"]
+    last_names = ["Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis"]
+    return f"{random.choice(first_names)} {random.choice(last_names)}"
+
+
+def random_title() -> str:
+    """Generate a random item title."""
+    if HAS_FAKER:
+        return fake.sentence(nb_words=4).rstrip('.')
+    adjectives = ["Amazing", "Great", "Awesome", "Fantastic", "Incredible", "Beautiful"]
+    nouns = ["Widget", "Gadget", "Thing", "Product", "Item", "Object"]
+    return f"{random.choice(adjectives)} {random.choice(nouns)}"
+
+
+def random_description() -> str:
+    """Generate a random description."""
+    if HAS_FAKER:
+        return fake.paragraph(nb_sentences=3)
+    return "This is a sample description for development purposes."
+
+
+@command("seed", help="Seed database with sample data")
+@click.option("--count", "-c", default=10, type=int, help="Number of records to create")
+@click.option("--clear", is_flag=True, help="Clear existing data before seeding")
+@click.option("--dry-run", is_flag=True, help="Show what would be created without making changes")
+{%- if cookiecutter.use_jwt %}
+@click.option("--users/--no-users", default=True, help="Seed users (default: True)")
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+@click.option("--items/--no-items", default=True, help="Seed items (default: True)")
+{%- endif %}
+def seed(
+    count: int,
+    clear: bool,
+    dry_run: bool,
+{%- if cookiecutter.use_jwt %}
+    users: bool,
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+    items: bool,
+{%- endif %}
+) -> None:
+    """
+    Seed the database with sample data for development.
+
+    Example:
+        project cmd seed --count 50
+        project cmd seed --clear --count 100
+        project cmd seed --dry-run
+    {%- if cookiecutter.use_jwt %}
+        project cmd seed --no-users --items  # Only seed items
+    {%- endif %}
+    """
+    if not HAS_FAKER:
+        warning("Faker not installed. Using basic random data. For better data: uv add faker --group dev")
+
+    if dry_run:
+        info(f"[DRY RUN] Would create {count} sample records per entity")
+        if clear:
+            info("[DRY RUN] Would clear existing data first")
+{%- if cookiecutter.use_jwt %}
+        if users:
+            info("[DRY RUN] Would create users")
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+        if items:
+            info("[DRY RUN] Would create items")
+{%- endif %}
+        return
+
+{%- if cookiecutter.use_postgresql %}
+    from app.db.session import async_session_maker
+{%- if cookiecutter.use_jwt %}
+    from app.db.models.user import User
+    from app.core.security import get_password_hash
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+    from app.db.models.item import Item
+{%- endif %}
+
+    async def _seed():
+        async with async_session_maker() as session:
+            created_counts = {}
+
+{%- if cookiecutter.use_jwt %}
+            # Seed users
+            if users:
+                if clear:
+                    info("Clearing existing users (except superusers)...")
+                    await session.execute(delete(User).where(User.is_superuser == False))  # noqa: E712
+                    await session.commit()
+
+                # Check how many users already exist
+                result = await session.execute(select(User).limit(1))
+                existing = result.scalars().first()
+
+                if existing and not clear:
+                    info("Users already exist. Use --clear to replace them.")
+                else:
+                    info(f"Creating {count} sample users...")
+                    for _ in range(count):
+                        user = User(
+                            email=random_email(),
+                            hashed_password=get_password_hash("password123"),
+                            full_name=random_name(),
+                            is_active=True,
+                            is_superuser=False,
+                            role="user",
+                        )
+                        session.add(user)
+                    await session.commit()
+                    created_counts["users"] = count
+{%- endif %}
+
+{%- if cookiecutter.include_example_crud %}
+            # Seed items
+            if items:
+                if clear:
+                    info("Clearing existing items...")
+                    await session.execute(delete(Item))
+                    await session.commit()
+
+                # Check how many items already exist
+                result = await session.execute(select(Item).limit(1))
+                existing = result.scalars().first()
+
+                if existing and not clear:
+                    info("Items already exist. Use --clear to replace them.")
+                else:
+                    info(f"Creating {count} sample items...")
+                    for _ in range(count):
+                        item = Item(
+                            title=random_title(),
+                            description=random_description(),
+                            is_active=random.choice([True, True, True, False]),  # 75% active
+                        )
+                        session.add(item)
+                    await session.commit()
+                    created_counts["items"] = count
+{%- endif %}
+
+            if created_counts:
+                summary = ", ".join(f"{v} {k}" for k, v in created_counts.items())
+                success(f"Created: {summary}")
+            else:
+                info("No records created.")
+
+    asyncio.run(_seed())
+{%- elif cookiecutter.use_sqlite %}
+    from app.db.session import SessionLocal
+{%- if cookiecutter.use_jwt %}
+    from app.db.models.user import User
+    from app.core.security import get_password_hash
+{%- endif %}
+{%- if cookiecutter.include_example_crud %}
+    from app.db.models.item import Item
+{%- endif %}
+
+    with SessionLocal() as session:
+        created_counts = {}
+
+{%- if cookiecutter.use_jwt %}
+        # Seed users
+        if users:
+            if clear:
+                info("Clearing existing users (except superusers)...")
+                session.execute(delete(User).where(User.is_superuser == False))  # noqa: E712
+                session.commit()
+
+            # Check how many users already exist
+            result = session.execute(select(User).limit(1))
+            existing = result.scalars().first()
+
+            if existing and not clear:
+                info("Users already exist. Use --clear to replace them.")
+            else:
+                info(f"Creating {count} sample users...")
+                for _ in range(count):
+                    user = User(
+                        email=random_email(),
+                        hashed_password=get_password_hash("password123"),
+                        full_name=random_name(),
+                        is_active=True,
+                        is_superuser=False,
+                        role="user",
+                    )
+                    session.add(user)
+                session.commit()
+                created_counts["users"] = count
+{%- endif %}
+
+{%- if cookiecutter.include_example_crud %}
+        # Seed items
+        if items:
+            if clear:
+                info("Clearing existing items...")
+                session.execute(delete(Item))
+                session.commit()
+
+            # Check how many items already exist
+            result = session.execute(select(Item).limit(1))
+            existing = result.scalars().first()
+
+            if existing and not clear:
+                info("Items already exist. Use --clear to replace them.")
+            else:
+                info(f"Creating {count} sample items...")
+                for _ in range(count):
+                    item = Item(
+                        title=random_title(),
+                        description=random_description(),
+                        is_active=random.choice([True, True, True, False]),  # 75% active
+                    )
+                    session.add(item)
+                session.commit()
+                created_counts["items"] = count
+{%- endif %}
+
+        if created_counts:
+            summary = ", ".join(f"{v} {k}" for k, v in created_counts.items())
+            success(f"Created: {summary}")
+        else:
+            info("No records created.")
+{%- endif %}
+{%- endif %}

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

@@ -0,0 +1,5 @@
+"""Core application configuration and utilities."""
+
+from .config import settings
+
+__all__ = ["settings"]

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/cache.py

@@ -0,0 +1,23 @@
+{%- if cookiecutter.enable_caching %}
+"""Caching configuration using fastapi-cache2."""
+
+from fastapi_cache import FastAPICache
+from fastapi_cache.backends.redis import RedisBackend
+
+from app.clients.redis import RedisClient
+
+
+def setup_cache(redis: RedisClient) -> None:
+    """Initialize FastAPI cache with Redis backend.
+
+    Uses the shared Redis client from lifespan state.
+    """
+    FastAPICache.init(RedisBackend(redis.raw), prefix="{{ cookiecutter.project_slug }}:cache:")
+{%- else %}
+"""Caching - not configured."""
+
+
+async def setup_cache() -> None:
+    """No-op when caching is disabled."""
+    pass
+{%- endif %}

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/config.py

@@ -0,0 +1,247 @@
+"""Application configuration using Pydantic BaseSettings."""
+{% if cookiecutter.use_database -%}
+# ruff: noqa: I001 - Imports structured for Jinja2 template conditionals
+{% endif %}
+from pathlib import Path
+from typing import Literal
+
+{% if cookiecutter.use_database -%}
+from pydantic import computed_field, field_validator
+{% else -%}
+from pydantic import field_validator
+{% endif -%}
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def find_env_file() -> Path | None:
+    """Find .env file in current or parent directories."""
+    current = Path.cwd()
+    for path in [current, current.parent]:
+        env_file = path / ".env"
+        if env_file.exists():
+            return env_file
+    return None
+
+
+class Settings(BaseSettings):
+    """Application settings."""
+
+    model_config = SettingsConfigDict(
+        env_file=find_env_file(),
+        env_ignore_empty=True,
+        extra="ignore",
+    )
+
+    # === Project ===
+    PROJECT_NAME: str = "{{ cookiecutter.project_name }}"
+    API_V1_STR: str = "/api/v1"
+    DEBUG: bool = False
+    ENVIRONMENT: Literal["development", "local", "staging", "production"] = "local"
+
+{%- if cookiecutter.enable_logfire %}
+
+    # === Logfire ===
+    LOGFIRE_TOKEN: str | None = None
+    LOGFIRE_SERVICE_NAME: str = "{{ cookiecutter.project_slug }}"
+    LOGFIRE_ENVIRONMENT: str = "development"
+{%- endif %}
+
+{%- if cookiecutter.use_postgresql %}
+
+    # === Database (PostgreSQL async) ===
+    POSTGRES_HOST: str = "localhost"
+    POSTGRES_PORT: int = 5432
+    POSTGRES_USER: str = "postgres"
+    POSTGRES_PASSWORD: str = ""
+    POSTGRES_DB: str = "{{ cookiecutter.project_slug }}"
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def DATABASE_URL(self) -> str:
+        """Build async PostgreSQL connection URL."""
+        return (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def DATABASE_URL_SYNC(self) -> str:
+        """Build sync PostgreSQL connection URL (for Alembic)."""
+        return (
+            f"postgresql://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+    # Pool configuration
+    DB_POOL_SIZE: int = {{ cookiecutter.db_pool_size }}
+    DB_MAX_OVERFLOW: int = {{ cookiecutter.db_max_overflow }}
+    DB_POOL_TIMEOUT: int = {{ cookiecutter.db_pool_timeout }}
+{%- endif %}
+
+{%- if cookiecutter.use_mongodb %}
+
+    # === Database (MongoDB async) ===
+    MONGO_HOST: str = "localhost"
+    MONGO_PORT: int = 27017
+    MONGO_DB: str = "{{ cookiecutter.project_slug }}"
+    MONGO_USER: str | None = None
+    MONGO_PASSWORD: str | None = None
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def MONGO_URL(self) -> str:
+        """Build MongoDB connection URL."""
+        if self.MONGO_USER and self.MONGO_PASSWORD:
+            return f"mongodb://{self.MONGO_USER}:{self.MONGO_PASSWORD}@{self.MONGO_HOST}:{self.MONGO_PORT}"
+        return f"mongodb://{self.MONGO_HOST}:{self.MONGO_PORT}"
+{%- endif %}
+
+{%- if cookiecutter.use_sqlite %}
+
+    # === Database (SQLite sync) ===
+    SQLITE_PATH: str = "./{{ cookiecutter.project_slug }}.db"
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def DATABASE_URL(self) -> str:
+        """Build SQLite connection URL."""
+        return f"sqlite:///{self.SQLITE_PATH}"
+{%- endif %}
+
+{%- if cookiecutter.use_jwt %}
+
+    # === Auth (JWT) ===
+    SECRET_KEY: str = "change-me-in-production-use-openssl-rand-hex-32"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30  # 30 minutes
+    REFRESH_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 7  # 7 days
+    ALGORITHM: str = "HS256"
+
+    @field_validator("SECRET_KEY")
+    @classmethod
+    def validate_secret_key(cls, v: str, info) -> str:
+        """Validate SECRET_KEY is secure in production."""
+        if len(v) < 32:
+            raise ValueError("SECRET_KEY must be at least 32 characters long")
+        # Get environment from values if available
+        env = info.data.get("ENVIRONMENT", "local") if info.data else "local"
+        if v == "change-me-in-production-use-openssl-rand-hex-32" and env == "production":
+            raise ValueError(
+                "SECRET_KEY must be changed in production! "
+                "Generate a secure key with: openssl rand -hex 32"
+            )
+        return v
+{%- endif %}
+
+{%- if cookiecutter.enable_oauth_google %}
+
+    # === OAuth2 (Google) ===
+    GOOGLE_CLIENT_ID: str = ""
+    GOOGLE_CLIENT_SECRET: str = ""
+    GOOGLE_REDIRECT_URI: str = "http://localhost:{{ cookiecutter.backend_port }}/api/v1/oauth/google/callback"
+{%- endif %}
+
+{%- if cookiecutter.use_api_key %}
+
+    # === Auth (API Key) ===
+    API_KEY: str = "change-me-in-production"
+    API_KEY_HEADER: str = "X-API-Key"
+
+    @field_validator("API_KEY")
+    @classmethod
+    def validate_api_key(cls, v: str, info) -> str:
+        """Validate API_KEY is set in production."""
+        env = info.data.get("ENVIRONMENT", "local") if info.data else "local"
+        if v == "change-me-in-production" and env == "production":
+            raise ValueError(
+                "API_KEY must be changed in production! "
+                "Generate a secure key with: openssl rand -hex 32"
+            )
+        return v
+{%- endif %}
+
+{%- if cookiecutter.enable_redis %}
+
+    # === Redis ===
+    REDIS_HOST: str = "localhost"
+    REDIS_PORT: int = 6379
+    REDIS_PASSWORD: str | None = None
+    REDIS_DB: int = 0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def REDIS_URL(self) -> str:
+        """Build Redis connection URL."""
+        if self.REDIS_PASSWORD:
+            return f"redis://:{self.REDIS_PASSWORD}@{self.REDIS_HOST}:{self.REDIS_PORT}/{self.REDIS_DB}"
+        return f"redis://{self.REDIS_HOST}:{self.REDIS_PORT}/{self.REDIS_DB}"
+{%- endif %}
+
+{%- if cookiecutter.enable_rate_limiting %}
+
+    # === Rate Limiting ===
+    RATE_LIMIT_REQUESTS: int = {{ cookiecutter.rate_limit_requests }}
+    RATE_LIMIT_PERIOD: int = {{ cookiecutter.rate_limit_period }}  # seconds
+{%- endif %}
+
+{%- if cookiecutter.use_celery %}
+
+    # === Celery ===
+    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
+    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/0"
+{%- endif %}
+
+{%- if cookiecutter.use_taskiq %}
+
+    # === Taskiq ===
+    TASKIQ_BROKER_URL: str = "redis://localhost:6379/1"
+    TASKIQ_RESULT_BACKEND: str = "redis://localhost:6379/1"
+{%- endif %}
+
+{%- if cookiecutter.enable_sentry %}
+
+    # === Sentry ===
+    SENTRY_DSN: str | None = None
+{%- endif %}
+
+{%- if cookiecutter.enable_file_storage %}
+
+    # === File Storage (S3/MinIO) ===
+    S3_ENDPOINT: str | None = None
+    S3_ACCESS_KEY: str = ""
+    S3_SECRET_KEY: str = ""
+    S3_BUCKET: str = "{{ cookiecutter.project_slug }}"
+    S3_REGION: str = "us-east-1"
+{%- endif %}
+
+{%- if cookiecutter.enable_ai_agent %}
+
+    # === AI Agent (PydanticAI) ===
+    OPENAI_API_KEY: str = ""
+    AI_MODEL: str = "gpt-4o-mini"
+    AI_TEMPERATURE: float = 0.7
+{%- endif %}
+
+{%- if cookiecutter.enable_cors %}
+
+    # === CORS ===
+    CORS_ORIGINS: list[str] = ["http://localhost:3000", "http://localhost:8080"]
+    CORS_ALLOW_CREDENTIALS: bool = True
+    CORS_ALLOW_METHODS: list[str] = ["*"]
+    CORS_ALLOW_HEADERS: list[str] = ["*"]
+
+    @field_validator("CORS_ORIGINS")
+    @classmethod
+    def validate_cors_origins(cls, v: list[str], info) -> list[str]:
+        """Warn if CORS_ORIGINS is too permissive in production."""
+        env = info.data.get("ENVIRONMENT", "local") if info.data else "local"
+        if "*" in v and env == "production":
+            raise ValueError(
+                "CORS_ORIGINS cannot contain '*' in production! "
+                "Specify explicit allowed origins."
+            )
+        return v
+{%- endif %}
+
+
+settings = Settings()

fastapi_gen/template/{{cookiecutter.project_slug}}/backend/app/core/csrf.py

@@ -0,0 +1,153 @@
+{%- if cookiecutter.use_jwt %}
+"""CSRF protection middleware for FastAPI.
+
+This module provides CSRF (Cross-Site Request Forgery) protection for
+state-changing HTTP methods (POST, PUT, PATCH, DELETE).
+
+The protection works by:
+1. Setting a CSRF token in a cookie on initial request
+2. Requiring the token to be sent in a header for state-changing requests
+3. Comparing the cookie token with the header token
+
+Usage:
+    Add to your main.py:
+
+    from app.core.csrf import CSRFMiddleware
+
+    app.add_middleware(CSRFMiddleware)
+
+    For endpoints that should be exempt (e.g., login):
+
+    @router.post("/login", tags=["csrf-exempt"])
+    async def login(...):
+        ...
+"""
+
+import secrets
+from collections.abc import Callable
+from typing import ClassVar
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from app.core.config import settings
+
+
+class CSRFMiddleware(BaseHTTPMiddleware):
+    """CSRF protection middleware.
+
+    Protects against Cross-Site Request Forgery attacks by requiring
+    a token to be present in both a cookie and a header for state-changing requests.
+    """
+
+    # Methods that require CSRF protection
+    PROTECTED_METHODS: ClassVar[set[str]] = {"POST", "PUT", "PATCH", "DELETE"}
+
+    # Cookie settings
+    COOKIE_NAME: ClassVar[str] = "csrf_token"
+    HEADER_NAME: ClassVar[str] = "X-CSRF-Token"
+
+    # Paths to exclude from CSRF protection
+    EXEMPT_PATHS: ClassVar[set[str]] = {
+        "/api/v1/auth/login",
+        "/api/v1/auth/register",
+        "/api/v1/auth/refresh",
+        "/api/v1/health",
+        "/api/v1/ready",
+        "/docs",
+        "/openapi.json",
+        "/redoc",
+    }
+
+    def __init__(self, app: Callable, **kwargs):
+        super().__init__(app)
+        self.exempt_paths = set(kwargs.get("exempt_paths", self.EXEMPT_PATHS))
+        self.cookie_name = kwargs.get("cookie_name", self.COOKIE_NAME)
+        self.header_name = kwargs.get("header_name", self.HEADER_NAME)
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Handle the request and apply CSRF protection."""
+        # Skip for exempt paths
+        if self._is_exempt(request):
+            return await call_next(request)
+
+        # Get or generate CSRF token
+        csrf_token = request.cookies.get(self.cookie_name)
+        if not csrf_token:
+            csrf_token = self._generate_token()
+
+        # Check CSRF for protected methods
+        if request.method in self.PROTECTED_METHODS:
+            header_token = request.headers.get(self.header_name)
+
+            if not header_token:
+                return JSONResponse(
+                    status_code=403,
+                    content={
+                        "detail": "CSRF token missing",
+                        "message": f"Include the '{self.header_name}' header with the CSRF token",
+                    },
+                )
+
+            if not secrets.compare_digest(csrf_token, header_token):
+                return JSONResponse(
+                    status_code=403,
+                    content={
+                        "detail": "CSRF token invalid",
+                        "message": "The CSRF token does not match",
+                    },
+                )
+
+        # Process the request
+        response = await call_next(request)
+
+        # Set CSRF token cookie if not present
+        if not request.cookies.get(self.cookie_name):
+            response.set_cookie(
+                key=self.cookie_name,
+                value=csrf_token,
+                httponly=False,  # JavaScript needs to read this
+                secure=not settings.DEBUG,
+                samesite="lax",
+                max_age=3600 * 24,  # 24 hours
+            )
+
+        return response
+
+    def _is_exempt(self, request: Request) -> bool:
+        """Check if the request path is exempt from CSRF protection."""
+        path = request.url.path
+
+        # Check exact path matches
+        if path in self.exempt_paths:
+            return True
+
+        # Check path prefixes
+        for exempt in self.exempt_paths:
+            if path.startswith(exempt):
+                return True
+
+        # Check if endpoint has "csrf-exempt" tag
+        route = request.scope.get("route")
+        return bool(route and hasattr(route, "tags") and "csrf-exempt" in route.tags)
+
+    @staticmethod
+    def _generate_token() -> str:
+        """Generate a secure CSRF token."""
+        return secrets.token_urlsafe(32)
+
+
+def get_csrf_token(request: Request) -> str:
+    """Get the current CSRF token from cookies or generate a new one.
+
+    Use this in templates or API responses to provide the token to clients.
+    """
+    token = request.cookies.get(CSRFMiddleware.COOKIE_NAME)
+    if not token:
+        token = secrets.token_urlsafe(32)
+    return token
+
+{%- else %}
+"""CSRF protection - authentication not enabled."""
+{%- endif %}