fastapi-templatekit 0.1.0__tar.gz

fastapi_templatekit-0.1.0/LICENSE

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

fastapi_templatekit-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: fastapi-templatekit
+Version: 0.1.0
+Summary: FastAPI project generator with a root-level, Django-style app layout
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# fastapi-templatekit
+
+[![Tests](https://github.com/Amogha-Hegde/fastapi-templatekit/actions/workflows/ci.yml/badge.svg)](https://github.com/Amogha-Hegde/fastapi-templatekit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/Amogha-Hegde/fastapi-templatekit/branch/main/graph/badge.svg)](https://codecov.io/gh/Amogha-Hegde/fastapi-templatekit)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-templatekit.svg)](https://pypi.org/project/fastapi-templatekit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-templatekit.svg)](https://pypi.org/project/fastapi-templatekit/)
+[![PyPI downloads](https://static.pepy.tech/badge/fastapi-templatekit)](https://pepy.tech/project/fastapi-templatekit)
+
+A FastAPI TemplateKit with a root-level, Django-style app layout.
+
+## CLI
+
+Create a new project without installing this template into that project's
+environment:
+
+```bash
+uvx fastapi-templatekit startproject myproject
+cd myproject
+uvx fastapi-templatekit startapp users
+```
+
+Create the project files directly in the current directory:
+
+```bash
+uvx fastapi-templatekit startproject myproject .
+```
+
+If generated files already exist, the CLI asks before overwriting them. Use
+`--force` to overwrite without a prompt:
+
+```bash
+uvx fastapi-templatekit startproject myproject . --force
+```
+
+Create the project at a custom path:
+
+```bash
+uvx fastapi-templatekit startproject myproject ../services/myproject
+```
+
+For local development from this repository:
+
+```bash
+uvx --from . fastapi-templatekit startproject myproject
+```
+
+Generated projects include a Typer management command to discover registered
+HTTP and websocket routes:
+
+```bash
+uv run myproject urls
+```
+
+Show available commands and details:
+
+```bash
+uvx fastapi-templatekit help
+```
+
+Add health probes to an existing generated project:
+
+```bash
+uvx fastapi-templatekit addhealthprobes
+```
+
+Create an app with optional websocket and database scaffolding:
+
+```bash
+uvx fastapi-templatekit startapp users
+uvx fastapi-templatekit startapp users --with-websockets --with-database
+```
+
+Generated projects keep the main router beside `main.py`:
+
+```text
+myproject/
+├── pyproject.toml
+├── fastapi_templatekit.toml
+├── myproject/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   └── router.py
+└── users/
+    ├── __init__.py
+    ├── router.py
+    ├── endpoints/
+    │   ├── __init__.py
+    │   └── api.py
+    ├── schemas/
+    │   ├── __init__.py
+    │   └── validator.py
+    ├── service/
+    │   ├── __init__.py
+    │   └── users_service.py
+    ├── models/          # created only with database/tables enabled
+    │   └── __init__.py
+    └── websocket/       # created only with websockets enabled
+        ├── __init__.py
+        └── router.py
+```
+
+## Structure
+
+```text
+.
+├── api/           # top-level router registration
+├── health/        # example domain app at project root
+├── main/
+│   ├── config.py  # settings and config live here
+│   └── app.py     # FastAPI declaration lives here
+└── pyproject.toml
+```
+
+This follows the same domain-first idea from `fastapi-best-practices`, but without a `src/` directory.
+Feature apps and the shared API router live directly under the project root, similar to Django apps.
+
+## Run
+
+```bash
+uv run uvicorn main.app:app --reload
+```
+
+## WebSockets
+
+WebSocket routes are mounted under the same API prefix, so the default endpoint is:
+
+```text
+/api/v1/ws/{room_name}
+```
+
+There is also a built-in browser test page at:
+
+```text
+/api/v1/ws/test
+```
+
+This app uses `fastapi-websockets` with the package's environment-based channel-layer loader.
+For websocket-related environment configuration, refer to https://github.com/Amogha-Hegde/fastapi-websockets.
+
+Tests force `FASTAPI_WEBSOCKETS_BACKEND=inmemory` so they do not depend on a running database.
+
+Example session:
+
+```text
+connect ws://127.0.0.1:8000/api/v1/ws/demo
+receive {"event":"connected","room":"demo",...}
+send {"sender":"alice","message":"hello"}
+receive {"event":"message","room":"demo","sender":"alice","message":"hello"}
+```
+
+## Add a new app
+
+Create a root-level package such as `users/` or `orders/`, define its router there, and include it from your project's main `router.py`.

fastapi_templatekit-0.1.0/README.md

@@ -0,0 +1,154 @@
+# fastapi-templatekit
+
+[![Tests](https://github.com/Amogha-Hegde/fastapi-templatekit/actions/workflows/ci.yml/badge.svg)](https://github.com/Amogha-Hegde/fastapi-templatekit/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/Amogha-Hegde/fastapi-templatekit/branch/main/graph/badge.svg)](https://codecov.io/gh/Amogha-Hegde/fastapi-templatekit)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-templatekit.svg)](https://pypi.org/project/fastapi-templatekit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-templatekit.svg)](https://pypi.org/project/fastapi-templatekit/)
+[![PyPI downloads](https://static.pepy.tech/badge/fastapi-templatekit)](https://pepy.tech/project/fastapi-templatekit)
+
+A FastAPI TemplateKit with a root-level, Django-style app layout.
+
+## CLI
+
+Create a new project without installing this template into that project's
+environment:
+
+```bash
+uvx fastapi-templatekit startproject myproject
+cd myproject
+uvx fastapi-templatekit startapp users
+```
+
+Create the project files directly in the current directory:
+
+```bash
+uvx fastapi-templatekit startproject myproject .
+```
+
+If generated files already exist, the CLI asks before overwriting them. Use
+`--force` to overwrite without a prompt:
+
+```bash
+uvx fastapi-templatekit startproject myproject . --force
+```
+
+Create the project at a custom path:
+
+```bash
+uvx fastapi-templatekit startproject myproject ../services/myproject
+```
+
+For local development from this repository:
+
+```bash
+uvx --from . fastapi-templatekit startproject myproject
+```
+
+Generated projects include a Typer management command to discover registered
+HTTP and websocket routes:
+
+```bash
+uv run myproject urls
+```
+
+Show available commands and details:
+
+```bash
+uvx fastapi-templatekit help
+```
+
+Add health probes to an existing generated project:
+
+```bash
+uvx fastapi-templatekit addhealthprobes
+```
+
+Create an app with optional websocket and database scaffolding:
+
+```bash
+uvx fastapi-templatekit startapp users
+uvx fastapi-templatekit startapp users --with-websockets --with-database
+```
+
+Generated projects keep the main router beside `main.py`:
+
+```text
+myproject/
+├── pyproject.toml
+├── fastapi_templatekit.toml
+├── myproject/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   └── router.py
+└── users/
+    ├── __init__.py
+    ├── router.py
+    ├── endpoints/
+    │   ├── __init__.py
+    │   └── api.py
+    ├── schemas/
+    │   ├── __init__.py
+    │   └── validator.py
+    ├── service/
+    │   ├── __init__.py
+    │   └── users_service.py
+    ├── models/          # created only with database/tables enabled
+    │   └── __init__.py
+    └── websocket/       # created only with websockets enabled
+        ├── __init__.py
+        └── router.py
+```
+
+## Structure
+
+```text
+.
+├── api/           # top-level router registration
+├── health/        # example domain app at project root
+├── main/
+│   ├── config.py  # settings and config live here
+│   └── app.py     # FastAPI declaration lives here
+└── pyproject.toml
+```
+
+This follows the same domain-first idea from `fastapi-best-practices`, but without a `src/` directory.
+Feature apps and the shared API router live directly under the project root, similar to Django apps.
+
+## Run
+
+```bash
+uv run uvicorn main.app:app --reload
+```
+
+## WebSockets
+
+WebSocket routes are mounted under the same API prefix, so the default endpoint is:
+
+```text
+/api/v1/ws/{room_name}
+```
+
+There is also a built-in browser test page at:
+
+```text
+/api/v1/ws/test
+```
+
+This app uses `fastapi-websockets` with the package's environment-based channel-layer loader.
+For websocket-related environment configuration, refer to https://github.com/Amogha-Hegde/fastapi-websockets.
+
+Tests force `FASTAPI_WEBSOCKETS_BACKEND=inmemory` so they do not depend on a running database.
+
+Example session:
+
+```text
+connect ws://127.0.0.1:8000/api/v1/ws/demo
+receive {"event":"connected","room":"demo",...}
+send {"sender":"alice","message":"hello"}
+receive {"event":"message","room":"demo","sender":"alice","message":"hello"}
+```
+
+## Add a new app
+
+Create a root-level package such as `users/` or `orders/`, define its router there, and include it from your project's main `router.py`.

fastapi_templatekit-0.1.0/fastapi_templatekit/__init__.py

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

fastapi_templatekit-0.1.0/fastapi_templatekit/cli.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import argparse
+
+from fastapi_templatekit.commands.addhealthprobes import add_addhealthprobes_parser
+from fastapi_templatekit.commands.help import add_help_parser
+from fastapi_templatekit.commands.startapp import add_startapp_parser
+from fastapi_templatekit.commands.startproject import add_startproject_parser
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fastapi-templatekit",
+        description="Create FastAPI projects and apps.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    add_startproject_parser(subparsers)
+    add_startapp_parser(subparsers)
+    add_addhealthprobes_parser(subparsers)
+    add_help_parser(subparsers)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    args.handler(args)
+
+
+if __name__ == "__main__":
+    main()

fastapi_templatekit-0.1.0/fastapi_templatekit/commands/__init__.py

@@ -0,0 +1 @@
+

fastapi_templatekit-0.1.0/fastapi_templatekit/commands/addhealthprobes.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from fastapi_templatekit.commands.project import load_project_config
+from fastapi_templatekit.commands.rendering import render_template
+
+
+HEALTHPROBES_APP_NAME = "healthprobes"
+
+HEALTHPROBES_TEMPLATES = (
+    ("healthprobes/__init__.py.tpl", "healthprobes/__init__.py"),
+    ("healthprobes/router.py.tpl", "healthprobes/router.py"),
+    ("healthprobes/endpoints/__init__.py.tpl", "healthprobes/endpoints/__init__.py"),
+    ("healthprobes/endpoints/api.py.tpl", "healthprobes/endpoints/api.py"),
+    ("healthprobes/schemas/__init__.py.tpl", "healthprobes/schemas/__init__.py"),
+    ("healthprobes/schemas/validator.py.tpl", "healthprobes/schemas/validator.py"),
+    ("healthprobes/service/__init__.py.tpl", "healthprobes/service/__init__.py"),
+    ("healthprobes/service/healthprobes_service.py.tpl", "healthprobes/service/healthprobes_service.py"),
+    ("healthprobes/models/__init__.py.tpl", "healthprobes/models/__init__.py"),
+)
+
+
+def add_addhealthprobes_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "addhealthprobes",
+        help="Add healthz and livez endpoints to an existing generated project.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing healthprobes files without prompting.",
+    )
+    parser.set_defaults(handler=handle_addhealthprobes)
+
+
+def handle_addhealthprobes(args: argparse.Namespace) -> None:
+    project_root = Path.cwd()
+    project = load_project_config(project_root)
+    apps_dir = project_root / project.get("apps_dir", ".")
+    app_dir = apps_dir / HEALTHPROBES_APP_NAME
+
+    context = {
+        "app_name": HEALTHPROBES_APP_NAME,
+        "route_prefix": HEALTHPROBES_APP_NAME,
+    }
+    destinations = [
+        apps_dir / destination_pattern.format(**context)
+        for _, destination_pattern in HEALTHPROBES_TEMPLATES
+    ]
+    existing_paths = [destination for destination in destinations if destination.exists()]
+
+    if existing_paths and not args.force:
+        conflicts = "\n".join(f"  {path}" for path in existing_paths)
+        print(f"Healthprobes files already exist:\n{conflicts}")
+        answer = input("Overwrite these files? [y/N]: ").strip().lower()
+        if answer not in {"y", "yes"}:
+            raise SystemExit("Aborted.")
+
+    for template_path, destination_pattern in HEALTHPROBES_TEMPLATES:
+        destination = apps_dir / destination_pattern.format(**context)
+        render_template(template_path, destination, context)
+
+    print(f"Created health probes app at {app_dir}")
+    print("Register the router in your project router:")
+    print("  from healthprobes.router import router as healthprobes_router")
+    print("  api_router.include_router(healthprobes_router, tags=[\"healthprobes\"])")

fastapi_templatekit-0.1.0/fastapi_templatekit/commands/help.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+
+
+HELP_TEXT = """fastapi-templatekit
+
+Available commands:
+
+  startproject <name> [directory]
+    Create a new FastAPI project.
+
+    Examples:
+      fastapi-templatekit startproject myproject
+      fastapi-templatekit startproject myproject .
+      fastapi-templatekit startproject myproject ../services/myproject
+
+    Details:
+      - Without directory, creates ./<name>/.
+      - With '.', creates project files in the current directory.
+      - With a custom directory, creates project files at that path.
+      - If generated files already exist, asks before overwriting.
+      - Use --force to overwrite generated files without prompting.
+
+  startapp <name>
+    Create a root-level app inside an existing generated project.
+
+    Example:
+      fastapi-templatekit startapp users
+      fastapi-templatekit startapp users --with-websockets --with-database
+
+    Details:
+      - Must be run from a directory containing fastapi_templatekit.toml.
+      - Creates endpoints, schemas, service, and router.py.
+      - Includes a hello-world GET endpoint.
+      - Asks whether to include websockets.
+      - Asks whether to include database/tables.
+      - Use --with-websockets to add websocket scaffolding without prompting for it.
+      - Use --with-database to add the models folder without prompting for it.
+      - Prints the router registration lines for your project router.py.
+
+  addhealthprobes
+    Create a root-level healthprobes app inside an existing generated project.
+
+    Example:
+      fastapi-templatekit addhealthprobes
+
+    Details:
+      - Must be run from a directory containing fastapi_templatekit.toml.
+      - Creates /healthz and /livez GET endpoints.
+      - Prints the router registration lines for your project router.py.
+      - Use --force to overwrite generated healthprobes files without prompting.
+
+  help
+    Show this command summary.
+
+Use 'fastapi-templatekit <command> --help' for argparse usage details.
+"""
+
+
+def add_help_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "help",
+        help="Show available commands and details.",
+    )
+    parser.set_defaults(handler=handle_help)
+
+
+def handle_help(_: argparse.Namespace) -> None:
+    print(HELP_TEXT)

fastapi_templatekit-0.1.0/fastapi_templatekit/commands/project.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def load_project_config(project_root: Path) -> dict[str, Any]:
+    marker_path = project_root / "fastapi_templatekit.toml"
+
+    if not marker_path.exists():
+        raise SystemExit(
+            "Error: command must be run inside a fastapi-templatekit project.\n"
+            "Run: fastapi-templatekit startproject <project_name>"
+        )
+
+    marker = tomllib.loads(marker_path.read_text(encoding="utf-8"))
+    project = marker.get("project", {})
+    if not isinstance(project, dict):
+        raise SystemExit(f"Error: invalid project config: {marker_path}")
+
+    return project

fastapi_templatekit-0.1.0/fastapi_templatekit/commands/rendering.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from string import Template
+
+
+TEMPLATE_ROOT = "fastapi_templatekit.templates"
+
+
+def render_template(template_path: str, destination: Path, context: dict[str, str]) -> None:
+    template = resources.files(TEMPLATE_ROOT).joinpath(template_path)
+    content = Template(template.read_text(encoding="utf-8")).safe_substitute(context)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(content, encoding="utf-8")