shaapi 0.1.0__py3-none-any.whl

shaapi/__init__.py

@@ -0,0 +1,3 @@
+"""shaapi — scaffold lean, batteries-included FastAPI backends."""
+
+__version__ = "0.1.0"

shaapi/cli.py

@@ -0,0 +1,97 @@
+"""shaapi command-line interface."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from shaapi import __version__
+from shaapi.generator import create_project, slugify
+
+# Make output robust on Windows consoles (cp1252) and when piped.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+    except (AttributeError, ValueError):
+        pass
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="shaapi - scaffold lean, batteries-included FastAPI backends.",
+)
+console = Console()
+
+
+@app.command("create-project")
+def create_project_command(
+    name: str = typer.Argument(..., help='Project name, e.g. "my api".'),
+    path: Path = typer.Option(Path("."), "--path", "-p", help="Where to create the project."),
+    monitoring: Optional[bool] = typer.Option(
+        None, "--monitoring/--no-monitoring", help="Include the Prometheus/Grafana stack."
+    ),
+    git: Optional[bool] = typer.Option(
+        None, "--git/--no-git", help="Initialize a git repository."
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Accept defaults, skip prompts."),
+):
+    """Create a new shaapi project."""
+    slug = slugify(name)
+    console.print(f"\n[bold cyan]shaapi[/] creating project [bold]{slug}[/]\n")
+
+    if monitoring is None:
+        monitoring = (
+            False if yes
+            else typer.confirm("Include monitoring (Prometheus/Grafana/Tempo/Loki)?", default=False)
+        )
+    if git is None:
+        git = True if yes else typer.confirm("Initialize a git repository?", default=True)
+
+    try:
+        dest = create_project(name, path, monitoring=monitoring, git_init=git)
+    except (FileExistsError, ValueError, RuntimeError) as exc:
+        console.print(f"[bold red]Error:[/] {exc}")
+        raise typer.Exit(code=1)
+
+    up_cmd = "./docker-run.sh up" + (" --monitoring" if monitoring else "")
+    console.print(
+        Panel.fit(
+            f"[green][OK][/] Project created at [bold]{dest}[/]\n\n"
+            f"[bold]Next steps[/]\n"
+            f"  cd {dest.name}\n"
+            f"  {up_cmd}\n\n"
+            f"Then open [cyan]http://localhost:8000/admin/api/v1/docs[/]",
+            title="Done",
+            border_style="cyan",
+        )
+    )
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"shaapi {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def version() -> None:
+    """Show the shaapi version."""
+    console.print(f"shaapi {__version__}")
+
+
+@app.callback()
+def main(
+    _version: Optional[bool] = typer.Option(
+        None, "--version", "-V", callback=_version_callback, is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """shaapi CLI."""
+
+
+if __name__ == "__main__":
+    app()

shaapi/generator.py

@@ -0,0 +1,114 @@
+"""Project scaffolding: copy the bundled template into a new project, rebranding
+the ``shaapi`` identifier to the user's project name.
+
+Kept intentionally dependency-free (pure stdlib) so the ``shaapi`` CLI stays
+tiny — the heavy stack lives only in the generated project.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+TEMPLATE_DIR = Path(__file__).resolve().parent / "template"
+
+# Path components never copied into a generated project.
+_EXCLUDE_NAMES = {
+    "__pycache__", ".venv", "venv", ".git", ".pytest_cache", ".ruff_cache",
+    ".mypy_cache", "node_modules", ".env", ".DS_Store",
+}
+# Suffixes never copied at all (local dev artifacts).
+_SKIP_SUFFIXES = {".pyc", ".pyo", ".db", ".sqlite3", ".log"}
+# Binary files: copied verbatim, never text-substituted.
+_BINARY_SUFFIXES = {
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".xdb",
+    ".woff", ".woff2", ".ttf", ".pdf", ".zip", ".gz",
+}
+
+
+def slugify(name: str) -> str:
+    """Turn a project name into a safe lowercase identifier slug."""
+    slug = re.sub(r"[^0-9a-zA-Z]+", "_", name.strip().lower()).strip("_")
+    if not slug:
+        raise ValueError("Project name must contain at least one letter or digit.")
+    if slug[0].isdigit():
+        slug = f"app_{slug}"
+    return slug
+
+
+def _rebrand(text: str, slug: str) -> str:
+    """Replace the shaapi identifier with the project slug, preserving case."""
+    text = text.replace("SHAAPI", slug.upper())
+    text = text.replace("Shaapi", slug.capitalize())
+    text = text.replace("shaapi", slug)
+    return text
+
+
+def create_project(
+    name: str,
+    dest_parent: Path | str,
+    *,
+    monitoring: bool = False,
+    git_init: bool = True,
+) -> Path:
+    """Generate a new shaapi project and return its path.
+
+    :param name: human project name (e.g. "My API").
+    :param dest_parent: directory in which the project folder is created.
+    :param monitoring: include the opt-in Prometheus/Grafana stack.
+    :param git_init: run ``git init`` in the new project.
+    """
+    if not TEMPLATE_DIR.is_dir():
+        raise RuntimeError(f"Template not found at {TEMPLATE_DIR}")
+
+    slug = slugify(name)
+    dest = Path(dest_parent).resolve() / slug
+    if dest.exists():
+        raise FileExistsError(f"Directory already exists: {dest}")
+
+    for src in sorted(TEMPLATE_DIR.rglob("*")):
+        rel = src.relative_to(TEMPLATE_DIR)
+        if any(part in _EXCLUDE_NAMES for part in rel.parts):
+            continue
+        if src.is_dir():
+            continue
+        if src.suffix in _SKIP_SUFFIXES:
+            continue
+        # Monitoring is opt-in: drop its compose file and the etc/ configs.
+        if not monitoring and (
+            src.name == "docker-compose.monitoring.yml" or rel.parts[0] == "etc"
+        ):
+            continue
+
+        target = dest / Path(_rebrand(str(rel), slug))
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        if src.suffix in _BINARY_SUFFIXES:
+            shutil.copy2(src, target)
+            continue
+        try:
+            content = src.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            shutil.copy2(src, target)
+            continue
+        # Force LF: the generated project targets Linux/Docker, and CRLF would
+        # break shell scripts and .env files inside containers. newline="\n"
+        # disables Windows' \n -> \r\n translation.
+        target.write_text(_rebrand(content, slug), encoding="utf-8", newline="\n")
+
+    # Seed a ready-to-run .env from the template.
+    env_template = dest / ".env.template"
+    env_file = dest / ".env"
+    if env_template.exists() and not env_file.exists():
+        env_file.write_text(
+            env_template.read_text(encoding="utf-8"), encoding="utf-8", newline="\n"
+        )
+
+    if git_init:
+        try:
+            subprocess.run(["git", "init", "-q"], cwd=dest, check=True)
+        except (subprocess.CalledProcessError, FileNotFoundError, OSError):
+            pass  # git is optional; never fail project creation over it
+
+    return dest

shaapi/template/.dockerignore

@@ -0,0 +1,37 @@
+# Version control
+.git
+.gitignore
+.gitlab-ci.yml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Env & secrets
+.env
+.env.*
+!.env.template
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+
+# Local data & build artifacts
+*.db
+*.sqlite3
+dist/
+build/
+node_modules/
+*.log
+
+# Docs / CI assets not needed in image
+.github/
+docs/
+README.md

shaapi/template/.env.template

@@ -0,0 +1,59 @@
+# shaapi environment configuration
+# Copy to `.env` and adjust. Every value has a sane default in
+# backend/core/conf.py, so you only need to override what differs.
+#
+# When running with docker-compose, the database/redis/minio hosts are
+# overridden to the container service names by the compose file, so the
+# localhost values below are meant for bare-metal local development.
+
+# Environment: dev | preprod | prod
+ENVIRONMENT=dev
+
+# --- Database (Postgres) ---
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DATABASE=shaapi
+
+# Auto-create tables on startup (dev only). Set to false in production and use
+# Alembic migrations instead.
+DB_AUTO_CREATE=true
+
+# --- Redis ---
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DATABASE=0
+
+# --- Object storage (MinIO / S3-compatible) ---
+MINIO_ENDPOINT=localhost:9000
+MINIO_PORT=9000
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+MINIO_BUCKET_NAME=shaapi
+MINIO_CLOUD_URL=http://localhost:9000
+
+# --- Secrets (CHANGE THESE IN PRODUCTION) ---
+# python -c "import secrets; print(secrets.token_urlsafe(32))"
+TOKEN_SECRET_KEY=dev-insecure-change-me-token-secret-key
+# python -c "import os; print(os.urandom(32).hex())"
+OPERA_LOG_ENCRYPT_SECRET_KEY=dev-insecure-change-me-opera-log-key
+
+# --- Optional: SMTP / email (leave blank to disable) ---
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_TLS=True
+SMTP_USER=
+SMTP_PASSWORD=
+EMAILS_FROM_EMAIL=
+EMAILS_FROM_NAME=
+
+# --- Optional: Google SSO ---
+GOOGLE_CLIENT_ID=
+GOOGLE_SECRET_KEY=
+GOOGLE_WEBHOOK_OAUTH_REDIRECT_URI=
+
+# --- Optional: Observability (Prometheus / OpenTelemetry) ---
+OBSERVABILITY_ENABLED=false
+OTLP_GRPC_ENDPOINT=

shaapi/template/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF in the repository (Linux/Docker target)
+* text=auto eol=lf
+
+# Shell scripts MUST keep LF or they break inside Linux containers
+*.sh text eol=lf
+
+# Binary assets (never normalize)
+*.png binary
+*.jpg binary
+*.ico binary
+*.xdb binary
+*.db binary

shaapi/template/.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.env.elastic
+
+# Distribution / packaging
+.Python
+# build/
+develop-eggs/
+dist/
+downloads/
+/node_modules
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# private_key.pem
+# public_key.pem
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.elastic
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+fastapi-boilerplate-venv/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+/boilerplate-venv
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.history/
+
+
+changelog.config.js
+
+# macOS
+.DS_Store
+
+# uv (commit uv.lock for reproducibility)
+.venv/

shaapi/template/.gitlab-ci.yml

@@ -0,0 +1,89 @@
+image:
+  name: docker/compose:1.29.1
+  entrypoint: [""]
+
+services:
+  - docker:dind
+
+stages:
+  - build
+  - release
+  - deploy
+
+variables:
+  DOCKER_HOST: tcp://docker:2375
+  DOCKER_DRIVER: overlay2
+  DOCKER_TLS_CERTDIR: ""
+
+# the way to re-use the same steps for every stage in the workflow in the configuration file
+before_script:
+  # export the environment variable for an address of where our Docker image gets stored
+  - export IMAGE=$CI_REGISTRY/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME
+  # Installs the open-ssh client for later login to our vps
+  # and Bash to execute the Bash script for setting up the environment variable.
+  - apk add --no-cache openssh-client bash
+  - echo "$CI_JOB_TOKEN" | docker login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
+  # - docker login -u $CI_REGISTRY_USER -p $CI_JOB_TOKEN $CI_REGISTRY
+  - chmod +x ./devops/scripts/setup_env.sh
+  - bash ./devops/scripts/setup_env.sh
+
+build:
+  stage: build
+  script:
+    - export API_IMAGE=$IMAGE:api
+    # Pull the image if it exists in the registry.
+    - docker pull $IMAGE:api || true
+    # Build the image based on the configuration we have in the docker-compose.ci.yml file
+    - docker-compose -f ./devops/docker-compose/docker-compose-ci.yml build
+    # After the image has been built, it pushes the latest build image back to the GitLab Docker image registry
+    - docker push $IMAGE:api
+  only:
+    - prod
+  # when: manual
+
+release:
+  stage: release
+  script:
+    - apk add --update nodejs git npm
+    - git config --global user.email "admin@kaanari.com"
+    - git config --global user.name "nicolas"
+    - git tag -d v0.1.1 || true
+    - git push --delete origin v0.1.1 || true
+    - mkdir -p ~/.ssh
+    - echo "$PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
+    - cat ~/.ssh/id_rsa
+    - chmod 700 ~/.ssh/id_rsa
+    - eval "$(ssh-agent -s)"
+    - ssh-add ~/.ssh/id_rsa
+    - ssh-keyscan -H gitlab.organisation.com >> ~/.ssh/known_hosts
+    - git remote set-url origin git@gitlab.organisation.com:boilerplate/boilerplate.git
+    - npm install
+    - npm ci
+    - npm run release
+    - git remote show origin
+    - git push --follow-tags origin HEAD:main
+  only:
+    - deploy
+
+deploy:
+  stage: deploy
+  script:
+    - export API_IMAGE=$IMAGE:api
+    # Extract a private key that is going to be used for SSH to the droplet and add it to the GitLab CI/CD process.
+    - mkdir -p ~/.ssh
+    - echo "$PRIVATE_KEY" | tr -d '\r' > ~/.ssh/id_rsa
+    # - cat ~/.ssh/id_rsa
+    - chmod 700 ~/.ssh/id_rsa
+    # Copy all of the required artifacts for the deployment to the droplet by SSH-ing to it.
+    - eval "$(ssh-agent -s)"
+    - ssh-add ~/.ssh/id_rsa
+    - ssh-keyscan -H "$VPS_IP_ADDRESS" >> ~/.ssh/known_hosts
+    - chmod +x ./devops/scripts/deploy.sh
+    # - chmod +x ./clean.sh
+    # - bash ./clean.sh
+    - scp -o StrictHostKeyChecking=no -r ./.env ./devops/docker-compose/docker-compose.yml $VPS_USER@$VPS_IP_ADDRESS:/app
+    # # Run the deployment script
+    - bash ./devops/scripts/deploy.sh
+  only:
+    - prod
+  # when: manual

shaapi/template/Dockerfile

@@ -0,0 +1,59 @@
+# syntax=docker/dockerfile:1
+# ============================================================================
+# Stage 1 — builder: resolve & install dependencies into an isolated venv
+# ============================================================================
+FROM python:3.11-slim AS builder
+
+# uv binary (fast, reproducible installs)
+COPY --from=ghcr.io/astral-sh/uv:0.11 /uv /uvx /bin/
+
+WORKDIR /app
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    # Keep the venv OUTSIDE /app so a dev bind-mount of the source (.:/app)
+    # never shadows the installed dependencies.
+    UV_PROJECT_ENVIRONMENT=/opt/venv
+
+# System build dependencies (asyncpg / cryptography / libpq)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Optional extras (e.g. "--extra monitoring"); empty for the lean default.
+ARG EXTRAS=""
+
+# Install dependencies first (cached layer; only re-runs when deps change)
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project ${EXTRAS}
+
+# ============================================================================
+# Stage 2 — runtime: slim image with only what's needed to run
+# ============================================================================
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Runtime system deps (libpq for Postgres, curl for healthchecks)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libpq5 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Bring in the pre-built virtualenv (lives outside /app so dev bind-mounts work)
+COPY --from=builder /opt/venv /opt/venv
+
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONPATH=/app \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    LANG=C.UTF-8
+
+# Application source
+COPY . .
+
+RUN chmod +x ./backend/entrypoint-api.sh
+
+EXPOSE 8000
+
+ENTRYPOINT ["bash", "./backend/entrypoint-api.sh"]

shaapi/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Kaanari
+
+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.