fastapi-basekit 0.2.1__tar.gz → 0.3.1__tar.gz

fastapi_basekit-0.3.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.1
+Name: fastapi-basekit
+Version: 0.3.1
+Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
+Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mundobien2025/fastapi-basekit
+Project-URL: Repository, https://github.com/mundobien2025/fastapi-basekit
+Project-URL: Issues, https://github.com/mundobien2025/fastapi-basekit/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.116.1
+Requires-Dist: pydantic<3,>=2.13.0
+Requires-Dist: fastapi-restful[all]>=0.6.0
+Requires-Dist: pyjwt>=2.12.1
+Provides-Extra: beanie
+Requires-Dist: beanie<3,>=2.0; extra == "beanie"
+Provides-Extra: sqlalchemy
+Requires-Dist: SQLAlchemy[asyncio]<3,>=2.0.30; extra == "sqlalchemy"
+Requires-Dist: psycopg2>=2.9.0; extra == "sqlalchemy"
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.37; extra == "sqlmodel"
+Provides-Extra: init
+Requires-Dist: cookiecutter>=2.5.0; extra == "init"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.10; extra == "docs"
+Requires-Dist: mike>=2.1.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: beanie<3,>=2.0; extra == "all"
+Requires-Dist: SQLAlchemy[asyncio]<3,>=2.0.30; extra == "all"
+Requires-Dist: psycopg2>=2.9.0; extra == "all"
+Requires-Dist: sqlmodel>=0.0.37; extra == "all"
+Requires-Dist: cookiecutter>=2.5.0; extra == "all"
+Requires-Dist: mkdocs>=1.6.0; extra == "all"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "all"
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "all"
+
+<div align="center">
+
+<img src="docs/assets/logo-mark.svg" width="120" alt="fastapi-basekit">
+
+# fastapi-basekit
+
+**FastAPI toolkit con repos, services y controllers listos para producción.**
+**Multi-ORM · CLI scaffolder · plugin Claude Code.**
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=009485&logo=pypi&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![Python](https://img.shields.io/badge/python-3.11+-2c5282?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-c41616?style=flat-square)](https://www.sqlalchemy.org/)
+[![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb&logoColor=white)](https://beanie-odm.dev/)
+[![License](https://img.shields.io/badge/license-MIT-009485?style=flat-square)](./LICENSE)
+
+[**Docs**](https://mundobien2025.github.io/fastapi-basekit) ·
+[**PyPI**](https://pypi.org/project/fastapi-basekit/) ·
+[**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) ·
+[**Changelog**](./CHANGELOG.md)
+
+</div>
+
+---
+
+## Quickstart
+
+```bash
+pip install fastapi-basekit[init]
+basekit init                                    # cookiecutter prompts
+cd <project_slug>
+cp .env.example .env
+make up-d
+make migrate-create && make migrate-up
+make seed
+```
+
+Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`.
+
+## ¿Qué incluye?
+
+- **Repository / Service / Controller** base async para SQLAlchemy 2.0, SQLModel y Beanie
+- **Paginación, filtrado, búsqueda, ordenamiento** vía query string out-of-the-box
+- **JWT middleware** + `BasePermission` classes + soft-delete
+- **`basekit init`** — scaffolder cookiecutter (multi-ORM, multi-DB, redis, s3, license)
+- **Plugin Claude Code** — la skill `fastapi-basekit-crud` enseña el patrón a Claude
+
+## Documentación
+
+**[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
+
+| Sección | Contenido |
+|---|---|
+| [Primeros pasos](https://mundobien2025.github.io/fastapi-basekit/getting-started/installation) | Instalación, `basekit init`, primer CRUD |
+| [Guía de usuario](https://mundobien2025.github.io/fastapi-basekit/user-guide/controllers) | Controllers, services, repositories, paginación, filtros |
+| [Avanzado](https://mundobien2025.github.io/fastapi-basekit/advanced/permissions) | Permisos, soft-delete, logging, performance |
+| [Referencia API](https://mundobien2025.github.io/fastapi-basekit/api-reference/base-controller) | Docstrings de `BaseController`, `BaseService`, `BaseRepository`, `Schemas` |
+| [Ejemplos](https://mundobien2025.github.io/fastapi-basekit/examples/basic-crud) | CRUD básico, filtros complejos, relaciones, auth |
+
+## Como plugin de Claude Code
+
+```bash
+/plugin marketplace add https://github.com/mundobien2025/fastapi-basekit
+/plugin install fastapi-basekit
+/plugin list
+```
+
+Luego pide: *"Crea el recurso `Invoice` con CRUD completo"* — Claude usa la skill automáticamente.
+
+## Instalación por ORM
+
+```bash
+pip install fastapi-basekit[sqlalchemy]   # Postgres / MySQL / SQLite
+pip install fastapi-basekit[beanie]       # MongoDB
+pip install fastapi-basekit[sqlmodel]
+pip install fastapi-basekit[init]         # solo scaffolder
+pip install fastapi-basekit[all]          # todo
+```
+
+## Contribuir
+
+PRs bienvenidos. Setup local en [docs/contributing](https://mundobien2025.github.io/fastapi-basekit/contributing).
+
+Mantenedores: [`RELEASING.md`](./RELEASING.md) tiene release flow, CI/CD, mike y troubleshooting.
+
+## Licencia
+
+[MIT](./LICENSE) — © Jerson Moreno

fastapi_basekit-0.3.1/README.md

@@ -0,0 +1,88 @@
+<div align="center">
+
+<img src="docs/assets/logo-mark.svg" width="120" alt="fastapi-basekit">
+
+# fastapi-basekit
+
+**FastAPI toolkit con repos, services y controllers listos para producción.**
+**Multi-ORM · CLI scaffolder · plugin Claude Code.**
+
+[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=009485&logo=pypi&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![Python](https://img.shields.io/badge/python-3.11+-2c5282?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-c41616?style=flat-square)](https://www.sqlalchemy.org/)
+[![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb&logoColor=white)](https://beanie-odm.dev/)
+[![License](https://img.shields.io/badge/license-MIT-009485?style=flat-square)](./LICENSE)
+
+[**Docs**](https://mundobien2025.github.io/fastapi-basekit) ·
+[**PyPI**](https://pypi.org/project/fastapi-basekit/) ·
+[**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) ·
+[**Changelog**](./CHANGELOG.md)
+
+</div>
+
+---
+
+## Quickstart
+
+```bash
+pip install fastapi-basekit[init]
+basekit init                                    # cookiecutter prompts
+cd <project_slug>
+cp .env.example .env
+make up-d
+make migrate-create && make migrate-up
+make seed
+```
+
+Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`.
+
+## ¿Qué incluye?
+
+- **Repository / Service / Controller** base async para SQLAlchemy 2.0, SQLModel y Beanie
+- **Paginación, filtrado, búsqueda, ordenamiento** vía query string out-of-the-box
+- **JWT middleware** + `BasePermission` classes + soft-delete
+- **`basekit init`** — scaffolder cookiecutter (multi-ORM, multi-DB, redis, s3, license)
+- **Plugin Claude Code** — la skill `fastapi-basekit-crud` enseña el patrón a Claude
+
+## Documentación
+
+**[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
+
+| Sección | Contenido |
+|---|---|
+| [Primeros pasos](https://mundobien2025.github.io/fastapi-basekit/getting-started/installation) | Instalación, `basekit init`, primer CRUD |
+| [Guía de usuario](https://mundobien2025.github.io/fastapi-basekit/user-guide/controllers) | Controllers, services, repositories, paginación, filtros |
+| [Avanzado](https://mundobien2025.github.io/fastapi-basekit/advanced/permissions) | Permisos, soft-delete, logging, performance |
+| [Referencia API](https://mundobien2025.github.io/fastapi-basekit/api-reference/base-controller) | Docstrings de `BaseController`, `BaseService`, `BaseRepository`, `Schemas` |
+| [Ejemplos](https://mundobien2025.github.io/fastapi-basekit/examples/basic-crud) | CRUD básico, filtros complejos, relaciones, auth |
+
+## Como plugin de Claude Code
+
+```bash
+/plugin marketplace add https://github.com/mundobien2025/fastapi-basekit
+/plugin install fastapi-basekit
+/plugin list
+```
+
+Luego pide: *"Crea el recurso `Invoice` con CRUD completo"* — Claude usa la skill automáticamente.
+
+## Instalación por ORM
+
+```bash
+pip install fastapi-basekit[sqlalchemy]   # Postgres / MySQL / SQLite
+pip install fastapi-basekit[beanie]       # MongoDB
+pip install fastapi-basekit[sqlmodel]
+pip install fastapi-basekit[init]         # solo scaffolder
+pip install fastapi-basekit[all]          # todo
+```
+
+## Contribuir
+
+PRs bienvenidos. Setup local en [docs/contributing](https://mundobien2025.github.io/fastapi-basekit/contributing).
+
+Mantenedores: [`RELEASING.md`](./RELEASING.md) tiene release flow, CI/CD, mike y troubleshooting.
+
+## Licencia
+
+[MIT](./LICENSE) — © Jerson Moreno

{fastapi_basekit-0.2.1 → fastapi_basekit-0.3.1}/fastapi_basekit/aio/beanie/repository/base.py

@@ -2,9 +2,9 @@ from typing import Any, Dict, List, Optional, Type, Union
 from typing import get_args, get_origin
 import re
 
-from bson import ObjectId, Link
+from bson import ObjectId
 from pydantic import BaseModel
-from beanie import Document
+from beanie import Document, Link
 from beanie.odm.queries.find import FindMany
 from beanie.operators import Or, RegEx
 
@@ -154,18 +154,42 @@ class BaseRepository:
 
         raw_filters: Dict[str, Any] = {}
 
+        def _coerce_objectid(value: Any) -> Any:
+            """str/UUID → ObjectId para queries Mongo sobre Link.id."""
+            if isinstance(value, ObjectId):
+                return value
+            if isinstance(value, str):
+                try:
+                    return ObjectId(value)
+                except Exception:
+                    return value
+            return value
+
         for k, v in (filters or {}).items():
             # MongoDB-style keys (dot-notation like "user.$id" or operators like "$or")
             # cannot be resolved via hasattr — pass them as a raw dict to find()
             if "." in k or k.startswith("$"):
                 raw_filters[k] = v
-            elif hasattr(self.model, k):
-                field_attr = getattr(self.model, k)
+                continue
 
+            if hasattr(self.model, k):
+                field_attr = getattr(self.model, k)
                 if _is_link_field(k):
-                    exprs.append(field_attr.id == v)
+                    exprs.append(field_attr.id == _coerce_objectid(v))
                 else:
                     exprs.append(field_attr == v)
+                continue
+
+            # `<field>_id` alias para Link fields. Permite filtros con
+            # `customer_id`, `user_id`, etc. sin que el caller deba conocer
+            # la sintaxis Mongo nested. Sólo se activa si <field> existe en
+            # el modelo y es un Link[X].
+            if k.endswith("_id"):
+                base = k[:-3]
+                if hasattr(self.model, base) and _is_link_field(base):
+                    field_attr = getattr(self.model, base)
+                    exprs.append(field_attr.id == _coerce_objectid(v))
+                    continue
 
         # Raw MongoDB filters go first so Beanie processes them as a dict condition
         query_args: list = ([raw_filters] if raw_filters else []) + exprs

{fastapi_basekit-0.2.1 → fastapi_basekit-0.3.1}/fastapi_basekit/aio/sqlalchemy/__init__.py

@@ -1,6 +1,7 @@
-__all__ = ["repository", "service", "controller"]
 from .controller.base import SQLAlchemyBaseController
+from .session import make_session_lifecycle
 
 __all__ = [
     "SQLAlchemyBaseController",
+    "make_session_lifecycle",
 ]

{fastapi_basekit-0.2.1 → fastapi_basekit-0.3.1}/fastapi_basekit/aio/sqlalchemy/service/base.py

@@ -10,7 +10,14 @@ from ....exceptions.api_exceptions import (
 
 
 class BaseService:
-    """Servicio base para SQLAlchemy AsyncSession."""
+    """Servicio base para SQLAlchemy AsyncSession.
+
+    Regla del proyecto: los servicios NO deben llamar `session.flush()`,
+    `session.commit()` ni `session.refresh()`. El flush vive en
+    `BaseRepository.create / update`; el commit/rollback único por
+    request lo gestiona el lifecycle creado con
+    `fastapi_basekit.aio.sqlalchemy.make_session_lifecycle`.
+    """
 
     repository: BaseRepository
     search_fields: List[str] = []

fastapi_basekit-0.3.1/fastapi_basekit/aio/sqlalchemy/session.py

@@ -0,0 +1,67 @@
+"""Reusable async SQLAlchemy session lifecycle.
+
+Single commit / single rollback per request. Optional hooks fire after
+commit (success) or rollback (error) so callers can attach logging,
+metrics, sentry, retries, etc. without coupling the lifecycle to any
+specific telemetry stack.
+
+Usage:
+
+    from fastapi_basekit.aio.sqlalchemy.session import make_session_lifecycle
+    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+    engine = create_async_engine(DATABASE_URL)
+    SessionFactory = async_sessionmaker(engine, autoflush=False, expire_on_commit=False)
+
+    async def on_error(exc, session):
+        logger.exception("rollback", exc_info=exc)
+
+    get_db = make_session_lifecycle(SessionFactory, on_error=on_error)
+
+    # then in routes: ... session: AsyncSession = Depends(get_db)
+
+Rule of thumb for callers:
+- Services SHOULD NOT call session.flush / session.commit / session.refresh.
+- Repositories own flush via BaseRepository.create / update.
+- get_db owns the single commit (success) and rollback (error).
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import Optional
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+ErrorHook = Callable[[Exception, AsyncSession], Awaitable[None]]
+SuccessHook = Callable[[AsyncSession], Awaitable[None]]
+
+
+def make_session_lifecycle(
+    session_factory: async_sessionmaker[AsyncSession],
+    *,
+    on_success: Optional[SuccessHook] = None,
+    on_error: Optional[ErrorHook] = None,
+) -> Callable[[], AsyncGenerator[AsyncSession, None]]:
+    """Return an async generator dependency that owns the request session.
+
+    The returned callable yields a session, commits on success, rolls back
+    on error, and invokes optional hooks. Hooks must not raise — wrap them
+    in try/except at the call site if their failure should not poison the
+    request.
+    """
+
+    async def get_db() -> AsyncGenerator[AsyncSession, None]:
+        async with session_factory() as session:
+            try:
+                yield session
+                await session.commit()
+                if on_success is not None:
+                    await on_success(session)
+            except Exception as exc:
+                await session.rollback()
+                if on_error is not None:
+                    await on_error(exc, session)
+                raise
+
+    return get_db

fastapi_basekit-0.3.1/fastapi_basekit/cli/__init__.py

@@ -0,0 +1,5 @@
+"""basekit CLI — entry point for `basekit init`."""
+
+from fastapi_basekit.cli.main import main
+
+__all__ = ["main"]

fastapi_basekit-0.3.1/fastapi_basekit/cli/main.py

@@ -0,0 +1,112 @@
+"""basekit CLI entry point.
+
+Usage:
+    basekit init                # interactive cookiecutter prompts
+    basekit init --no-input     # use defaults (good for CI / testing)
+    basekit init -o /path       # output dir
+    basekit init --extra-context key=value
+    basekit version
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib import metadata
+from pathlib import Path
+from typing import Sequence
+
+
+def _template_dir() -> Path:
+    return Path(__file__).resolve().parent.parent / "templates" / "project"
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    try:
+        from cookiecutter.main import cookiecutter
+    except ImportError:
+        print(
+            "Error: cookiecutter not installed. Install with:\n"
+            "    pip install fastapi-basekit[init]\n"
+            "or  pip install cookiecutter",
+            file=sys.stderr,
+        )
+        return 1
+
+    extra_context: dict[str, str] = {}
+    for kv in args.extra_context or []:
+        if "=" not in kv:
+            print(f"Bad --extra-context value (expected key=value): {kv}", file=sys.stderr)
+            return 2
+        k, v = kv.split("=", 1)
+        extra_context[k.strip()] = v.strip()
+
+    try:
+        cookiecutter(
+            template=str(_template_dir()),
+            no_input=args.no_input,
+            output_dir=args.output_dir,
+            extra_context=extra_context,
+            overwrite_if_exists=args.overwrite,
+        )
+    except Exception as exc:  # pragma: no cover - cookiecutter raises various
+        print(f"basekit init failed: {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+def _cmd_version(_: argparse.Namespace) -> int:
+    try:
+        v = metadata.version("fastapi-basekit")
+    except metadata.PackageNotFoundError:  # pragma: no cover
+        v = "unknown"
+    print(f"fastapi-basekit {v}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="basekit",
+        description="fastapi-basekit project scaffolder.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    init = sub.add_parser("init", help="Scaffold a new project from the basekit template.")
+    init.add_argument(
+        "-o",
+        "--output-dir",
+        default=".",
+        help="Where to write the new project (default: current directory).",
+    )
+    init.add_argument(
+        "--no-input",
+        action="store_true",
+        help="Skip interactive prompts; use cookiecutter.json defaults.",
+    )
+    init.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite the output directory if it already exists.",
+    )
+    init.add_argument(
+        "--extra-context",
+        action="append",
+        metavar="KEY=VALUE",
+        help="Override one cookiecutter variable; repeatable.",
+    )
+    init.set_defaults(func=_cmd_init)
+
+    version = sub.add_parser("version", help="Print the installed version.")
+    version.set_defaults(func=_cmd_version)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/cookiecutter.json

@@ -0,0 +1,19 @@
+{
+    "project_name": "My FastAPI Service",
+    "project_slug": "{{ cookiecutter.project_name.lower()|replace(' ', '_')|replace('-', '_') }}",
+    "package_name": "{{ cookiecutter.project_slug }}",
+    "description": "Backend API built with fastapi-basekit",
+    "author_name": "Your Name",
+    "author_email": "you@example.com",
+    "python_version": "3.12",
+    "orm": ["sqlalchemy", "beanie"],
+    "database": ["postgres", "mariadb", "sqlite", "mongodb"],
+    "server": ["uvicorn", "gunicorn"],
+    "cache": ["none", "redis"],
+    "background_tasks": ["none", "arq"],
+    "bucket": ["none", "s3"],
+    "include_alembic": ["yes", "no"],
+    "license": ["MIT", "Apache-2.0", "GPL-3.0", "Proprietary"],
+    "include_docker": ["yes", "no"],
+    "_extensions": ["jinja2.ext.do"]
+}

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/hooks/post_gen_project.py

@@ -0,0 +1,51 @@
+"""Cleanup files that aren't needed for the chosen options."""
+
+import os
+import shutil
+from pathlib import Path
+
+ORM = "{{ cookiecutter.orm }}"
+DB = "{{ cookiecutter.database }}"
+INCLUDE_ALEMBIC = "{{ cookiecutter.include_alembic }}" == "yes"
+INCLUDE_DOCKER = "{{ cookiecutter.include_docker }}" == "yes"
+CACHE = "{{ cookiecutter.cache }}"
+BUCKET = "{{ cookiecutter.bucket }}"
+
+PROJECT_DIR = Path(os.getcwd())
+
+
+def rm(path: str) -> None:
+    p = PROJECT_DIR / path
+    if p.is_dir():
+        shutil.rmtree(p, ignore_errors=True)
+    elif p.exists():
+        p.unlink()
+
+
+# 1. Beanie projects don't use alembic
+if ORM == "beanie" or not INCLUDE_ALEMBIC:
+    rm("alembic")
+    rm("alembic.ini")
+
+# 2. Docker is opt-out
+if not INCLUDE_DOCKER:
+    rm("docker-compose.yml")
+    rm("Dockerfile")
+
+# 3. Print next steps
+print(
+    f"\n✓ Project scaffolded at {PROJECT_DIR}\n"
+    f"  ORM      : {ORM}\n"
+    f"  Database : {DB}\n"
+    f"  Cache    : {CACHE}\n"
+    f"  Bucket   : {BUCKET}\n"
+    f"  Alembic  : {'yes' if INCLUDE_ALEMBIC and ORM != 'beanie' else 'no'}\n"
+    f"  Docker   : {'yes' if INCLUDE_DOCKER else 'no'}\n"
+    f"\nNext steps:\n"
+    f"  cd {PROJECT_DIR.name}\n"
+    f"  cp .env.example .env       # edit values\n"
+    + ("  make up                    # start containers\n" if INCLUDE_DOCKER else "  pip install -r requirements.txt\n  uvicorn app.main:app --reload\n")
+    + (f"  make migrate-create        # generate baseline alembic\n  make migrate-up\n" if ORM != 'beanie' and INCLUDE_ALEMBIC else "")
+    + f"  make seed                  # seed admin user\n"
+    f"\nVisit http://localhost:8000/docs\n"
+)

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/hooks/pre_gen_project.py

@@ -0,0 +1,32 @@
+"""Validate cookiecutter inputs before scaffolding."""
+
+import re
+import sys
+
+slug = "{{ cookiecutter.project_slug }}"
+orm = "{{ cookiecutter.orm }}"
+db = "{{ cookiecutter.database }}"
+
+# 1. Slug must be a valid Python identifier
+if not re.match(r"^[a-z][a-z0-9_]*$", slug):
+    print(
+        f"ERROR: project_slug '{slug}' is invalid. "
+        "Must start with a lowercase letter and contain only [a-z0-9_].",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+# 2. ORM ↔ database compatibility
+if orm == "beanie" and db != "mongodb":
+    print(
+        f"ERROR: orm=beanie requires database=mongodb (got '{db}').",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+if orm in ("sqlalchemy", "sqlmodel") and db == "mongodb":
+    print(
+        f"ERROR: orm={orm} requires a SQL database (postgres/mariadb/sqlite), got '{db}'.",
+        file=sys.stderr,
+    )
+    sys.exit(1)

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/{{cookiecutter.project_slug}}/.env.example

@@ -0,0 +1,40 @@
+PROJECT_NAME={{ cookiecutter.project_name }}
+VERSION=0.1.0
+DEBUG=true
+ENVIRONMENT=local
+
+SECRET_KEY=change-me-in-production
+JWT_SECRET=change-me-in-production
+JWT_ALGORITHM=HS256
+JWT_EXPIRE_SECONDS=3600
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+REFRESH_TOKEN_EXPIRE_DAYS=7
+
+{% if cookiecutter.orm == "beanie" -%}
+DATABASE_URL=mongodb://root:secret@db:27017
+DATABASE_NAME={{ cookiecutter.package_name }}
+{%- elif cookiecutter.database == "postgres" -%}
+DATABASE_URL=postgresql+asyncpg://{{ cookiecutter.package_name }}:secret@db:5432/{{ cookiecutter.package_name }}
+{%- elif cookiecutter.database == "mariadb" -%}
+DATABASE_URL=mysql+aiomysql://{{ cookiecutter.package_name }}:secret@db:3306/{{ cookiecutter.package_name }}
+{%- elif cookiecutter.database == "sqlite" -%}
+DATABASE_URL=sqlite+aiosqlite:///./{{ cookiecutter.package_name }}.db
+{%- endif %}
+
+{% if cookiecutter.cache == "redis" -%}
+REDIS_HOST=redis
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_PASSWORD=
+{%- endif %}
+
+{% if cookiecutter.bucket == "s3" -%}
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION_NAME=us-east-1
+AWS_S3_BUCKET_NAME=
+{%- endif %}
+
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=ChangeMe2026!
+ADMIN_NAME=Platform Admin

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/{{cookiecutter.project_slug}}/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+*.sqlite3
+uploads/

fastapi_basekit-0.3.1/fastapi_basekit/templates/project/{{cookiecutter.project_slug}}/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:{{ cookiecutter.python_version }}-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+{% if cookiecutter.server == "gunicorn" -%}
+CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "--workers", "4"]
+{%- else -%}
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+{%- endif %}