scaffold-ca-python 0.1.1__py3-none-any.whl

scaffold_ca_python/templates/entry_point/mcp/test_tools.py.jinja2

@@ -0,0 +1,40 @@
+"""Tests for {{ project.python_package }}.infrastructure.entry_points.mcp_server.tools."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from unittest.mock import MagicMock
+
+from {{ project.python_package }}.infrastructure.entry_points.mcp_server.tools import bind_tools
+
+
+def _make_mock_mcp() -> tuple[MagicMock, dict[str, object]]:
+    """Return (mock_mcp, registered) where registered maps tool name → handler."""
+    registered: dict[str, object] = {}
+    mock = MagicMock()
+    mock.tool = lambda name: (lambda fn: registered.setdefault(name, fn) or fn)
+    return mock, registered
+
+
+def test_bind_tools_is_async_callable() -> None:
+    """bind_tools must be an async function (or wrap one via @inject)."""
+    fn = getattr(bind_tools, "__wrapped__", bind_tools)
+    assert inspect.iscoroutinefunction(fn), "bind_tools must be async"
+
+
+def test_bind_tools_registers_example_tool() -> None:
+    """Calling bind_tools registers 'example_tool' on the mcp instance."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_tools, "__wrapped__", bind_tools)
+    asyncio.run(fn(mock_mcp))
+    assert "example_tool" in registered
+
+
+def test_example_tool_returns_expected_result() -> None:
+    """The example_tool inner function returns a string containing the query."""
+    mock_mcp, registered = _make_mock_mcp()
+    fn = getattr(bind_tools, "__wrapped__", bind_tools)
+    asyncio.run(fn(mock_mcp))
+    result = asyncio.run(registered["example_tool"]("hello"))  # type: ignore[operator]
+    assert "hello" in result

scaffold_ca_python/templates/entry_point/mcp/tools.py.jinja2

@@ -0,0 +1,22 @@
+"""MCP tools binding — register FastMCP tools via dependency injection."""
+
+from __future__ import annotations
+
+from dependency_injector.wiring import Provide, inject
+from mcp.server.fastmcp import FastMCP
+
+from {{ project.python_package }}.application.config.container import Container
+
+
+@inject
+async def bind_tools(
+    mcp: FastMCP,
+    # Replace with your actual use-case injection:
+    # some_usecase: SomeUseCase = Provide[Container.usecase_container.some_usecase],
+) -> None:
+    """Bind all MCP tools to the server instance."""
+
+    @mcp.tool("example_tool")
+    async def example_tool(query: str) -> str:
+        """Example tool stub — replace with your implementation."""
+        return f"result for: {query}"

scaffold_ca_python/templates/entry_point/restapi/__init__.py.jinja2

@@ -0,0 +1 @@
+"""REST API entry-point package."""

scaffold_ca_python/templates/entry_point/restapi/app.py.jinja2

@@ -0,0 +1,78 @@
+"""FastAPI application factory for {{ project.name }}."""
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException
+
+from {{ project.python_package }}.application.config.container import Container
+from {{ project.python_package }}.application.config.config import Settings
+from {{ project.python_package }}.infrastructure.entry_points.api.v1 import rest_controller
+from {{ project.python_package }}.infrastructure.entry_points.api.v1.exception_handler import (
+    generic_exception_handler,
+    http_exception_handler,
+    validation_exception_handler,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> None:
+    """Wire the DI container on startup and unwire on shutdown."""
+    container: Container = app.state.container  # type: ignore[attr-defined]
+    container.wire(
+        modules=[
+            rest_controller,
+        ]
+    )
+    logger.info("Application startup complete.")
+    # Uncomment to initialize async resources on startup, if needed
+    # await container.resource_container.init_resources()
+    yield
+    container.unwire()
+    # Uncomment the following line if you have async resources to shutdown
+    # await container.resource_container.shutdown_resources()
+    logger.info("Application shutdown complete.")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    settings = Settings()
+    container = Container()
+
+    app = FastAPI(
+        title="{{ project.name }}",
+        lifespan=lifespan,
+        root_path="/api"
+    )
+    app.state.container = container  # type: ignore[attr-defined]
+    app.state.settings = settings  # type: ignore[attr-defined]
+
+    app.add_exception_handler(HTTPException, http_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(Exception, generic_exception_handler)  # type: ignore[arg-type]
+
+    app.include_router(rest_controller.router)
+
+    return app
+
+
+def start_server() -> None:
+    """Launch uvicorn — called from the [project.scripts] entrypoint."""
+    settings = Settings()
+    uvicorn.run(
+        "{{ project.python_package }}.application.app:create_app",
+        host=getattr(settings, "HOST", "0.0.0.0"),
+        port=int(getattr(settings, "PORT", 8000)),
+        factory=True,
+        reload=False,
+    )
+
+
+if __name__ == "__main__":
+    start_server()

scaffold_ca_python/templates/entry_point/restapi/exception_handler.py.jinja2

@@ -0,0 +1,35 @@
+"""Exception handlers for {{ project.name }} REST API."""
+from __future__ import annotations
+
+import logging
+
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+
+logger = logging.getLogger(__name__)
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    """Handle HTTP exceptions raised by route handlers."""
+    logger.warning("HTTP %s: %s — %s %s", exc.status_code, exc.detail, request.method, request.url)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+async def validation_exception_handler(
+    request: Request,
+    exc: RequestValidationError,
+) -> JSONResponse:
+    """Handle Pydantic validation errors on incoming requests."""
+    logger.warning("Validation error on %s %s: %s", request.method, request.url, exc.errors())
+    return JSONResponse(
+        status_code=422,
+        content={"detail": exc.errors()},
+    )
+
+
+async def generic_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Catch-all handler for unexpected exceptions."""
+    logger.exception("Unhandled exception on %s %s", request.method, request.url)
+    return JSONResponse(status_code=500, content={"detail": "Internal server error"})

scaffold_ca_python/templates/entry_point/restapi/health.py.jinja2

@@ -0,0 +1,13 @@
+"""Health-check endpoint."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("")
+async def health() -> dict[str, str]:
+    """Return service liveness status."""
+    return {"status": "ok"}

scaffold_ca_python/templates/entry_point/restapi/rest_controller.py.jinja2

@@ -0,0 +1,26 @@
+"""REST controller — versioned API router for {{ project.name }}."""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/v1")
+{% if routes %}
+{% for path, method in routes %}
+
+@router.{{ method }}("{{ path }}")
+async def {{ method }}_{{ path | replace("/", "_") | replace("-", "_") | trim("_") }}() -> JSONResponse:
+    """Handle {{ method.upper() }} {{ path }}."""
+    raise NotImplementedError
+{% endfor %}
+{% else %}
+
+@router.get("/health")
+async def health() -> JSONResponse:
+    """Health check endpoint."""
+    return JSONResponse(content={"status": "app is online"})
+{% endif %}

scaffold_ca_python/templates/entry_point/restapi/server.py.jinja2

@@ -0,0 +1,5 @@
+"""Server entry point for {{ project.name }} — delegates to the application factory."""
+from {{ project.python_package }}.application.app import start_server
+
+if __name__ == "__main__":
+    start_server()

scaffold_ca_python/templates/entry_point/restapi/test_app.py.jinja2

@@ -0,0 +1,22 @@
+"""Tests for application factory — {{ project.name }}."""
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from {{ project.python_package }}.application.app import create_app
+
+
+def test_create_app_returns_fastapi_instance() -> None:
+    app = create_app()
+    assert isinstance(app, FastAPI)
+
+
+def test_create_app_has_router_included() -> None:
+    app = create_app()
+    routes = [r.path for r in app.routes]  # type: ignore[attr-defined]
+    assert any("/api" in p or "/health" in p for p in routes)
+
+
+def test_create_app_registers_exception_handlers() -> None:
+    app = create_app()
+    assert app.exception_handlers  # type: ignore[attr-defined]

scaffold_ca_python/templates/entry_point/restapi/test_exception_handler.py.jinja2

@@ -0,0 +1,44 @@
+"""Tests for exception handlers — {{ project.name }}."""
+from __future__ import annotations
+
+from fastapi import HTTPException
+from fastapi.testclient import TestClient
+
+from {{ project.python_package }}.application.app import create_app
+
+_client = TestClient(create_app(), raise_server_exceptions=False)
+
+
+def test_http_exception_returns_json_with_status_code() -> None:
+    app = create_app()
+
+    @app.get("/_test_http_error")
+    def _raise_http() -> None:
+        raise HTTPException(status_code=404, detail="not found")
+
+    client = TestClient(app, raise_server_exceptions=False)
+    response = client.get("/_test_http_error")
+    assert response.status_code == 404
+
+
+def test_unhandled_exception_returns_500() -> None:
+    app = create_app()
+
+    @app.get("/_test_unhandled")
+    def _raise_unhandled() -> None:
+        raise RuntimeError("boom")
+
+    client = TestClient(app, raise_server_exceptions=False)
+    response = client.get("/_test_unhandled")
+    assert response.status_code == 500
+
+
+def test_validation_error_returns_422() -> None:
+    app = create_app()
+    client = TestClient(app, raise_server_exceptions=False)
+    # POST to /api/v1 with bad payload should trigger RequestValidationError → 422
+    response = client.post(
+        "/api/v1/",
+        json={"bad_field": True},
+    )
+    assert response.status_code in (422, 404, 405)

scaffold_ca_python/templates/entry_point/restapi/test_rest_controller.py.jinja2

@@ -0,0 +1,35 @@
+"""Tests for {{ project.name }} REST API health endpoint."""
+from __future__ import annotations
+
+import pytest
+from starlette.testclient import TestClient
+
+from {{ project.python_package }}.application.app import create_app
+
+
+@pytest.fixture()
+def client() -> TestClient:
+    """TestClient fixture wired to the FastAPI application.
+
+    Add DI overrides here before constructing TestClient, e.g.:
+        app = create_app()
+        app.state.container.my_service.override(MockService())
+    """
+    return TestClient(create_app())
+
+
+def test_health_returns_200(client: TestClient) -> None:
+    """GET /v1/health must return HTTP 200."""
+    response = client.get("/v1/health")
+    assert response.status_code == 200
+
+
+def test_health_returns_online_status(client: TestClient) -> None:
+    """GET /v1/health body must contain a status key."""
+    response = client.get("/v1/health")
+    assert response.json().get("status") is not None
+
+
+# ---------------------------------------------------------------------------
+# Add your custom endpoint tests below this line
+# ---------------------------------------------------------------------------

scaffold_ca_python/templates/entry_point/restapi/test_server.py.jinja2

@@ -0,0 +1,15 @@
+"""Tests for server entry point — {{ project.name }}."""
+from __future__ import annotations
+
+import importlib
+
+
+def test_start_server_is_callable() -> None:
+    from {{ project.python_package }}.application.app import start_server
+
+    assert callable(start_server)
+
+
+def test_server_module_imports_without_error() -> None:
+    mod = importlib.import_module("{{ project.python_package }}.server")
+    assert mod is not None

scaffold_ca_python/templates/helper/__init__.py.jinja2

@@ -0,0 +1 @@
+"""{{ class_name }} helper package."""

scaffold_ca_python/templates/helper/helper.py.jinja2

@@ -0,0 +1,7 @@
+"""{{ class_name }} helper."""
+
+
+class {{ class_name }}:
+    """{{ class_name }} utility helper."""
+
+    pass

scaffold_ca_python/templates/helper/test_helper.py.jinja2

@@ -0,0 +1,8 @@
+"""Tests for {{ class_name }}."""
+
+from {{ project.python_package }}.infrastructure.helpers.{{ module_name }}.{{ module_name }} import {{ class_name }}
+
+
+def test_{{ module_name }}_instantiation() -> None:
+    helper = {{ class_name }}()
+    assert helper is not None

scaffold_ca_python/templates/model/model.py.jinja2

@@ -0,0 +1,9 @@
+"""{{ class_name }} domain model."""
+
+from pydantic import BaseModel
+
+
+class {{ class_name }}(BaseModel):
+    """{{ class_name }} entity."""
+
+    pass

scaffold_ca_python/templates/model/test_model.py.jinja2

@@ -0,0 +1,8 @@
+"""Tests for {{ class_name }} domain model."""
+
+from {{ project.python_package }}.domain.model.{{ module_name }} import {{ class_name }}
+
+
+def test_{{ module_name }}_can_be_instantiated() -> None:
+    instance = {{ class_name }}()
+    assert instance is not None

scaffold_ca_python/templates/pipeline/azure/azure_pipelines.yml.jinja2

@@ -0,0 +1,28 @@
+trigger:
+  branches:
+    include:
+      - main
+      - master
+
+pool:
+  vmImage: "ubuntu-latest"
+
+steps:
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: "3.13"
+    displayName: "Set up Python 3.13"
+
+  - script: |
+      pip install uv
+      uv sync --all-extras
+    displayName: "Install dependencies"
+
+  - script: uv run ruff check src/ tests/
+    displayName: "Lint (ruff)"
+
+  - script: uv run mypy src/
+    displayName: "Type check (mypy)"
+
+  - script: uv run pytest --cov=src/ --cov-fail-under=80
+    displayName: "Test (pytest + coverage)"

scaffold_ca_python/templates/pipeline/github/ci.yml.jinja2

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/
+
+      - name: Test (pytest + coverage)
+        run: uv run pytest --cov=src/ --cov-fail-under=80

scaffold_ca_python/templates/project/README.jinja2

@@ -0,0 +1,30 @@
+# {{ name }}
+
+A Clean Architecture Python project.
+
+## Getting Started
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Architecture
+
+```
+src/{{ python_package }}/
+├── application/          # Application bootstrap and DI wiring
+├── domain/
+│   ├── model/            # Entities, value objects (Pydantic v2)
+│   └── usecase/          # Business logic, async use cases
+└── infrastructure/
+    ├── driven_adapters/  # Outbound adapters (DB, HTTP, secrets)
+    ├── entry_points/     # Inbound adapters (REST, CLI, events)
+    └── helpers/          # Cross-cutting utilities
+
+tests/                    # Mirrors src/ structure
+```
+
+## Package
+
+`{{ package }}`

scaffold_ca_python/templates/project/application/config/__init__.py.jinja2

@@ -0,0 +1 @@
+"""DI configuration package."""

scaffold_ca_python/templates/project/application/config/config.py.jinja2

@@ -0,0 +1,12 @@
+"""Application settings loaded from environment / .env file."""
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    ENV: str = "development"
+    LOG_LEVEL: str = "INFO"
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+
+settings = Settings()

scaffold_ca_python/templates/project/application/config/container.py.jinja2

@@ -0,0 +1,17 @@
+"""Root application DI container."""
+from dependency_injector import containers, providers
+
+from {{ python_package }}.application.config.resource_container import ResourceContainer
+from {{ python_package }}.application.config.driven_adapters_container import DAContainer
+from {{ python_package }}.application.config.usecases_container import UseCaseContainer
+
+
+class Container(containers.DeclarativeContainer):
+    """Top-level container wiring all sub-containers."""
+
+    resource_container = providers.Container(ResourceContainer)
+    da_container = providers.Container(DAContainer)
+    usecase_container = providers.Container(
+        UseCaseContainer,
+        da_container=da_container,
+    )

scaffold_ca_python/templates/project/application/config/driven_adapters_container.py.jinja2

@@ -0,0 +1,14 @@
+"""Driven-adapters DI container."""
+from dependency_injector import containers, providers
+
+# Import driven-adapter classes here to wire them in the DAContainer below.
+#{{ python_package }}.infrastructure.driven_adapters.my_repo.MyRepo
+
+class DAContainer(containers.DeclarativeContainer):
+    """Wire infrastructure driven-adapter singletons here."""
+
+    # Example:
+    # my_repo = providers.Singleton(
+    #     MyRepo,
+    #     arg1=arg1,
+    # )

scaffold_ca_python/templates/project/application/config/resource_container.py.jinja2

@@ -0,0 +1,17 @@
+"""Resource DI container — wires infrastructure resources (DB pools, HTTP clients, etc.)."""
+from dependency_injector import containers, providers
+
+from {{ python_package }}.application.config.config import settings
+
+# Import resource-level classes here to wire them in the ResourceContainer below.
+#{{ python_package }}.infrastructure.driven_adapters.my_repo.MyResource
+
+
+class ResourceContainer(containers.DeclarativeContainer):
+    """Wire resource-level singletons (connections, clients) here."""
+
+    # Example:
+    # db_pool = providers.Resource(
+    #     MyResource,
+    #     arg1=settings.ARG1,
+    # )

scaffold_ca_python/templates/project/application/config/usecases_container.py.jinja2

@@ -0,0 +1,16 @@
+"""Use-case DI container."""
+from dependency_injector import containers, providers
+
+# Import use-case classes here to wire them in the UseCaseContainer below.
+#{{ python_package }}.application.usecases.my_use_case.MyUseCase
+
+class UseCaseContainer(containers.DeclarativeContainer):
+    """Wire use-case singletons here, injecting driven adapters."""
+
+    da_container = providers.DependenciesContainer()
+
+    # Example:
+    # my_use_case = providers.Singleton(
+    #     MyUseCase,
+    #     arg1=da_container.my_repo,
+    # )

scaffold_ca_python/templates/project/dockerfile.jinja2

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+FROM python:3.13-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Install dependencies (cached layer)
+COPY pyproject.toml .
+RUN uv sync --no-dev --no-install-project
+
+# Copy source
+COPY src/ src/
+
+# Install project
+RUN uv sync --no-dev
+
+CMD ["python", "-m", "{{ python_package }}"]

scaffold_ca_python/templates/project/dockerignore.jinja2

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.git/
+.github/
+*.log
+*.env
+.env*
+coverage/
+.coverage
+htmlcov/