fastapi-spawn 0.1.0__py3-none-any.whl

fastapi_spawn/templates/app/api/v1/health.py.j2

@@ -0,0 +1,40 @@
+"""Health check endpoints — /health, /readiness, /liveness."""
+
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter(prefix="/health")
+
+_start_time = time.time()
+
+
+class HealthResponse(BaseModel):
+    status: str
+    uptime_seconds: float
+    version: str = "0.1.0"
+    service: str = "{{ project_name }}"
+
+
+@router.get("", response_model=HealthResponse, summary="Basic health check")
+async def health() -> HealthResponse:
+    """Returns service status and uptime."""
+    return HealthResponse(
+        status="ok",
+        uptime_seconds=round(time.time() - _start_time, 2),
+    )
+
+
+@router.get("/readiness", summary="Readiness probe (Kubernetes)")
+async def readiness() -> dict:
+    """Indicates whether the service is ready to accept traffic."""
+    return {"status": "ready"}
+
+
+@router.get("/liveness", summary="Liveness probe (Kubernetes)")
+async def liveness() -> dict:
+    """Indicates whether the service process is alive."""
+    return {"status": "alive"}

fastapi_spawn/templates/app/core/ai.py.j2

@@ -0,0 +1,76 @@
+"""AI client utilities for {{ project_name }}."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+{% if ai == "openai" %}
+from openai import AsyncOpenAI
+
+from app.core.config import settings
+
+
+@lru_cache
+def get_openai_client() -> AsyncOpenAI:
+    """Return a cached AsyncOpenAI client."""
+    return AsyncOpenAI(
+        api_key=settings.OPENAI_API_KEY,
+        base_url=settings.OPENAI_BASE_URL or None,  # None = default api.openai.com
+    )
+
+
+async def chat_completion(
+    messages: list[dict],
+    model: str | None = None,
+    temperature: float = 0.7,
+    max_tokens: int = 1024,
+) -> str:
+    """Send a chat completion request and return the response text."""
+    client = get_openai_client()
+    response = await client.chat.completions.create(
+        model=model or settings.OPENAI_MODEL,
+        messages=messages,
+        temperature=temperature,
+        max_tokens=max_tokens,
+    )
+    return response.choices[0].message.content or ""
+
+
+async def get_embedding(text: str, model: str | None = None) -> list[float]:
+    """Return an embedding vector for the given text."""
+    client = get_openai_client()
+    response = await client.embeddings.create(
+        model=model or settings.OPENAI_EMBEDDING_MODEL,
+        input=text,
+    )
+    return response.data[0].embedding
+
+{% elif ai == "anthropic" %}
+import anthropic
+
+from app.core.config import settings
+
+
+@lru_cache
+def get_anthropic_client() -> anthropic.AsyncAnthropic:
+    """Return a cached AsyncAnthropic client."""
+    return anthropic.AsyncAnthropic(api_key=settings.ANTHROPIC_API_KEY)
+
+
+async def chat_completion(
+    messages: list[dict],
+    system: str = "You are a helpful assistant.",
+    model: str | None = None,
+    max_tokens: int = 1024,
+) -> str:
+    """Send a message to Claude and return the response text."""
+    client = get_anthropic_client()
+    response = await client.messages.create(
+        model=model or settings.ANTHROPIC_MODEL,
+        max_tokens=max_tokens,
+        system=system,
+        messages=messages,
+    )
+    return response.content[0].text
+
+{% endif %}

fastapi_spawn/templates/app/core/config.py.j2

@@ -0,0 +1,177 @@
+"""Application configuration using Pydantic Settings v2."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # ── App ────────────────────────────────────────────────────────────────
+    APP_NAME: str = "{{ project_name }}"
+    APP_ENV: str = "development"
+    DEBUG: bool = False
+    API_V1_PREFIX: str = "/api/v1"
+    SECRET_KEY: str = "change-me"
+    CORS_ORIGINS: list[str] = ["http://localhost:3000", "http://localhost:8000"]
+
+    @field_validator("CORS_ORIGINS", mode="before")
+    @classmethod
+    def assemble_cors_origins(cls, v: Any) -> list[str]:
+        if isinstance(v, str):
+            return [o.strip() for o in v.split(",")]
+        return v
+
+{% if db == "postgresql" %}
+    # ── PostgreSQL ─────────────────────────────────────────────────────────
+    POSTGRES_USER: str = "postgres"
+    POSTGRES_PASSWORD: str = "postgres"
+    POSTGRES_HOST: str = "localhost"
+    POSTGRES_PORT: str = "5432"
+    POSTGRES_DB: str = "{{ slug }}_db"
+
+    @property
+    def database_url(self) -> str:
+        return (
+            f"postgresql+asyncpg://{self.POSTGRES_USER}:{self.POSTGRES_PASSWORD}"
+            f"@{self.POSTGRES_HOST}:{self.POSTGRES_PORT}/{self.POSTGRES_DB}"
+        )
+
+{% elif db == "mysql" %}
+    # ── MySQL ──────────────────────────────────────────────────────────────
+    MYSQL_USER: str = "root"
+    MYSQL_PASSWORD: str = "mysql"
+    MYSQL_HOST: str = "localhost"
+    MYSQL_PORT: str = "3306"
+    MYSQL_DB: str = "{{ slug }}_db"
+
+    @property
+    def database_url(self) -> str:
+        return (
+            f"mysql+aiomysql://{self.MYSQL_USER}:{self.MYSQL_PASSWORD}"
+            f"@{self.MYSQL_HOST}:{self.MYSQL_PORT}/{self.MYSQL_DB}"
+        )
+
+{% elif db == "sqlite" %}
+    # ── SQLite ─────────────────────────────────────────────────────────────
+    SQLITE_FILE: str = "{{ slug }}.db"
+
+    @property
+    def database_url(self) -> str:
+        return f"sqlite+aiosqlite:///./{self.SQLITE_FILE}"
+
+{% endif %}
+{% if has_mongo %}
+    # ── MongoDB ────────────────────────────────────────────────────────────
+    MONGODB_USER: str = "mongo"
+    MONGODB_PASSWORD: str = "mongo"
+    MONGODB_HOST: str = "localhost"
+    MONGODB_PORT: str = "27017"
+    MONGODB_DB: str = "{{ slug }}_db"
+
+    @property
+    def mongodb_url(self) -> str:
+        if self.MONGODB_USER and self.MONGODB_PASSWORD:
+            return (
+                f"mongodb://{self.MONGODB_USER}:{self.MONGODB_PASSWORD}"
+                f"@{self.MONGODB_HOST}:{self.MONGODB_PORT}"
+            )
+        return f"mongodb://{self.MONGODB_HOST}:{self.MONGODB_PORT}"
+
+{% endif %}
+{% if broker == "redis" or cache == "redis" %}
+    # ── Redis ──────────────────────────────────────────────────────────────
+    REDIS_HOST: str = "localhost"
+    REDIS_PORT: str = "6379"
+    REDIS_PASSWORD: str = ""
+    REDIS_DB: str = "0"
+
+    @property
+    def redis_url(self) -> str:
+        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 broker == "rabbitmq" %}
+    # ── RabbitMQ ───────────────────────────────────────────────────────────
+    RABBITMQ_USER: str = "guest"
+    RABBITMQ_PASSWORD: str = "guest"
+    RABBITMQ_HOST: str = "localhost"
+    RABBITMQ_PORT: str = "5672"
+    RABBITMQ_VHOST: str = "/"
+
+    @property
+    def rabbitmq_url(self) -> str:
+        return (
+            f"amqp://{self.RABBITMQ_USER}:{self.RABBITMQ_PASSWORD}"
+            f"@{self.RABBITMQ_HOST}:{self.RABBITMQ_PORT}/{self.RABBITMQ_VHOST}"
+        )
+
+{% endif %}
+{% if broker == "kafka" %}
+    # ── Kafka ──────────────────────────────────────────────────────────────
+    KAFKA_HOST: str = "localhost"
+    KAFKA_PORT: str = "9092"
+
+    @property
+    def kafka_bootstrap_servers(self) -> str:
+        return f"{self.KAFKA_HOST}:{self.KAFKA_PORT}"
+
+{% endif %}
+{% if has_s3 %}
+    # ── AWS S3 ─────────────────────────────────────────────────────────────
+    AWS_ACCESS_KEY_ID: str = ""
+    AWS_SECRET_ACCESS_KEY: str = ""
+    AWS_REGION: str = "us-east-1"
+    AWS_S3_BUCKET: str = "{{ slug }}-bucket"
+    AWS_S3_ENDPOINT_URL: str = ""  # Override for MinIO / LocalStack
+
+{% endif %}
+{% if has_auth %}
+    # ── Auth ───────────────────────────────────────────────────────────────
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+    ALGORITHM: str = "HS256"
+
+{% endif %}
+{% if ai == "openai" %}
+    # ── OpenAI ─────────────────────────────────────────────────────────────
+    OPENAI_API_KEY: str = ""
+    OPENAI_MODEL: str = "gpt-4o"
+    OPENAI_EMBEDDING_MODEL: str = "text-embedding-3-small"
+    OPENAI_BASE_URL: str = ""  # Override for Azure OpenAI, LM Studio, local endpoints
+
+{% elif ai == "anthropic" %}
+    # ── Anthropic ──────────────────────────────────────────────────────────
+    ANTHROPIC_API_KEY: str = ""
+    ANTHROPIC_MODEL: str = "claude-3-5-sonnet-20241022"
+
+{% endif %}
+
+    # ── Helpers ────────────────────────────────────────────────────────────
+    @property
+    def is_development(self) -> bool:
+        return self.APP_ENV == "development"
+
+    @property
+    def is_production(self) -> bool:
+        return self.APP_ENV == "production"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+
+
+settings: Settings = get_settings()

fastapi_spawn/templates/app/core/exceptions.py.j2

@@ -0,0 +1,43 @@
+"""Global exception handlers."""
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+
+class AppError(Exception):
+    """Base application error."""
+    def __init__(self, message: str, status_code: int = 400) -> None:
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str = "Resource") -> None:
+        super().__init__(f"{resource} not found.", status_code=404)
+
+
+class UnauthorizedError(AppError):
+    def __init__(self, detail: str = "Not authenticated.") -> None:
+        super().__init__(detail, status_code=401)
+
+
+class ForbiddenError(AppError):
+    def __init__(self, detail: str = "Permission denied.") -> None:
+        super().__init__(detail, status_code=403)
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(AppError)
+    async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"detail": exc.message, "type": type(exc).__name__},
+        )
+
+    @app.exception_handler(Exception)
+    async def unhandled_error_handler(request: Request, exc: Exception) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={"detail": "An unexpected error occurred.", "type": "InternalServerError"},
+        )

fastapi_spawn/templates/app/core/logging.py.j2

@@ -0,0 +1,70 @@
+"""Structured logging configuration."""
+
+import logging
+import sys
+
+{% if log_lib == "loguru" %}
+from loguru import logger
+
+
+def configure_logging() -> None:
+    """Configure loguru as the application logger."""
+    logger.remove()
+    logger.add(
+        sys.stdout,
+        colorize=True,
+        format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+        level="DEBUG",
+        backtrace=True,
+        diagnose=True,
+    )
+
+    # Intercept standard library logging
+    class InterceptHandler(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            try:
+                level = logger.level(record.levelname).name
+            except ValueError:
+                level = record.levelno  # type: ignore[assignment]
+            frame, depth = sys._getframe(6), 6
+            while frame and frame.f_code.co_filename == logging.__file__:
+                frame = frame.f_back  # type: ignore[assignment]
+                depth += 1
+            logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+    logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+{% elif log_lib == "structlog" %}
+import structlog
+
+
+def configure_logging() -> None:
+    """Configure structlog as the application logger."""
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.stdlib.filter_by_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.dev.ConsoleRenderer(),
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+{% else %}
+def configure_logging() -> None:
+    """Configure standard library logging."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s | %(levelname)-8s | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        stream=sys.stdout,
+    )
+{% endif %}

fastapi_spawn/templates/app/core/security.py.j2

@@ -0,0 +1,42 @@
+"""Security utilities — JWT token creation and verification."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from app.core.config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def create_access_token(subject: str | Any, expires_delta: timedelta | None = None) -> str:
+    expire = datetime.now(timezone.utc) + (
+        expires_delta or timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    )
+    payload = {"sub": str(subject), "exp": expire, "type": "access"}
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def create_refresh_token(subject: str | Any) -> str:
+    expire = datetime.now(timezone.utc) + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
+    payload = {"sub": str(subject), "exp": expire, "type": "refresh"}
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def decode_token(token: str) -> dict[str, Any]:
+    try:
+        return jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+    except JWTError as exc:
+        raise ValueError("Invalid or expired token.") from exc

fastapi_spawn/templates/app/core/storage.py.j2

@@ -0,0 +1,73 @@
+"""AWS S3 storage utilities for {{ project_name }}."""
+
+from __future__ import annotations
+
+import boto3
+from botocore.exceptions import ClientError
+
+from app.core.config import settings
+
+
+def _get_client():
+    """Return a configured boto3 S3 client."""
+    kwargs = {
+        "region_name": settings.AWS_REGION,
+        "aws_access_key_id": settings.AWS_ACCESS_KEY_ID,
+        "aws_secret_access_key": settings.AWS_SECRET_ACCESS_KEY,
+    }
+    if settings.AWS_S3_ENDPOINT_URL:
+        kwargs["endpoint_url"] = settings.AWS_S3_ENDPOINT_URL  # MinIO / LocalStack
+    return boto3.client("s3", **kwargs)
+
+
+def upload_file(file_path: str, object_key: str, bucket: str | None = None) -> str:
+    """
+    Upload a local file to S3.
+    Returns the public object key on success.
+    """
+    bucket = bucket or settings.AWS_S3_BUCKET
+    client = _get_client()
+    client.upload_file(file_path, bucket, object_key)
+    return object_key
+
+
+def upload_fileobj(file_obj, object_key: str, bucket: str | None = None, content_type: str = "application/octet-stream") -> str:
+    """Upload a file-like object to S3."""
+    bucket = bucket or settings.AWS_S3_BUCKET
+    client = _get_client()
+    client.upload_fileobj(
+        file_obj,
+        bucket,
+        object_key,
+        ExtraArgs={"ContentType": content_type},
+    )
+    return object_key
+
+
+def generate_presigned_url(object_key: str, expires_in: int = 3600, bucket: str | None = None) -> str:
+    """Generate a pre-signed URL for temporary read access."""
+    bucket = bucket or settings.AWS_S3_BUCKET
+    client = _get_client()
+    return client.generate_presigned_url(
+        "get_object",
+        Params={"Bucket": bucket, "Key": object_key},
+        ExpiresIn=expires_in,
+    )
+
+
+def delete_file(object_key: str, bucket: str | None = None) -> None:
+    """Delete an object from S3."""
+    bucket = bucket or settings.AWS_S3_BUCKET
+    client = _get_client()
+    client.delete_object(Bucket=bucket, Key=object_key)
+
+
+def file_exists(object_key: str, bucket: str | None = None) -> bool:
+    """Check if an object exists in S3."""
+    bucket = bucket or settings.AWS_S3_BUCKET
+    client = _get_client()
+    try:
+        client.head_object(Bucket=bucket, Key=object_key)
+        return True
+    except ClientError:
+        return False

fastapi_spawn/templates/app/db/session.py.j2

@@ -0,0 +1,84 @@
+"""Database session factory."""
+
+from __future__ import annotations
+
+{% if has_relational_db and orm == "sqlalchemy" %}
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+
+from app.core.config import settings
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+    pool_size=10,
+    max_overflow=20,
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autoflush=False,
+    autocommit=False,
+)
+
+
+class Base(DeclarativeBase):
+    """Base class for all SQLAlchemy ORM models."""
+    pass
+
+
+async def get_session() -> AsyncSession:  # type: ignore[return]
+    """FastAPI dependency that yields an async DB session."""
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+        finally:
+            await session.close()
+
+{% elif has_relational_db and orm == "tortoise" %}
+from tortoise import Tortoise
+
+from app.core.config import settings
+
+TORTOISE_ORM = {
+    "connections": {"default": settings.database_url},
+    "apps": {
+        "models": {
+            "models": ["app.models", "aerich.models"],
+            "default_connection": "default",
+        },
+    },
+}
+
+
+async def init_db() -> None:
+    await Tortoise.init(config=TORTOISE_ORM)
+    await Tortoise.generate_schemas()
+
+
+async def close_db() -> None:
+    await Tortoise.close_connections()
+
+{% elif has_mongo and orm == "beanie" %}
+import motor.motor_asyncio
+from beanie import init_beanie
+
+from app.core.config import settings
+
+
+async def init_db() -> None:
+    client = motor.motor_asyncio.AsyncIOMotorClient(settings.mongodb_url)
+    database = client[settings.MONGODB_DB]
+    # TODO: Add your Beanie Document models to the list below
+    await init_beanie(database=database, document_models=[])
+
+{% else %}
+# No database configured. Add your connection logic here.
+{% endif %}

fastapi_spawn/templates/app/main.py.j2

@@ -0,0 +1,71 @@
+"""FastAPI application entrypoint for {{ project_name }}."""
+
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import ORJSONResponse
+
+from app.api.v1 import health
+{% if has_auth %}
+from app.api.v1 import auth
+{% endif %}
+from app.core.config import settings
+from app.core.exceptions import register_exception_handlers
+from app.core.logging import configure_logging
+
+
+@asynccontextmanager
+async def lifespan(application: FastAPI) -> AsyncGenerator[None, None]:
+    """Manage application startup and shutdown lifecycle."""
+    configure_logging()
+{% if has_relational_db and orm == "sqlalchemy" %}
+    from app.db.session import engine, Base
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+{% endif %}
+{% if has_mongo and orm == "beanie" %}
+    from app.db.session import init_db
+    await init_db()
+{% endif %}
+    yield
+{% if has_relational_db and orm == "sqlalchemy" %}
+    await engine.dispose()
+{% endif %}
+
+
+def create_application() -> FastAPI:
+    application = FastAPI(
+        title=settings.APP_NAME,
+        description="Generated by fastapi-spawn 🚀",
+        version="0.1.0",
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+        default_response_class=ORJSONResponse,
+        lifespan=lifespan,
+    )
+
+    # Middleware
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.CORS_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Exception handlers
+    register_exception_handlers(application)
+
+    # Routers
+    application.include_router(health.router, prefix=settings.API_V1_PREFIX, tags=["Health"])
+{% if has_auth %}
+    application.include_router(auth.router, prefix=settings.API_V1_PREFIX, tags=["Auth"])
+{% endif %}
+
+    return application
+
+
+app = create_application()