shaapi 0.1.0__tar.gz

shaapi-0.1.0/.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-0.1.0/LICENCE

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

shaapi-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: shaapi
+Version: 0.1.0
+Summary: Scaffold lean, batteries-included FastAPI backends — like django-admin, for FastAPI.
+Project-URL: Homepage, https://github.com/Shalom-302/shaapi
+Project-URL: Repository, https://github.com/Shalom-302/shaapi
+Author-email: Shalom <shalomtehe219@gmail.com>
+License: MIT
+License-File: LICENCE
+Keywords: backend,boilerplate,cli,fastapi,scaffold,starter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# shaapi
+
+**Scaffold lean, batteries-included FastAPI backends — like `django-admin`, for FastAPI.**
+
+Beginners shouldn't have to architect a production backend from scratch. `shaapi`
+gives you a clean, opinionated FastAPI project — async SQLAlchemy + Alembic,
+Postgres, Redis, JWT auth, Casbin RBAC, file storage, and a one-command Docker
+workflow — generated in seconds.
+
+```bash
+pip install shaapi
+shaapi create-project "my api"
+cd my_api
+./docker-run.sh up
+```
+
+→ API live at `http://localhost:8000`, Swagger at `http://localhost:8000/admin/api/v1/docs`.
+
+## What you get
+
+- **FastAPI** (async) with a clean layered architecture (`app/`, `common/`, `core/`, `crud/`, `models/`, `schemas/`)
+- **SQLAlchemy 2 + Alembic** migrations, **Postgres** (auto-create in dev, migrations in prod)
+- **Redis** cache + rate limiting
+- **JWT auth** + **Casbin RBAC** (users, roles, permissions)
+- **File storage** (MinIO / S3 / GCS)
+- **Docker**: multi-stage slim image built with [uv], hot-reload in dev (source bind-mount), `docker-run.sh` orchestration
+- **Opt-in observability** (`--monitoring`): Prometheus, Grafana, Tempo, Loki
+
+## CLI
+
+```bash
+shaapi create-project "my api"          # interactive
+shaapi create-project "my api" -y       # accept defaults
+shaapi create-project "my api" --monitoring --no-git
+shaapi --version
+```
+
+## In your generated project
+
+```bash
+./docker-run.sh up            # build + start everything (dev: hot-reload)
+./docker-run.sh up --monitoring
+./docker-run.sh logs          # tail logs
+./docker-run.sh migrate       # alembic upgrade head
+./docker-run.sh makemigrations "add posts table"
+./docker-run.sh down
+```
+
+## Documentation
+
+Full docs in **English** and **French** under [`docs/`](docs/):
+
+| | English | Français |
+|---|---|---|
+| Getting started | [getting-started](docs/en/getting-started.md) | [démarrage](docs/fr/demarrage.md) |
+| Architecture | [architecture](docs/en/architecture.md) | [architecture](docs/fr/architecture.md) |
+| Create a feature | [create-a-feature](docs/en/create-a-feature.md) | [créer une fonctionnalité](docs/fr/creer-une-fonctionnalite.md) |
+| Deployment | [deployment](docs/en/deployment.md) | [déploiement](docs/fr/deploiement.md) |
+
+## Example
+
+[`examples/todolist`](examples/todolist) — a complete authenticated Todo API
+(JWT, per-user ownership, admin-only endpoint) built on top of shaapi in 5 files.
+
+## Status
+
+Alpha. See the repo for roadmap and contribution guidelines.
+
+## License
+
+MIT
+
+[uv]: https://github.com/astral-sh/uv

shaapi-0.1.0/README.md

@@ -0,0 +1,73 @@
+# shaapi
+
+**Scaffold lean, batteries-included FastAPI backends — like `django-admin`, for FastAPI.**
+
+Beginners shouldn't have to architect a production backend from scratch. `shaapi`
+gives you a clean, opinionated FastAPI project — async SQLAlchemy + Alembic,
+Postgres, Redis, JWT auth, Casbin RBAC, file storage, and a one-command Docker
+workflow — generated in seconds.
+
+```bash
+pip install shaapi
+shaapi create-project "my api"
+cd my_api
+./docker-run.sh up
+```
+
+→ API live at `http://localhost:8000`, Swagger at `http://localhost:8000/admin/api/v1/docs`.
+
+## What you get
+
+- **FastAPI** (async) with a clean layered architecture (`app/`, `common/`, `core/`, `crud/`, `models/`, `schemas/`)
+- **SQLAlchemy 2 + Alembic** migrations, **Postgres** (auto-create in dev, migrations in prod)
+- **Redis** cache + rate limiting
+- **JWT auth** + **Casbin RBAC** (users, roles, permissions)
+- **File storage** (MinIO / S3 / GCS)
+- **Docker**: multi-stage slim image built with [uv], hot-reload in dev (source bind-mount), `docker-run.sh` orchestration
+- **Opt-in observability** (`--monitoring`): Prometheus, Grafana, Tempo, Loki
+
+## CLI
+
+```bash
+shaapi create-project "my api"          # interactive
+shaapi create-project "my api" -y       # accept defaults
+shaapi create-project "my api" --monitoring --no-git
+shaapi --version
+```
+
+## In your generated project
+
+```bash
+./docker-run.sh up            # build + start everything (dev: hot-reload)
+./docker-run.sh up --monitoring
+./docker-run.sh logs          # tail logs
+./docker-run.sh migrate       # alembic upgrade head
+./docker-run.sh makemigrations "add posts table"
+./docker-run.sh down
+```
+
+## Documentation
+
+Full docs in **English** and **French** under [`docs/`](docs/):
+
+| | English | Français |
+|---|---|---|
+| Getting started | [getting-started](docs/en/getting-started.md) | [démarrage](docs/fr/demarrage.md) |
+| Architecture | [architecture](docs/en/architecture.md) | [architecture](docs/fr/architecture.md) |
+| Create a feature | [create-a-feature](docs/en/create-a-feature.md) | [créer une fonctionnalité](docs/fr/creer-une-fonctionnalite.md) |
+| Deployment | [deployment](docs/en/deployment.md) | [déploiement](docs/fr/deploiement.md) |
+
+## Example
+
+[`examples/todolist`](examples/todolist) — a complete authenticated Todo API
+(JWT, per-user ownership, admin-only endpoint) built on top of shaapi in 5 files.
+
+## Status
+
+Alpha. See the repo for roadmap and contribution guidelines.
+
+## License
+
+MIT
+
+[uv]: https://github.com/astral-sh/uv

shaapi-0.1.0/docs/README.md

@@ -0,0 +1,30 @@
+# shaapi documentation
+
+**Scaffold lean, batteries-included FastAPI backends — like `django-admin`, for FastAPI.**
+
+Choose your language / Choisissez votre langue :
+
+### 🇬🇧 English
+- [Getting started](en/getting-started.md)
+- [Architecture](en/architecture.md)
+- [Create a feature (Todo tutorial)](en/create-a-feature.md)
+- [Deployment](en/deployment.md)
+
+### 🇫🇷 Français
+- [Démarrage rapide](fr/demarrage.md)
+- [Architecture](fr/architecture.md)
+- [Créer une fonctionnalité (tutoriel Todo)](fr/creer-une-fonctionnalite.md)
+- [Déploiement](fr/deploiement.md)
+
+---
+
+## TL;DR
+
+```bash
+pip install shaapi
+shaapi create-project "my api"
+cd my_api
+./docker-run.sh up
+```
+
+API → `http://localhost:8000` · Swagger → `http://localhost:8000/admin/api/v1/docs`

shaapi-0.1.0/examples/todolist/README.md

@@ -0,0 +1,92 @@
+# Example: a Todo API with auth (admin + user)
+
+This example shows how little it takes to build a real, authenticated feature on
+top of a shaapi project: a per-user todo list with ownership rules and an
+admin-only "see everything" endpoint.
+
+*Cet exemple montre à quel point il est simple de bâtir une vraie fonctionnalité
+authentifiée sur shaapi : une todolist par utilisateur, avec règles de propriété
+et un endpoint réservé aux admins.*
+
+---
+
+## What it demonstrates / Ce que ça démontre
+
+- **JWT auth** — register / login, protected routes (`DependsJwtAuth`)
+- **Per-user data** — each user only sees and edits their own todos
+- **Ownership enforcement** — accessing someone else's todo returns `403`
+- **Role-based access** — only users with the `admin` role can `GET /todo/all`
+
+All of it on **FastAPI + async SQLAlchemy + Pydantic v2**, with zero extra
+plumbing — shaapi already provides the auth, DB session, RBAC and response layer.
+
+## The whole feature = 5 files + 1 line
+
+```
+backend/
+├── models/todo.py                      # SQLAlchemy model
+├── app/admin/schema/todo.py            # Pydantic schemas
+├── crud/crud_todo.py                   # data access (CRUDBase)
+├── app/admin/service/todo_service.py   # business logic
+└── app/admin/api/v1/todo.py            # router (auto-discovered)
+```
+
+The router is **auto-discovered** — dropping `todo.py` into `app/admin/api/v1/`
+is enough to expose its endpoints. No central registry to edit.
+
+## Install into a shaapi project / Installer dans un projet shaapi
+
+```bash
+# 1. Create a project
+pip install shaapi
+shaapi create-project "todoapp"
+
+# 2. Copy this feature on top of it
+cp -r examples/todolist/backend/. todoapp/backend/
+
+# 3. Register the model (one line) in todoapp/backend/models/__init__.py
+#    from backend.models.todo import Todo
+
+# 4. Run
+cd todoapp
+./docker-run.sh up
+```
+
+In development the table is auto-created on startup. For production, generate a
+migration: `./docker-run.sh makemigrations "add todo table"`.
+
+## Endpoints
+
+| Method | Path                         | Who            | Description                 |
+|--------|------------------------------|----------------|-----------------------------|
+| POST   | `/admin/api/v1/auth/register`| public         | Create an account           |
+| POST   | `/admin/api/v1/auth/login`   | public         | Get an access token         |
+| POST   | `/admin/api/v1/todo/`        | any user       | Create a todo               |
+| GET    | `/admin/api/v1/todo/`        | any user       | List **my** todos (paged)   |
+| GET    | `/admin/api/v1/todo/{id}`    | owner/admin    | Get one todo                |
+| PUT    | `/admin/api/v1/todo/{id}`    | owner/admin    | Update a todo               |
+| DELETE | `/admin/api/v1/todo/{id}`    | owner/admin    | Delete a todo               |
+| GET    | `/admin/api/v1/todo/all`     | **admin only** | List every user's todos     |
+
+Authenticated calls send `Authorization: Bearer <access_token>`.
+
+## Make a user an admin / Donner le rôle admin
+
+```sql
+INSERT INTO role (x_id, name, status, remark, created_time)
+VALUES ('admin0000000000000000000001', 'admin', 1, '', now());
+INSERT INTO user_role (user_id, role_id)
+SELECT <USER_ID>, id FROM role WHERE name = 'admin';
+```
+
+## Reproduce the proof / Reproduire la preuve
+
+With the stack running, from the repo root:
+
+```bash
+python examples/todolist/smoke_test.py
+```
+
+Expected output: registration, per-user CRUD, a `403` when a user touches
+another user's todo, a `403` on `/todo/all` for a normal user, and `200` once
+the user is granted the `admin` role.

shaapi-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "shaapi"
+version = "0.1.0"
+description = "Scaffold lean, batteries-included FastAPI backends — like django-admin, for FastAPI."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Shalom", email = "shalomtehe219@gmail.com" }]
+keywords = ["fastapi", "boilerplate", "scaffold", "backend", "starter", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.11",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+]
+
+[project.urls]
+Homepage = "https://github.com/Shalom-302/shaapi"
+Repository = "https://github.com/Shalom-302/shaapi"
+
+[project.scripts]
+shaapi = "shaapi.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# packages=["src/shaapi"] already bundles the whole template (incl. non-python
+# files and dotfiles), so no force-include is needed.
+[tool.hatch.build.targets.wheel]
+packages = ["src/shaapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/shaapi", "README.md", "LICENCE"]

shaapi-0.1.0/src/shaapi/__init__.py

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

shaapi-0.1.0/src/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()