paststack 0.1.0__py3-none-any.whl

paststack/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

paststack/banner.py

@@ -0,0 +1,19 @@
+import click
+
+
+def display_banner() -> None:
+    click.echo(
+        r"""
+ /$$$$$$$                       /$$      /$$$$$$   /$$                         /$$      
+| $$__  $$                     | $$     /$$__  $$ | $$                        | $$      
+| $$  \ $$ /$$$$$$   /$$$$$$$ /$$$$$$  | $$  \__//$$$$$$    /$$$$$$   /$$$$$$$| $$   /$$
+| $$$$$$$/|____  $$ /$$_____/|_  $$_/  |  $$$$$$|_  $$_/   |____  $$ /$$_____/| $$  /$$/
+| $$____/  /$$$$$$$|  $$$$$$   | $$     \____  $$ | $$      /$$$$$$$| $$      | $$$$$$/ 
+| $$      /$$__  $$ \____  $$  | $$ /$$ /$$  \ $$ | $$ /$$ /$$__  $$| $$      | $$_  $$ 
+| $$     |  $$$$$$$ /$$$$$$$/  |  $$$$/|  $$$$$$/ |  $$$$/|  $$$$$$$|  $$$$$$$| $$ \  $$
+|__/      \_______/|_______/    \___/   \______/   \___/   \_______/ \_______/|__/  \__/
+                                                                                        
+                                                                                        
+                                                                                        
+"""
+    )

paststack/cli.py

@@ -0,0 +1,353 @@
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from shutil import copyfile, which
+
+import click
+import questionary
+from rich.progress import (
+    BarColumn,
+    Progress,
+    SpinnerColumn,
+    TaskProgressColumn,
+    TextColumn,
+)
+
+from paststack.banner import display_banner
+from paststack.models import Database, Orm, Project
+from paststack.prompts import ask_questions, show_summary
+
+TEMPLATES_ROOT = Path(__file__).resolve().parent / "templates"
+BASE = TEMPLATES_ROOT / "base"
+DATABASE = TEMPLATES_ROOT / "database"
+RATE_LIMITING = TEMPLATES_ROOT / "rate_limiting"
+
+
+def _venv_python(venv_path: Path) -> Path:
+    if sys.platform == "win32":
+        return venv_path / "Scripts" / "python.exe"
+    return venv_path / "bin" / "python"
+
+
+def _database_url(project: Project) -> str:
+    if project.database == Database.NONE:
+        return "sqlite+aiosqlite:///./data/app.db"
+    if project.database == Database.SQLITE:
+        return "sqlite+aiosqlite:///./data/app.db"
+    if project.orm == Orm.SQLMODEL:
+        return "postgresql+asyncpg://app:app@127.0.0.1:5432/app"
+    return "postgresql://app:app@127.0.0.1:5432/app"
+
+
+def _env_database_block(project: Project) -> str:
+    if project.database == Database.NONE:
+        return "# Pas de base de données (DATABASE_URL ignoré)"
+    return f"DATABASE_URL={_database_url(project)}"
+
+
+def _build_extra(project: Project) -> dict[str, str]:
+    extra: dict[str, str] = {
+        "{{ database_url }}": _database_url(project),
+        "{{ env_database_block }}": _env_database_block(project),
+    }
+    if project.rate_limiting:
+        extra["{{ rate_limit_imports }}"] = (
+            "from app.core.rate_limit import setup_rate_limiting\n"
+        )
+        extra["{{ rate_limit_setup }}"] = "setup_rate_limiting(app)\n"
+    else:
+        extra["{{ rate_limit_imports }}"] = ""
+        extra["{{ rate_limit_setup }}"] = ""
+    return extra
+
+
+def _subprocess_env_without_venv() -> dict[str, str]:
+    env = os.environ.copy()
+    env.pop("VIRTUAL_ENV", None)
+    return env
+
+
+def _docker_compose_up_postgres(project_root: Path) -> bool:
+    """Démarre le conteneur Postgres du projet. Retourne False si Docker indisponible ou échec."""
+    if not (project_root / "docker-compose.yml").is_file():
+        click.echo("Aucun docker-compose.yml — impossible de lancer PostgreSQL ici.", err=True)
+        return False
+    if which("docker") is None:
+        click.echo(
+            click.style(
+                "La commande `docker` est introuvable.\n"
+                "→ Installe Docker Desktop : https://www.docker.com/products/docker-desktop/\n"
+                "→ Puis dans le projet : docker compose up -d",
+                fg="red",
+            ),
+            err=True,
+        )
+        return False
+    result = subprocess.run(
+        ["docker", "compose", "up", "-d"],
+        cwd=project_root,
+        capture_output=True,
+        text=True,
+        env=_subprocess_env_without_venv(),
+    )
+    if result.returncode != 0:
+        click.echo(click.style("docker compose up -d a échoué.", fg="red"), err=True)
+        if result.stderr.strip():
+            click.echo(result.stderr, err=True)
+        if result.stdout.strip():
+            click.echo(result.stdout, err=True)
+        click.echo(
+            click.style(
+                "Vérifie que Docker Desktop est démarré (icône baleine active).\n"
+                "Ensuite, à la main : docker compose up -d",
+                fg="yellow",
+            ),
+            err=True,
+        )
+        return False
+    click.echo(click.style("PostgreSQL : conteneur démarré (docker compose up -d).", fg="green"))
+    return True
+
+
+def _uv_extras(project: Project) -> list[str]:
+    extras: list[str] = []
+    if project.database == Database.SQLITE:
+        extras.append(
+            "sqlite-sqlmodel" if project.orm == Orm.SQLMODEL else "sqlite-none"
+        )
+    elif project.database == Database.POSTGRES:
+        extras.append(
+            "postgres-sqlmodel" if project.orm == Orm.SQLMODEL else "postgres-none"
+        )
+    if project.rate_limiting:
+        extras.append("rate-limit")
+    return extras
+
+
+@click.command()
+def main() -> None:
+    try:
+        display_banner()
+        while True:
+            project = ask_questions()
+            show_summary(project)
+            if questionary.confirm("Proceed with project setup ?").unsafe_ask():
+                break
+        setup_project(project)
+    except KeyboardInterrupt:
+        click.echo("\nAborted.")
+
+
+def _create_directories(base: Path, paths: list[tuple[str, ...]]) -> None:
+    for parts in paths:
+        (base / Path(*parts)).mkdir(parents=True, exist_ok=True)
+
+
+def _copy_and_render(
+    template: Path,
+    destination: Path,
+    project: Project,
+    extra: dict[str, str] | None = None,
+) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    copyfile(template, destination)
+    content = destination.read_text(encoding="utf-8")
+    content = content.replace("{{ project_name }}", project.project_name)
+    origins = project.allowed_origins or []
+    content = content.replace("{{ allowed_origins }}", repr(origins))
+    content = content.replace("{{project.allowed_origins}}", repr(origins))
+    content = content.replace("{{ database }}", project.database.value)
+    content = content.replace("{{ orm }}", project.orm.value)
+    for key, value in (extra or {}).items():
+        content = content.replace(key, value)
+    destination.write_text(content, encoding="utf-8")
+
+
+def _copy_template_tree(
+    template_dir: Path,
+    dest_root: Path,
+    project: Project,
+    extra: dict[str, str] | None = None,
+) -> None:
+    if not template_dir.is_dir():
+        return
+    for path in sorted(template_dir.rglob("*")):
+        if path.is_file():
+            rel = path.relative_to(template_dir)
+            _copy_and_render(path, dest_root / rel, project, extra)
+
+
+def setup_project(project: Project) -> None:
+    main_directory = Path(project.project_name).resolve()
+
+    try:
+        main_directory.mkdir()
+    except FileExistsError:
+        click.echo(f"Directory '{main_directory}' already exists.")
+        return
+    except PermissionError:
+        click.echo(f"Permission denied: unable to create '{main_directory}'.")
+        return
+    except OSError as e:
+        click.echo(f"An error occurred: {e}")
+        return
+
+    extra = _build_extra(project)
+    _copy_template_tree(BASE, main_directory, project, extra)
+
+    db_dest = main_directory / "src" / "app" / "database.py"
+
+    match (project.database, project.orm):
+        case (Database.NONE, _):
+            pass
+        case (Database.SQLITE, Orm.NONE):
+            _copy_and_render(
+                DATABASE / "sqlite" / "none" / "database.py", db_dest, project, extra
+            )
+        case (Database.SQLITE, Orm.SQLMODEL):
+            _copy_template_tree(
+                DATABASE / "sqlite" / "sqlmodel",
+                main_directory / "src" / "app",
+                project,
+                extra,
+            )
+        case (Database.POSTGRES, Orm.NONE):
+            _copy_and_render(
+                DATABASE / "postgres" / "none" / "database.py", db_dest, project, extra
+            )
+            _copy_and_render(
+                DATABASE / "postgres" / "docker-compose.yml",
+                main_directory / "docker-compose.yml",
+                project,
+                extra,
+            )
+        case (Database.POSTGRES, Orm.SQLMODEL):
+            _copy_template_tree(
+                DATABASE / "postgres" / "sqlmodel",
+                main_directory / "src" / "app",
+                project,
+                extra,
+            )
+            _copy_and_render(
+                DATABASE / "postgres" / "docker-compose.yml",
+                main_directory / "docker-compose.yml",
+                project,
+                extra,
+            )
+
+    if project.rate_limiting:
+        _copy_template_tree(RATE_LIMITING, main_directory, project, extra)
+
+    venv_path = (main_directory / project.project_name).resolve()
+    py_exe = _venv_python(venv_path).resolve()
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(bar_width=40),
+        TaskProgressColumn(),
+        TextColumn(" "),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+    ) as progress:
+        t_venv = progress.add_task("Création du venv…", total=1)
+        subprocess.run(
+            [sys.executable, "-m", "venv", str(venv_path)],
+            check=True,
+            env=_subprocess_env_without_venv(),
+        )
+        progress.update(t_venv, completed=1)
+
+        if project.run_install:
+            uv_extras = _uv_extras(project)
+            cmd = ["uv", "sync", "-p", str(py_exe)]
+            for e in uv_extras:
+                cmd.append(f"--extra={e}")
+            t_sync = progress.add_task("uv sync (dépendances)…", total=1)
+            subprocess.run(
+                cmd,
+                cwd=main_directory,
+                check=True,
+                env=_subprocess_env_without_venv(),
+            )
+            progress.update(t_sync, completed=1)
+
+    if project.git_z:
+        subprocess.run(["git", "init"], cwd=main_directory, check=True)
+        # --default : config git-z sans wizard interactif (sinon le CLI semble « figé »)
+        result = subprocess.run(
+            ["git", "z", "init", "--default"],
+            cwd=main_directory,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            click.echo(
+                "git z init a échoué (git-z installé ?). "
+                "Voir https://github.com/ejpcmac/git-z",
+                err=True,
+            )
+            if result.stderr:
+                click.echo(result.stderr, err=True)
+    elif project.git:
+        subprocess.run(["git", "init"], cwd=main_directory, check=True)
+
+    env_example = main_directory / ".env.example"
+    env_dest = main_directory / ".env"
+    if env_example.is_file() and not env_dest.is_file():
+        copyfile(env_example, env_dest)
+        click.echo("Fichier .env créé à partir de .env.example.")
+
+    start_uvicorn = project.run_install and questionary.confirm(
+        "Démarrer l’API maintenant (uvicorn --reload) ?",
+        default=True,
+    ).unsafe_ask()
+
+    if start_uvicorn and project.database == Database.POSTGRES:
+        if questionary.confirm(
+            "Lancer PostgreSQL avec Docker (`docker compose up -d`) ?",
+            default=True,
+        ).unsafe_ask():
+            if not _docker_compose_up_postgres(main_directory):
+                start_uvicorn = questionary.confirm(
+                    "Lancer uvicorn quand même ? (l’API échouera si Postgres n’est pas joignable.)",
+                    default=False,
+                ).unsafe_ask()
+            else:
+                time.sleep(2)
+        else:
+            click.echo(
+                click.style(
+                    "Sans conteneur Docker, assure-toi que Postgres tourne déjà "
+                    "(même URL que dans `.env`), sinon le démarrage de l’API échouera.",
+                    fg="yellow",
+                )
+            )
+            start_uvicorn = questionary.confirm(
+                "Lancer uvicorn quand même ?",
+                default=False,
+            ).unsafe_ask()
+
+    if start_uvicorn:
+        click.echo(
+            click.style(
+                "\n→ http://127.0.0.1:8000/docs  (Ctrl+C pour arrêter)\n",
+                fg="green",
+            )
+        )
+        subprocess.run(
+            [
+                "uv",
+                "run",
+                "--python",
+                str(py_exe),
+                "uvicorn",
+                "app.main:app",
+                "--reload",
+                "--app-dir",
+                "src",
+            ],
+            cwd=main_directory,
+            env=_subprocess_env_without_venv(),
+        )

paststack/combinations.py

@@ -0,0 +1,68 @@
+"""Combinaisons valides du générateur — réutilisables par les tests ou d’autres outils."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from paststack.models import Database, Orm, Project
+
+
+def iter_database_orm_rate_limit_triples() -> Iterator[tuple[Database, Orm, bool]]:
+    """Toutes les combinaisons métier valides (SGBD × ORM × rate limiting)."""
+    for rate_limiting in (False, True):
+        yield (Database.NONE, Orm.NONE, rate_limiting)
+
+    for database in (Database.SQLITE, Database.POSTGRES):
+        for orm in (Orm.NONE, Orm.SQLMODEL):
+            for rate_limiting in (False, True):
+                yield (database, orm, rate_limiting)
+
+
+def make_project(
+    database: Database,
+    orm: Orm,
+    *,
+    rate_limiting: bool = False,
+    project_name: str = "generated_app",
+    run_install: bool = False,
+    git: bool = False,
+    git_z: bool = False,
+) -> Project:
+    """Construit un `Project` cohérent (sans base → ORM forcé à none)."""
+    if database == Database.NONE:
+        orm = Orm.NONE
+    return Project(
+        project_name=project_name,
+        package_manager="uv",
+        use_typing=True,
+        use_ruff=True,
+        enable_cors=False,
+        allowed_origins=None,
+        database=database,
+        orm=orm,
+        rate_limiting=rate_limiting,
+        config=True,
+        git=git,
+        git_z=git_z,
+        run_install=run_install,
+    )
+
+
+def iter_all_projects(
+    *,
+    project_name: str = "generated_app",
+    run_install: bool = False,
+) -> Iterator[Project]:
+    """Itère un `Project` par combinaison valide."""
+    for database, orm, rate_limiting in iter_database_orm_rate_limit_triples():
+        yield make_project(
+            database,
+            orm,
+            rate_limiting=rate_limiting,
+            project_name=project_name,
+            run_install=run_install,
+        )
+
+
+def combination_count() -> int:
+    return sum(1 for _ in iter_database_orm_rate_limit_triples())

paststack/models.py

@@ -0,0 +1,30 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class Database(str, Enum):
+    NONE = "none"
+    SQLITE = "sqlite"
+    POSTGRES = "postgres"
+
+
+class Orm(str, Enum):
+    NONE = "none"
+    SQLMODEL = "sqlmodel"
+
+
+class Project(BaseModel):
+    project_name: str
+    package_manager: str
+    use_typing: bool
+    use_ruff: bool
+    enable_cors: bool
+    allowed_origins: list[str] | None = None
+    database: Database
+    orm: Orm
+    rate_limiting: bool
+    config: bool
+    git: bool
+    git_z: bool
+    run_install: bool

paststack/prompts.py

@@ -0,0 +1,92 @@
+import click
+import questionary
+
+from paststack.models import Database, Orm, Project
+
+
+def ask_questions() -> Project:
+    project_name = questionary.text(
+        "Project name",
+        default="my_fastapi_app",
+    ).unsafe_ask()
+
+    raw_allowed_origins: str = questionary.text(
+        "Allowed origins (CORS) [comma-separated, empty = disabled]",
+        default="",
+    ).unsafe_ask()
+
+    allowed_origins: list[str] = [
+        origin.strip() for origin in raw_allowed_origins.split(",") if origin.strip()
+    ]
+
+    raw_database: str = questionary.select(
+        "Database",
+        choices=[e.value for e in Database],
+        default="none",
+    ).unsafe_ask()
+
+    raw_orm: str = "none"
+    if raw_database != "none":
+        raw_orm = questionary.select(
+            "Data layer (SQLModel = ORM + Pydantic, none = driver only)",
+            choices=[e.value for e in Orm],
+            default="sqlmodel",
+        ).unsafe_ask()
+
+    rate_limiting: bool = questionary.confirm(
+        "Enable rate limiting",
+        default=False,
+    ).unsafe_ask()
+
+    run_install: bool = questionary.confirm(
+        "Run install after setup",
+        default=True,
+    ).unsafe_ask()
+
+    git: bool = questionary.confirm(
+        "Initialize git repository in the new project?",
+        default=True,
+    ).unsafe_ask()
+
+    git_z: bool = False
+    if git:
+        git_z = questionary.confirm(
+            "Run git z init (git-z commit wizard)? Requires git-z — https://github.com/ejpcmac/git-z",
+            default=False,
+        ).unsafe_ask()
+
+    project = Project(
+        project_name=project_name,
+        package_manager="uv",
+        use_typing=True,
+        use_ruff=True,
+        enable_cors=bool(allowed_origins),
+        allowed_origins=allowed_origins,
+        database=Database(raw_database),
+        orm=Orm(raw_orm),
+        rate_limiting=rate_limiting,
+        config=True,
+        git=git,
+        git_z=git_z,
+        run_install=run_install,
+    )
+
+    return project
+
+
+def show_summary(project: Project) -> None:
+    click.echo()
+    click.echo(f"Project : {project.project_name}")
+    click.echo(f"Package Manager : {project.package_manager}")
+
+    click.echo(f"CORS enabled : {'yes' if project.enable_cors else 'no'}")
+    if project.enable_cors:
+        click.echo(f"Allowed origins : {project.allowed_origins}")
+
+    click.echo(f"Database : {project.database.value}")
+    click.echo(f"ORM : {project.orm.value}")
+    click.echo(f"Rate limiting : {'yes' if project.rate_limiting else 'no'}")
+    click.echo(f"Run install : {'yes' if project.run_install else 'no'}")
+    click.echo(f"Git init : {'yes' if project.git else 'no'}")
+    click.echo(f"git-z init : {'yes' if project.git_z else 'no'}")
+    click.echo()

paststack/templates/base/.env.example

@@ -0,0 +1,2 @@
+# Copier vers .env et adapter
+{{ env_database_block }}

paststack/templates/base/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.DS_Store

paststack/templates/base/README.md

@@ -0,0 +1,39 @@
+# {{ project_name }}
+
+Projet généré avec [paststack](https://github.com/initd-fr/paststack).
+
+## Structure
+
+- `src/app/core/` — configuration (`pydantic-settings`)
+- `src/app/api/` — routeurs, dépendances, routes
+- `src/app/models/` — modèles **SQLModel** (si ORM activé)
+- `src/app/schemas/` — schémas Pydantic pour l’API
+- `src/app/database.py` — couche base (générée selon SQLite / Postgres, ORM ou non)
+
+## Dépendances optionnelles
+
+Le générateur installe les extras `uv` adaptés (ex. `sqlite-sqlmodel`, `postgres-none`, `rate-limit`).  
+Pour réinstaller à la main :
+
+```bash
+uv sync --extra <nom>   # voir [project.optional-dependencies] dans pyproject.toml
+```
+
+## Lancer en dev
+
+```bash
+cp .env.example .env
+uv run uvicorn app.main:app --reload --app-dir src
+```
+
+PostgreSQL : démarre la base avec `docker compose up -d` (fichier fourni si tu as choisi Postgres).
+
+Documentation interactive : http://127.0.0.1:8000/docs
+
+## Qualité
+
+```bash
+uv sync --group dev
+uv run ruff check src
+uv run mypy src
+```

paststack/templates/base/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "FastAPI application"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "pydantic-settings>=2.6.0",
+    "uvicorn[standard]>=0.32.0",
+]
+
+[project.optional-dependencies]
+sqlite-none = ["aiosqlite>=0.20.0"]
+sqlite-sqlmodel = [
+    "aiosqlite>=0.20.0",
+    "sqlalchemy[asyncio]>=2.0.0",
+    "sqlmodel>=0.0.22",
+]
+postgres-none = ["psycopg[binary]>=3.2.0"]
+postgres-sqlmodel = [
+    "asyncpg>=0.30.0",
+    "sqlalchemy[asyncio]>=2.0.0",
+    "sqlmodel>=0.0.22",
+]
+rate-limit = ["slowapi>=0.1.9"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13.0",
+    "ruff>=0.8.0",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+mypy_path = "src"
+explicit_package_bases = true

paststack/templates/base/src/app/__init__.py

@@ -0,0 +1,5 @@
+"""Code de ton application FastAPI (point d’entrée : `main.create_app`)."""
+
+from app.main import create_app
+
+__all__ = ["create_app"]

paststack/templates/base/src/app/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP : routeurs, endpoints et dépendances FastAPI."""

paststack/templates/base/src/app/api/deps.py

@@ -0,0 +1 @@
+"""Dépendances injectées dans les routes via `Depends()`."""

paststack/templates/base/src/app/api/router.py

@@ -0,0 +1,6 @@
+"""Routeur racine de l’API (monté sous `/api/v1` dans `main.py`)."""
+
+from fastapi import APIRouter
+
+api_router = APIRouter()
+# Branche tes routeurs métier : api_router.include_router(users.router, prefix="/users")

paststack/templates/base/src/app/api/routes/__init__.py

@@ -0,0 +1 @@
+"""Endpoints HTTP par domaine : un fichier (ou sous-package) par thème métier."""

paststack/templates/base/src/app/api/routes/health.py

@@ -0,0 +1,17 @@
+"""Endpoints `/health` et `/ready` (supervision, déploiement)."""
+
+from fastapi import APIRouter
+
+from app.database import is_database_configured
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@router.get("/ready")
+def ready() -> dict[str, str | bool]:
+    return {"status": "ok", "database": is_database_configured()}

paststack/templates/base/src/app/core/__init__.py

@@ -0,0 +1 @@
+"""Réglages et constantes partagés par toute l’app."""

paststack/templates/base/src/app/core/config.py

@@ -0,0 +1,22 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Variables lues depuis l’environnement (fichier `.env` à la racine du projet)."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_name: str = "{{ project_name }}"
+    debug: bool = False
+
+    cors_origins: list[str] = {{ allowed_origins }}
+
+    # URL async (SQLite ou Postgres) ; sans base de données, la valeur n’est pas utilisée
+    database_url: str = "{{ database_url }}"
+
+
+settings = Settings()

paststack/templates/base/src/app/database.py

@@ -0,0 +1,13 @@
+"""Accès données : démarrage / arrêt du moteur ou pool, état « DB prête »."""
+
+
+async def lifespan_startup() -> None:
+    return
+
+
+async def lifespan_shutdown() -> None:
+    return
+
+
+def is_database_configured() -> bool:
+    return False

paststack/templates/base/src/app/main.py

@@ -0,0 +1,42 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from starlette.middleware.cors import CORSMiddleware
+
+from app.api.router import api_router
+from app.api.routes import health
+from app.core.config import settings
+from app.database import lifespan_shutdown, lifespan_startup
+
+{{ rate_limit_imports }}
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    await lifespan_startup()
+    yield
+    await lifespan_shutdown()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.app_name,
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+    {{ rate_limit_setup }}
+    if settings.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=settings.cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    app.include_router(health.router)
+    app.include_router(api_router, prefix="/api/v1")
+    return app
+
+
+app = create_app()

paststack/templates/base/src/app/models/__init__.py

@@ -0,0 +1 @@
+"""Modèles ORM (tables SQL) — SQLModel ou SQLAlchemy selon ton projet."""

paststack/templates/base/src/app/schemas/__init__.py

@@ -0,0 +1 @@
+"""Schémas Pydantic : corps de requête, query params, réponses JSON."""

paststack/templates/database/postgres/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: app
+      POSTGRES_DB: app
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:

paststack/templates/database/postgres/none/database.py

@@ -0,0 +1,27 @@
+"""PostgreSQL sans ORM — connexion async via psycopg 3."""
+
+from app.core.config import settings
+from psycopg import AsyncConnection
+
+_conn: AsyncConnection | None = None
+
+
+async def lifespan_startup() -> None:
+    global _conn
+    _conn = await AsyncConnection.connect(settings.database_url)
+
+
+async def lifespan_shutdown() -> None:
+    if _conn is not None:
+        await _conn.close()
+
+
+def is_database_configured() -> bool:
+    return True
+
+
+def get_connection() -> AsyncConnection:
+    if _conn is None:
+        msg = "Database not initialized"
+        raise RuntimeError(msg)
+    return _conn

paststack/templates/database/postgres/sqlmodel/api/deps.py

@@ -0,0 +1,10 @@
+"""Injection d’une session SQLModel async dans les routes (`Depends(get_session)`)."""
+
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_session
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]

paststack/templates/database/postgres/sqlmodel/database.py

@@ -0,0 +1,38 @@
+"""PostgreSQL + SQLModel (async via asyncpg)."""
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlmodel import SQLModel
+
+from app.core.config import settings
+
+engine: AsyncEngine = create_async_engine(
+    settings.database_url,
+    echo=settings.debug,
+)
+async_session_maker = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def lifespan_startup() -> None:
+    import app.models  # noqa: F401 — pour enregistrer les tables auprès de SQLModel
+
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+
+async def lifespan_shutdown() -> None:
+    await engine.dispose()
+
+
+def is_database_configured() -> bool:
+    return True
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session

paststack/templates/database/postgres/sqlmodel/models/__init__.py

@@ -0,0 +1,5 @@
+"""Tables SQLModel : définis tes modèles ici (`SQLModel`, `Field`, …)."""
+
+from sqlmodel import SQLModel
+
+__all__ = ["SQLModel"]

paststack/templates/database/sqlite/none/database.py

@@ -0,0 +1,27 @@
+"""SQLite sans ORM — connexions async via aiosqlite."""
+
+from pathlib import Path
+
+import aiosqlite
+
+DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
+DB_PATH = DATA_DIR / "app.db"
+
+
+async def lifespan_startup() -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    async with aiosqlite.connect(DB_PATH) as db:
+        await db.execute("SELECT 1")
+
+
+async def lifespan_shutdown() -> None:
+    return
+
+
+def is_database_configured() -> bool:
+    return True
+
+
+async def get_connection() -> aiosqlite.Connection:
+    """Ouvrir une connexion : `db = await get_connection()` puis `await db.close()`."""
+    return await aiosqlite.connect(DB_PATH)

paststack/templates/database/sqlite/sqlmodel/api/deps.py

@@ -0,0 +1,10 @@
+"""Injection d’une session SQLModel async dans les routes (`Depends(get_session)`)."""
+
+from typing import Annotated
+
+from fastapi import Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_session
+
+SessionDep = Annotated[AsyncSession, Depends(get_session)]

paststack/templates/database/sqlite/sqlmodel/database.py

@@ -0,0 +1,40 @@
+"""SQLite + SQLModel (async)."""
+
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+from sqlmodel import SQLModel
+
+from app.core.config import settings
+
+engine: AsyncEngine = create_async_engine(
+    settings.database_url,
+    echo=settings.debug,
+)
+async_session_maker = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def lifespan_startup() -> None:
+    (Path(__file__).resolve().parent.parent.parent / "data").mkdir(parents=True, exist_ok=True)
+    import app.models  # noqa: F401 — pour enregistrer les tables auprès de SQLModel
+
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+
+
+async def lifespan_shutdown() -> None:
+    await engine.dispose()
+
+
+def is_database_configured() -> bool:
+    return True
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session

paststack/templates/database/sqlite/sqlmodel/models/__init__.py

@@ -0,0 +1,5 @@
+"""Tables SQLModel : définis tes modèles ici (`SQLModel`, `Field`, …)."""
+
+from sqlmodel import SQLModel
+
+__all__ = ["SQLModel"]

paststack/templates/rate_limiting/src/app/core/rate_limit.py

@@ -0,0 +1,14 @@
+"""Limite le débit des requêtes par IP (slowapi / Limiter)."""
+
+from fastapi import FastAPI
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
+from slowapi.util import get_remote_address
+
+
+def setup_rate_limiting(app: FastAPI) -> None:
+    limiter = Limiter(key_func=get_remote_address, default_limits=["120/minute"])
+    app.state.limiter = limiter
+    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+    app.add_middleware(SlowAPIMiddleware)

paststack-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: paststack
+Version: 0.1.0
+Summary: Opinionated CLI to generate production-ready FastAPI boilerplate with typing and linting.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/initd-fr/paststack
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.24.1
+Dynamic: license-file
+
+# paststack
+
+![logo](./img/logo.png)
+
+A CLI to generate production-ready FastAPI backends with a clean, opinionated architecture.
+
+![python](https://img.shields.io/badge/python-3.12%2B-blue)
+![cli](https://img.shields.io/badge/interface-CLI-black)
+![ruff](https://img.shields.io/badge/ruff-linting-red)
+![mypy](https://img.shields.io/badge/mypy-typing-blue)
+![pydantic](https://img.shields.io/badge/pydantic-validation-blue)
+![status](https://img.shields.io/badge/status-active--development-orange)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## Vue d’ensemble
+
+**paststack** génère un projet prêt au développement : arborescence `src/app/` (core, api, routes, models, schemas), configuration **pydantic-settings**, CORS, santé `/health` et `/ready`.
+
+Décisions actuelles de la v1 :
+
+| Sujet                   | Choix                                                                                                                             |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Gestionnaire de paquets | **uv**                                                                                                                            |
+| Base de données         | **none**, **SQLite**, **PostgreSQL**                                                                                              |
+| Couche données          | **sans ORM** (driver async) ou **SQLModel** (ORM unique)                                                                          |
+| Rate limiting           | **slowapi** (optionnel), limite par IP                                                                                            |
+| PostgreSQL              | **docker-compose** fourni ; URL alignée sur le conteneur                                                                          |
+| Dépendances             | **extras** dans le `pyproject.toml` généré (`sqlite-none`, `sqlite-sqlmodel`, `postgres-none`, `postgres-sqlmodel`, `rate-limit`) |
+| Git                     | `git init` optionnel                                                                                                              |
+| Messages de commit      | **[git-z](https://github.com/ejpcmac/git-z)** optionnel (`git z init` dans le projet généré)                                      |
+
+---
+
+## Fonctionnalités
+
+- Assistant interactif (`questionary`) : nom du projet, CORS, base, ORM, rate limiting, installation `uv`, git, git-z
+- Copie des templates embarqués dans le package (`templates/**/*`)
+- Création d’un venv + `uv sync` avec les bons `--extra` si demandé
+
+---
+
+## Utilisation
+
+Une fois le package installé (`pip install paststack` depuis PyPI, ou `uv pip install -e .` depuis ce dépôt) :
+
+```bash
+paststack
+```
+
+Puis ouvrir le dossier créé, copier `.env.example` vers `.env`, lancer l’API (voir le `README.md` généré dans le projet).
+
+### Développement (ce dépôt)
+
+```bash
+git clone https://github.com/initd-fr/paststack.git
+cd paststack
+uv sync
+uv pip install -e .
+paststack
+```
+
+### Qualité (ce dépôt)
+
+```bash
+uv run ruff check .
+uv run mypy .
+```
+
+### Tests (ce dépôt)
+
+```bash
+uv sync --group dev
+uv run pytest tests/ -v
+```
+
+Les combinaisons valides (SGBD × ORM × rate limiting) sont exposées dans `paststack.combinations` pour les tests ou un usage programmatique.
+
+---
+
+## Conventions de commit (ce dépôt)
+
+Format décrit dans `git-z.toml` : `TYPE description (scope)` (types et scopes listés dans le fichier).
+
+Pour utiliser l’assistant [git-z](https://github.com/ejpcmac/git-z) en local : `git z init` (après installation de l’outil). Le générateur peut lancer `git z init` dans le **nouveau** projet si tu coches l’option correspondante.
+
+---
+
+## Feuille de route (indicative)
+
+### v0.x — générateur actuel
+
+- [x] CLI interactive + modèle `Project` typé
+- [x] Template FastAPI (`core`, `api`, routes, models, schemas)
+- [x] SQLite / Postgres × ORM ou driver seul
+- [x] Rate limiting (slowapi) en option
+- [x] Venv + `uv sync` avec extras
+- [x] `git init` / `git z init` en option
+
+### Plus tard
+
+- Variantes d’architecture (minimal / modulable avancée), autres SGBD, observabilité, etc.
+
+---
+
+## Pourquoi ce projet
+
+Poser une base FastAPI propre (structure, typing, lint, DB) prend du temps. Ce CLI applique les mêmes défauts à chaque nouveau service.
+
+## Licence
+
+MIT

paststack-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+paststack/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+paststack/banner.py,sha256=q4oXk0FY5zVm6WXmnfYbKd7u2xMVnhtQ3u3iq0lwkck,1063
+paststack/cli.py,sha256=GYSRgqji1BNQLr3h7Zf8Bl9EFhUYatrf4La7MyutmP8,11944
+paststack/combinations.py,sha256=KO9kSbd0a77LvJjBQIqPLK_1g1DWm0aKP_knZSnBYjM,1986
+paststack/models.py,sha256=-GnOSgXelxBgl_OmXGRY65RwQ2dtKgL4QvGOiz0Nx9M,528
+paststack/prompts.py,sha256=JpCZPCvRDpU_MmRaaN6AqzK77L4wI08jRALytTFKyA0,2743
+paststack/templates/base/.env.example,sha256=-Rvx9TNbGbAkGduAaRd8U9jh4b_7TIqNmTdHwE9rRvk,55
+paststack/templates/base/.gitignore,sha256=c3xgCgkYf30P98o6lA1AS_N9JwyMYkD65OvToNnIlNA,145
+paststack/templates/base/README.md,sha256=A66RZhAY23hhZaFhrigOdWJQazsa-S28tKcExFfAcdU,1040
+paststack/templates/base/pyproject.toml,sha256=qiud3FMRJBzJaUMcf_BJ06hmgBXX6R0BkG4ld-kcqSw,1011
+paststack/templates/base/src/app/__init__.py,sha256=HKzpEnD18-CnTkVK7Ldxc0yRVzSC0ChpFcCxMPaDh0U,138
+paststack/templates/base/src/app/database.py,sha256=3mfMGpFPDoufaD_GEP-M-DKV-CJVJ-ukIw_RplH1Sko,246
+paststack/templates/base/src/app/main.py,sha256=uUW_QgaGlEK9b50HRGdg411d0mGngyowqmwECk26eUk,1055
+paststack/templates/base/src/app/api/__init__.py,sha256=1i_0TYs6aJPs-0m5KLXwAeGX1-fFTyAny6G1wjhc_Dg,58
+paststack/templates/base/src/app/api/deps.py,sha256=onq0VM_Ek53mWoV4UoWq25ZEjm8urh8eZjlM0p5OTuA,63
+paststack/templates/base/src/app/api/router.py,sha256=VDYoTr8Z7JNJAKY_8I8IMtaUrId3X_1wUNS9CiybRMU,219
+paststack/templates/base/src/app/api/routes/__init__.py,sha256=Lz-jtC92Bm2pwWYlCb0su-_eZ8ygJwLWnVqMPCcymFo,84
+paststack/templates/base/src/app/api/routes/health.py,sha256=B_SQRBXH2vi12pYIBaBm8hZwAlHdv_mcAgeaHyGWlhU,397
+paststack/templates/base/src/app/core/__init__.py,sha256=_CEqFxRWNQfJz_coVMRcYqAqhgsOUVSCxEqXWx-2Fj4,59
+paststack/templates/base/src/app/core/config.py,sha256=CqTM6Y4Xg3a_hi4JOrfh5IPkmtfWhVJmRX0JEjSzfiw,599
+paststack/templates/base/src/app/models/__init__.py,sha256=aNCTsy0qEpHNwdsLcwlJGSuKZUR0hhCP9b0nYQu8itc,77
+paststack/templates/base/src/app/schemas/__init__.py,sha256=Bjnprg3q75H3nplHydYz6gk6d-FDxB68erOeVga5hU4,75
+paststack/templates/database/postgres/docker-compose.yml,sha256=E7Gle_6GZN03hacGBwSploHOEpFfwtl3kEi5ihKUlGY,258
+paststack/templates/database/postgres/none/database.py,sha256=r4iEpHH7ry4bPeX7ltKfDQwRo6X26Z_kgG1QF7LWrgM,601
+paststack/templates/database/postgres/sqlmodel/database.py,sha256=1qx9htyCGrqTtBLY51E29wT2l4MVzoBtqpetVLplALM,957
+paststack/templates/database/postgres/sqlmodel/api/deps.py,sha256=BOojAC9sQnbsO153QGZI24DS3KVVZwywGStVDMpyIlI,294
+paststack/templates/database/postgres/sqlmodel/models/__init__.py,sha256=2oYxJudsBFH4so4CNw8L_3CGT1BG4qomB9y-zes8BAE,133
+paststack/templates/database/sqlite/none/database.py,sha256=xlT4mHcA2MLMY-OtTE_1MAGMWiH3Iy3lfVnuFw8hyEE,667
+paststack/templates/database/sqlite/sqlmodel/database.py,sha256=ZUTiAUfBv3GrcFK2AzY7yLkgxHVe8BZ64z8ctW8tHDQ,1062
+paststack/templates/database/sqlite/sqlmodel/api/deps.py,sha256=BOojAC9sQnbsO153QGZI24DS3KVVZwywGStVDMpyIlI,294
+paststack/templates/database/sqlite/sqlmodel/models/__init__.py,sha256=2oYxJudsBFH4so4CNw8L_3CGT1BG4qomB9y-zes8BAE,133
+paststack/templates/rate_limiting/src/app/core/rate_limit.py,sha256=QcdS7Ny6tprNw0CTQy6trtdLneYTCvHm6Qic0bubp1I,574
+paststack-0.1.0.dist-info/licenses/LICENSE,sha256=kfpGx5BL8MZ6FculLtl3jKSa22TPkZKNpaTThxj-Yaw,1080
+paststack-0.1.0.dist-info/METADATA,sha256=AqqPnoRXk2z9o17aWEsO9QxeVbbquqALPCGy98SnJ7A,4979
+paststack-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+paststack-0.1.0.dist-info/entry_points.txt,sha256=Ikb6kTNbasiFCF7fd0HbpH6Dv-7DCh47YFpDlaNSvkQ,49
+paststack-0.1.0.dist-info/top_level.txt,sha256=zKdgU3u1iisr9qqlj2H8cXpy71NgmGjmZfRhBnZ6E9c,10
+paststack-0.1.0.dist-info/RECORD,,

paststack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paststack-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paststack = paststack.cli:main

paststack-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quentin Van Steenwinkel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paststack-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paststack