fastapi-templatekit 0.1.0__py3-none-any.whl

fastapi_templatekit/__init__.py

@@ -0,0 +1 @@
+__version__ = "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/commands/__init__.py

@@ -0,0 +1 @@
+

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/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/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/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")

fastapi_templatekit/commands/startapp.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import argparse
+import tomllib
+from pathlib import Path
+
+from fastapi_templatekit.commands.project import load_project_config
+from fastapi_templatekit.commands.rendering import render_template
+from fastapi_templatekit.commands.validation import normalize_package_name, validate_package_name
+
+
+BASE_APP_TEMPLATES = (
+    ("app/__init__.py.tpl", "{app_name}/__init__.py"),
+    ("app/router.py.tpl", "{app_name}/router.py"),
+    ("app/endpoints/__init__.py.tpl", "{app_name}/endpoints/__init__.py"),
+    ("app/endpoints/api.py.tpl", "{app_name}/endpoints/api.py"),
+    ("app/schemas/__init__.py.tpl", "{app_name}/schemas/__init__.py"),
+    ("app/schemas/validator.py.tpl", "{app_name}/schemas/validator.py"),
+    ("app/service/__init__.py.tpl", "{app_name}/service/__init__.py"),
+    ("app/service/app_service.py.tpl", "{app_name}/service/{app_name}_service.py"),
+)
+
+DATABASE_APP_TEMPLATES = (
+    ("app/models/__init__.py.tpl", "{app_name}/models/__init__.py"),
+)
+
+WEBSOCKET_APP_TEMPLATES = (
+    ("app/websocket/__init__.py.tpl", "{app_name}/websocket/__init__.py"),
+    ("app/websocket/router.py.tpl", "{app_name}/websocket/router.py"),
+)
+
+WEBSOCKET_DEPENDENCY = "fastapi-websockets"
+WEBSOCKET_CONFIG_DOCS_URL = "https://github.com/Amogha-Hegde/fastapi-websockets"
+
+
+def add_startapp_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "startapp",
+        help="Create a FastAPI app inside an existing generated project.",
+    )
+    parser.add_argument("name", help="App name.")
+    parser.add_argument(
+        "--with-websockets",
+        action="store_true",
+        help="Add a websocket folder with a sample websocket route.",
+    )
+    parser.add_argument(
+        "--with-database",
+        action="store_true",
+        help="Add a models folder for database tables.",
+    )
+    parser.set_defaults(handler=handle_startapp)
+
+
+def handle_startapp(args: argparse.Namespace) -> None:
+    project_root = Path.cwd()
+    project = load_project_config(project_root)
+    apps_dir = project_root / project.get("apps_dir", ".")
+
+    app_name = validate_package_name(
+        normalize_package_name(args.name),
+        "App name",
+    )
+    app_dir = apps_dir / app_name
+
+    if app_dir.exists():
+        raise SystemExit(f"Error: app already exists: {app_dir}")
+
+    include_websockets = args.with_websockets or ask_yes_no("Do you want to include websockets?")
+    include_database = args.with_database or ask_yes_no("Do you want to include database/tables?")
+
+    context = {
+        "app_name": app_name,
+        "app_class_name": "".join(part.capitalize() for part in app_name.split("_")),
+        "route_prefix": app_name.replace("_", "-"),
+    }
+
+    templates = list(BASE_APP_TEMPLATES)
+    if include_database:
+        templates.extend(DATABASE_APP_TEMPLATES)
+    if include_websockets:
+        templates.extend(WEBSOCKET_APP_TEMPLATES)
+
+    for template_path, destination_pattern in templates:
+        destination = apps_dir / destination_pattern.format(**context)
+        render_template(template_path, destination, context)
+
+    if include_websockets:
+        ensure_project_dependency(project_root, WEBSOCKET_DEPENDENCY)
+
+    print(f"Created FastAPI app '{app_name}' at {app_dir}")
+    print("Register the router in your project API router:")
+    print(f"  from {app_name}.router import router as {app_name}_router")
+    print(f"  api_router.include_router({app_name}_router, prefix=\"/{context['route_prefix']}\", tags=[\"{app_name}\"])")
+    if include_websockets:
+        print("Register the websocket router in your project API router:")
+        print(f"  from {app_name}.websocket.router import router as {app_name}_websocket_router")
+        print(f"  api_router.include_router({app_name}_websocket_router, prefix=\"/{context['route_prefix']}\")")
+        print(
+            "Info: for websocket-related environment configuration, refer to "
+            f"{WEBSOCKET_CONFIG_DOCS_URL}"
+        )
+
+
+def ask_yes_no(question: str) -> bool:
+    try:
+        answer = input(f"{question} [y/N]: ").strip().lower()
+    except EOFError:
+        return False
+    return answer in {"y", "yes"}
+
+
+def ensure_project_dependency(project_root: Path, dependency: str) -> None:
+    pyproject_path = project_root / "pyproject.toml"
+    if not pyproject_path.exists():
+        raise SystemExit(f"Error: missing project config: {pyproject_path}")
+
+    content = pyproject_path.read_text(encoding="utf-8")
+    parsed = tomllib.loads(content)
+    dependencies = parsed.get("project", {}).get("dependencies", [])
+    if not isinstance(dependencies, list):
+        dependencies = []
+
+    dependency_name = normalize_dependency_name(dependency)
+    if any(normalize_dependency_name(item) == dependency_name for item in dependencies):
+        return
+
+    lines = content.splitlines(keepends=True)
+    dependencies_start = next(
+        (index for index, line in enumerate(lines) if line.strip() == "dependencies = ["),
+        None,
+    )
+
+    if dependencies_start is None:
+        project_start = next(
+            (index for index, line in enumerate(lines) if line.strip() == "[project]"),
+            None,
+        )
+        if project_start is None:
+            raise SystemExit(f"Error: invalid project config: {pyproject_path}")
+        lines[project_start + 1 : project_start + 1] = [
+            "dependencies = [\n",
+            f'    "{dependency}",\n',
+            "]\n",
+        ]
+        pyproject_path.write_text("".join(lines), encoding="utf-8")
+        return
+
+    dependencies_end = next(
+        (
+            index
+            for index in range(dependencies_start + 1, len(lines))
+            if lines[index].strip() == "]"
+        ),
+        None,
+    )
+    if dependencies_end is None:  # pragma: no cover
+        raise SystemExit(f"Error: invalid dependencies array: {pyproject_path}")
+
+    lines.insert(dependencies_end, f'    "{dependency}",\n')
+    pyproject_path.write_text("".join(lines), encoding="utf-8")
+
+
+def normalize_dependency_name(dependency: object) -> str:
+    if not isinstance(dependency, str):
+        return ""
+    name = dependency
+    for separator in ("[", "<", ">", "=", "~", "!", ";"):
+        name = name.split(separator, 1)[0]
+    return name.strip().lower().replace("_", "-")

fastapi_templatekit/commands/startproject.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from fastapi_templatekit.commands.rendering import render_template
+from fastapi_templatekit.commands.validation import normalize_package_name, validate_package_name
+
+
+PROJECT_TEMPLATES = (
+    ("project/pyproject.toml.tpl", "pyproject.toml"),
+    ("project/gitignore.tpl", ".gitignore"),
+    ("project/fastapi_templatekit.toml.tpl", "fastapi_templatekit.toml"),
+    ("project/env.example.tpl", ".env.example"),
+    ("project/README.md.tpl", "README.md"),
+    ("project/package/__init__.py.tpl", "{package_name}/__init__.py"),
+    ("project/package/cli.py.tpl", "{package_name}/cli.py"),
+    ("project/package/main.py.tpl", "{package_name}/main.py"),
+    ("project/package/config.py.tpl", "{package_name}/config.py"),
+    ("project/package/router.py.tpl", "{package_name}/router.py"),
+)
+
+
+def add_startproject_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "startproject",
+        help="Create a new FastAPI project.",
+    )
+    parser.add_argument("name", help="Project name.")
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        help="Optional destination directory. Use '.' to create files in the current directory.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing project files without prompting.",
+    )
+    parser.set_defaults(handler=handle_startproject)
+
+
+def handle_startproject(args: argparse.Namespace) -> None:
+    project_name = args.name.strip()
+    package_name = validate_package_name(
+        normalize_package_name(project_name),
+        "Project name",
+    )
+    target_dir = Path(args.directory or project_name).resolve()
+
+    if target_dir.exists() and not target_dir.is_dir():
+        raise SystemExit(f"Error: target path exists and is not a directory: {target_dir}")
+
+    context = {
+        "project_name": project_name,
+        "package_name": package_name,
+    }
+
+    destinations = [
+        target_dir / destination_pattern.format(**context)
+        for _, destination_pattern in PROJECT_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"Project 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 PROJECT_TEMPLATES:
+        destination = target_dir / destination_pattern.format(**context)
+        render_template(template_path, destination, context)
+
+    print(f"Created FastAPI project '{project_name}' at {target_dir}")
+    print(f"Next steps:")
+    if target_dir != Path.cwd().resolve():
+        print(f"  cd {target_dir}")
+    print(f"  uv sync")
+    print(f"  uv run uvicorn {package_name}.main:app --reload")
+    print(f"  uv run {package_name} urls")

fastapi_templatekit/commands/validation.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import keyword
+import re
+
+
+PACKAGE_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def normalize_package_name(name: str) -> str:
+    return name.strip().replace("-", "_").replace(" ", "_").lower()
+
+
+def validate_package_name(name: str, label: str) -> str:
+    if not PACKAGE_RE.match(name) or keyword.iskeyword(name):
+        raise ValueError(f"{label} must be a valid Python package name.")
+    return name

fastapi_templatekit/templates/__init__.py

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/endpoints/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/endpoints/api.py.tpl

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from $app_name.schemas.validator import HelloWorldResponse
+from $app_name.service.${app_name}_service import get_hello_world_message
+
+
+router = APIRouter()
+
+
+@router.get("/", response_model=HelloWorldResponse)
+async def hello_world() -> HelloWorldResponse:
+    return HelloWorldResponse(message=get_hello_world_message())

fastapi_templatekit/templates/app/models/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/router.py.tpl

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from $app_name.endpoints.api import router as api_router
+
+
+router = APIRouter()
+router.include_router(api_router)

fastapi_templatekit/templates/app/schemas/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/schemas/validator.py.tpl

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HelloWorldResponse(BaseModel):
+    message: str

fastapi_templatekit/templates/app/service/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/service/app_service.py.tpl

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+def get_hello_world_message() -> str:
+    return "Hello from $app_name"

fastapi_templatekit/templates/app/websocket/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/app/websocket/router.py.tpl

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, WebSocket
+from fastapi_websockets import AsyncWebSocketConsumer, get_channel_layer
+
+
+router = APIRouter()
+channel_layer = get_channel_layer()
+
+
+class EchoConsumer(AsyncWebSocketConsumer):
+    async def connect(self) -> None:
+        await self.accept()
+
+    async def receive_text(self, text_data: str) -> None:
+        await self.send_json({"message": text_data})
+
+    async def disconnect(self, close_code: int | None) -> None:
+        print("WebSocket disconnected:", close_code)
+
+
+@router.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket) -> None:
+    consumer = EchoConsumer(layer=channel_layer)
+    await consumer(websocket)

fastapi_templatekit/templates/healthprobes/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/healthprobes/endpoints/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/healthprobes/endpoints/api.py.tpl

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from healthprobes.schemas.validator import HealthProbeResponse
+from healthprobes.service.healthprobes_service import get_health_status
+
+
+router = APIRouter()
+
+
+@router.get("/healthz", response_model=HealthProbeResponse)
+async def healthz() -> HealthProbeResponse:
+    return HealthProbeResponse(status=get_health_status())
+
+
+@router.get("/livez", response_model=HealthProbeResponse)
+async def livez() -> HealthProbeResponse:
+    return HealthProbeResponse(status=get_health_status())

fastapi_templatekit/templates/healthprobes/models/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/healthprobes/router.py.tpl

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from healthprobes.endpoints.api import router as api_router
+
+
+router = APIRouter()
+router.include_router(api_router)

fastapi_templatekit/templates/healthprobes/schemas/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/healthprobes/schemas/validator.py.tpl

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthProbeResponse(BaseModel):
+    status: str

fastapi_templatekit/templates/healthprobes/service/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/healthprobes/service/healthprobes_service.py.tpl

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+def get_health_status() -> str:
+    return "ok"

fastapi_templatekit/templates/project/README.md.tpl

@@ -0,0 +1,12 @@
+# $project_name
+
+```bash
+uv sync
+uv run uvicorn $package_name.main:app --reload
+```
+
+List registered HTTP and websocket routes:
+
+```bash
+uv run $package_name urls
+```

fastapi_templatekit/templates/project/env.example.tpl

@@ -0,0 +1,4 @@
+APP_NAME=$project_name
+APP_VERSION=0.1.0
+API_PREFIX=/api/v1
+DEBUG=false

fastapi_templatekit/templates/project/fastapi_templatekit.toml.tpl

@@ -0,0 +1,5 @@
+[project]
+name = "$project_name"
+package = "$package_name"
+template_version = "0.1.0"
+apps_dir = "."

fastapi_templatekit/templates/project/gitignore.tpl

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/

fastapi_templatekit/templates/project/package/__init__.py.tpl

@@ -0,0 +1 @@
+

fastapi_templatekit/templates/project/package/cli.py.tpl

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+import typer
+from fastapi.routing import APIRoute, APIWebSocketRoute
+from starlette.routing import Mount, Route, WebSocketRoute
+
+project_root = str(Path.cwd())
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from $package_name.main import app as fastapi_app
+
+
+app = typer.Typer(help="Project management commands.")
+
+
+@app.callback()
+def main() -> None:
+    """Project management commands."""
+
+
+@app.command("urls")
+def discover_urls() -> None:
+    """List HTTP and websocket routes registered on the FastAPI app."""
+    rows = list(iter_routes(fastapi_app.routes))
+
+    if not rows:
+        typer.echo("No routes found.")
+        return
+
+    protocol_width = max(len(row[0]) for row in rows + [("Protocol", "", "")])
+    methods_width = max(len(row[1]) for row in rows + [("Protocol", "Methods", "")])
+    path_width = max(len(row[2]) for row in rows + [("Protocol", "Methods", "Path")])
+
+    typer.echo(
+        f"{'Protocol'.ljust(protocol_width)}  "
+        f"{'Methods'.ljust(methods_width)}  "
+        f"{'Path'.ljust(path_width)}"
+    )
+    typer.echo(
+        f"{'-' * protocol_width}  "
+        f"{'-' * methods_width}  "
+        f"{'-' * path_width}"
+    )
+
+    for protocol, methods, path in rows:
+        typer.echo(
+            f"{protocol.ljust(protocol_width)}  "
+            f"{methods.ljust(methods_width)}  "
+            f"{path.ljust(path_width)}"
+        )
+
+
+def iter_routes(routes: Iterable[Route], prefix: str = "") -> Iterable[tuple[str, str, str]]:
+    for route in routes:
+        path = normalize_path(prefix, getattr(route, "path", ""))
+
+        if isinstance(route, APIRoute):
+            methods = ", ".join(sorted(route.methods or []))
+            yield ("HTTP", methods, path)
+            continue
+
+        if isinstance(route, Route):
+            methods = ", ".join(sorted(route.methods or []))
+            yield ("HTTP", methods, path)
+            continue
+
+        if isinstance(route, APIWebSocketRoute | WebSocketRoute):
+            yield ("WEBSOCKET", "WS", path)
+            continue
+
+        if isinstance(route, Mount):
+            yield from iter_routes(route.routes, path)
+
+
+def normalize_path(prefix: str, path: str) -> str:
+    combined = f"{prefix.rstrip('/')}/{path.lstrip('/')}"
+    if not combined.startswith("/"):
+        combined = f"/{combined}"
+    return combined.rstrip("/") or "/"
+
+
+if __name__ == "__main__":
+    app()

fastapi_templatekit/templates/project/package/config.py.tpl

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    app_name: str = "$project_name"
+    app_version: str = "0.1.0"
+    api_prefix: str = "/api/v1"
+    debug: bool = False
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+
+settings = Settings()

fastapi_templatekit/templates/project/package/main.py.tpl

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from $package_name.config import settings
+from $package_name.router import api_router
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    debug=settings.debug,
+)
+
+app.include_router(api_router, prefix=settings.api_prefix)

fastapi_templatekit/templates/project/package/router.py.tpl

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+
+api_router = APIRouter()

fastapi_templatekit/templates/project/pyproject.toml.tpl

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "$project_name"
+version = "0.1.0"
+description = "FastAPI application."
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi",
+    "typer",
+    "uvicorn[standard]",
+    "pydantic-settings",
+]
+
+[project.scripts]
+$package_name = "$package_name.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest",
+]
+
+[tool.setuptools.packages.find]
+include = ["$package_name*"]

fastapi_templatekit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,47 @@
+fastapi_templatekit/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+fastapi_templatekit/cli.py,sha256=E-yBqmP60HIK2Tx8zH0SzA8gNcwjfzS0NKcLjB-jjtM,918
+fastapi_templatekit/commands/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/commands/addhealthprobes.py,sha256=Oj_XoSeTRNAv1FNIzlKZc9xxMakQXaGaseyjJqyxOHw,2881
+fastapi_templatekit/commands/help.py,sha256=ZUN02MesRp0endKkg2oXhE4La_1QaPSeMik_-F-haWk,2318
+fastapi_templatekit/commands/project.py,sha256=KghyK3lhhEaeFudjU4rp_67QJ0PYbVN_HPWPnpb1Q4E,683
+fastapi_templatekit/commands/rendering.py,sha256=_m6GGxktwp1g6k1sF7kvgv3VC1WFDXTG33d7iukLHcs,534
+fastapi_templatekit/commands/startapp.py,sha256=dP_gajuqtZ2r0KBmzUigvIqPXuB8kv24UILZG8qxhog,6324
+fastapi_templatekit/commands/startproject.py,sha256=-BG5N8R3adCTdZWwF5yXIVBxUeSna3ms5eZa2CRmtmE,3099
+fastapi_templatekit/commands/validation.py,sha256=Ib7LVp2eeXBQnU1qR6Hqr9ib9pXzXLhtOrIHTZHcvPU,443
+fastapi_templatekit/templates/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/router.py.tpl,sha256=khwHC538LNXZLEkU-NVHMvR8vOkI6zVieY0E9vASego,181
+fastapi_templatekit/templates/app/endpoints/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/endpoints/api.py.tpl,sha256=M3CAWcXcu3MqZciuv0uCTzjWSYiKsdZHvvMdXjJ5JHU,389
+fastapi_templatekit/templates/app/models/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/schemas/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/schemas/validator.py.tpl,sha256=A9_APBMG_-egiE5voXPv-PnZteUCAwEMs4y9OWL1TwA,123
+fastapi_templatekit/templates/app/service/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/service/app_service.py.tpl,sha256=1ze1VEnfV5gw3Mae-hk0RgjA7zsvlvA8qE6s9YZJfQI,109
+fastapi_templatekit/templates/app/websocket/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/app/websocket/router.py.tpl,sha256=Kjs1f_2-L1wEpFeNWfahJnXfz-w4tz7L5GXreTUkqSc,716
+fastapi_templatekit/templates/healthprobes/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/healthprobes/router.py.tpl,sha256=Vh8uvXopYPwBdjmxWWjyUl75n6MvmH6e7f5u1gcZBGs,184
+fastapi_templatekit/templates/healthprobes/endpoints/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/healthprobes/endpoints/api.py.tpl,sha256=zGSbM_Li1n7F34qhXUrz6Bc_hk7GmBu7P4dmb_NtwX8,551
+fastapi_templatekit/templates/healthprobes/models/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/healthprobes/schemas/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/healthprobes/schemas/validator.py.tpl,sha256=bpfBokixSOMvmf-Qk1BsRK9sGAucKv4Nc0ZoOs58yZ8,123
+fastapi_templatekit/templates/healthprobes/service/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/healthprobes/service/healthprobes_service.py.tpl,sha256=n2jldjyLNQqC5xSJwaVjEi-e9MOxFjUzkeSmqGteYhg,85
+fastapi_templatekit/templates/project/README.md.tpl,sha256=zFFT6-KXuwTOJxDPnGTQrtjBLRqoBa0yhtbjmGRFLTM,167
+fastapi_templatekit/templates/project/env.example.tpl,sha256=2LRa8mcouRRFVGTQOc-zmFTh246_wVG4ItumgCRsL_E,72
+fastapi_templatekit/templates/project/fastapi_templatekit.toml.tpl,sha256=45CcoUgvhDuEkKnLeuo2n47IW5FaJLTolGtNld1BFXk,101
+fastapi_templatekit/templates/project/gitignore.tpl,sha256=ic-h9ptvPfgXO4m97l0UUybWoctSeb4YNpuXw9citWU,96
+fastapi_templatekit/templates/project/pyproject.toml.tpl,sha256=D0WgDKyHovAtclWa8B08wKywrhQ22qYd5ryCKlTWET0,464
+fastapi_templatekit/templates/project/package/__init__.py.tpl,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+fastapi_templatekit/templates/project/package/cli.py.tpl,sha256=Q2SY5mmreUdmtUUMEp4QsP8RTaxNj4tRZKzEy8Aeqtw,2508
+fastapi_templatekit/templates/project/package/config.py.tpl,sha256=nDPOMsU_e4snsjs7yu9nGnGVJXenZZR3_ewyQeUOySk,350
+fastapi_templatekit/templates/project/package/main.py.tpl,sha256=PFB_FFoxffRuJKYWNW50RaLMIGVMlfhMn5tXaaW6_4c,319
+fastapi_templatekit/templates/project/package/router.py.tpl,sha256=nZihMF6NZoN8wWhjIHYKqQ8HT8Vc1WN2pg4EI0vXISo,93
+fastapi_templatekit-0.1.0.dist-info/licenses/LICENSE,sha256=S0B0kuEbFCCQd4DGdkPtR5aRfzxrl5EKv9IWhfvWO0A,1069
+fastapi_templatekit-0.1.0.dist-info/METADATA,sha256=2Aqvd_7a_-F0EXwUYCT5oxdP61JCFRxxi3QdhPly6dw,4627
+fastapi_templatekit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastapi_templatekit-0.1.0.dist-info/entry_points.txt,sha256=DlCCF6MoNRRAVgLkssLHRpmL_UaFs7d6TsMI-42R6Xo,69
+fastapi_templatekit-0.1.0.dist-info/top_level.txt,sha256=8i6fSXbOuMBu1MY1In0UtDgBrP4_FWCjYvvlVXQUcUc,20
+fastapi_templatekit-0.1.0.dist-info/RECORD,,

fastapi_templatekit-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
+

fastapi_templatekit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastapi-templatekit = fastapi_templatekit.cli:main

fastapi_templatekit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_templatekit