oe-python-template-example 0.3.4__py3-none-any.whl → 0.3.6__py3-none-any.whl

oe_python_template_example/__init__.py

@@ -1,20 +1,6 @@
-"""Example project scaffolded and kept up to date with OE Python Template (oe-python-template)."""
+"""Copier template to scaffold Python projects compliant with best practices and modern tooling."""
 
-from .constants import (
-    __project_name__,
-    __project_path__,
-    __version__,
-)
-from .models import Echo, Health, HealthStatus, Utterance
-from .service import Service
+from .constants import MODULES_TO_INSTRUMENT
+from .utils.boot import boot
 
-__all__ = [
-    "Echo",
-    "Health",
-    "HealthStatus",
-    "Service",
-    "Utterance",
-    "__project_name__",
-    "__project_path__",
-    "__version__",
-]
+boot(modules_to_instrument=MODULES_TO_INSTRUMENT)

oe_python_template_example/api.py

@@ -1,44 +1,30 @@
 """Webservice API of OE Python Template Example.
 
-This module provides a webservice API with several endpoints:
-- A health/healthz endpoint that returns the health status of the service
-- A hello-world endpoint that returns a greeting message
-- An echo endpoint that echoes back the provided text
-
-The endpoints use Pydantic models for request and response validation.
+- Provides a versioned API
+- Automatically registers APIs of modules and mounts them to the main API.
 """
 
 import os
-from collections.abc import Generator
-from typing import Annotated
 
-from fastapi import Depends, FastAPI, Response, status
-from pydantic import BaseModel, Field
+from fastapi import FastAPI
 
-from . import Echo, Health, HealthStatus, Service, Utterance
+from .constants import API_VERSIONS
+from .utils import (
+    VersionedAPIRouter,
+    __author_email__,
+    __author_name__,
+    __documentation__url__,
+    __repository_url__,
+    locate_implementations,
+)
 
 TITLE = "OE Python Template Example"
-HELLO_WORLD_EXAMPLE = "Hello, world!"
 UVICORN_HOST = os.environ.get("UVICORN_HOST", "127.0.0.1")
 UVICORN_PORT = os.environ.get("UVICORN_PORT", "8000")
-CONTACT_NAME = "Helmut Hoffer von Ankershoffen"
-CONTACT_EMAIL = "helmuthva@gmail.com"
-CONTACT_URL = "https://github.com/helmut-hoffer-von-ankershoffen"
-TERMS_OF_SERVICE_URL = "https://oe-python-template-example.readthedocs.io/en/latest/"
-
-
-def get_service() -> Generator[Service, None, None]:
-    """Get the service instance.
-
-    Yields:
-        Service: The service instance.
-    """
-    service = Service()
-    try:
-        yield service
-    finally:
-        # Cleanup code if needed
-        pass
+CONTACT_NAME = __author_name__
+CONTACT_EMAIL = __author_email__
+CONTACT_URL = __repository_url__
+TERMS_OF_SERVICE_URL = __documentation__url__
 
 
 app = FastAPI(
@@ -52,130 +38,38 @@ app = FastAPI(
     terms_of_service=TERMS_OF_SERVICE_URL,
     openapi_tags=[
         {
-            "name": "v1",
-            "description": "API version 1, check link on the right",
+            "name": version,
+            "description": f"API version {version.lstrip('v')}, check link on the right",
             "externalDocs": {
                 "description": "sub-docs",
-                "url": f"http://{UVICORN_HOST}:{UVICORN_PORT}/api/v1/docs",
+                "url": f"http://{UVICORN_HOST}:{UVICORN_PORT}/api/{version}/docs",
             },
-        },
-        {
-            "name": "v2",
-            "description": "API version 2, check link on the right",
-            "externalDocs": {
-                "description": "sub-docs",
-                "url": f"http://{UVICORN_HOST}:{UVICORN_PORT}/api/v2/docs",
-            },
-        },
+        }
+        for version, _ in API_VERSIONS.items()
     ],
 )
 
-api_v1 = FastAPI(
-    version="1.0.0",
-    title=TITLE,
-    contact={
-        "name": CONTACT_NAME,
-        "email": CONTACT_EMAIL,
-        "url": CONTACT_URL,
-    },
-    terms_of_service=TERMS_OF_SERVICE_URL,
-)
-
-api_v2 = FastAPI(
-    version="2.0.0",
-    title=TITLE,
-    contact={
-        "name": CONTACT_NAME,
-        "email": CONTACT_EMAIL,
-        "url": CONTACT_URL,
-    },
-    terms_of_service=TERMS_OF_SERVICE_URL,
-)
-
-
-@api_v1.get("/healthz", tags=["Observability"])
-@api_v1.get("/health", tags=["Observability"])
-@api_v2.get("/healthz", tags=["Observability"])
-@api_v2.get("/health", tags=["Observability"])
-async def health(service: Annotated[Service, Depends(get_service)], response: Response) -> Health:
-    """Check the health of the service.
-
-    This endpoint returns the health status of the service.
-    The health status can be either UP or DOWN.
-    If the service is healthy, the status will be UP.
-    If the service is unhealthy, the status will be DOWN and a reason will be provided.
-    The response will have a 200 OK status code if the service is healthy,
-    and a 500 Internal Server Error status code if the service is unhealthy.
-
-    Returns:
-        Health: The health status of the service.
-    """
-    if service.healthy():
-        health_result = Health(status=HealthStatus.UP)
-    else:
-        health_result = Health(status=HealthStatus.DOWN, reason="Service is unhealthy")
-
-    if health_result.status == HealthStatus.DOWN:
-        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
-
-    return health_result
-
-
-class _HelloWorldResponse(BaseModel):
-    """Response model for hello-world endpoint."""
-
-    message: str = Field(
-        ...,
-        description="The hello world message",
-        examples=[HELLO_WORLD_EXAMPLE],
+# Create API instances for each version
+api_instances: dict["str", FastAPI] = {}
+for version, semver in API_VERSIONS.items():
+    api_instances[version] = FastAPI(
+        version=semver,
+        title=TITLE,
+        contact={
+            "name": CONTACT_NAME,
+            "email": CONTACT_EMAIL,
+            "url": CONTACT_URL,
+        },
+        terms_of_service=TERMS_OF_SERVICE_URL,
     )
 
+# Register routers with appropriate API versions
+for router in locate_implementations(VersionedAPIRouter):
+    router_instance: VersionedAPIRouter = router
+    version = router_instance.version
+    if version in API_VERSIONS:
+        api_instances[version].include_router(router_instance)
 
-@api_v1.get("/hello-world", tags=["Basics"])
-@api_v2.get("/hello-world", tags=["Basics"])
-async def hello_world(service: Annotated[Service, Depends(get_service)]) -> _HelloWorldResponse:
-    """
-    Return a hello world message.
-
-    Returns:
-        _HelloWorldResponse: A response containing the hello world message.
-    """
-    return _HelloWorldResponse(message=service.get_hello_world())
-
-
-@api_v1.get("/echo/{text}", tags=["Basics"])
-async def echo(text: str) -> Echo:
-    """
-    Echo back the provided text.
-
-    Args:
-        text (str): The text to echo.
-
-    Returns:
-        Echo: The echo.
-
-    Raises:
-        422 Unprocessable Entity: If text is not provided or empty.
-    """
-    return Service.echo(Utterance(text=text))
-
-
-@api_v2.post("/echo", tags=["Basics"])
-async def echo_v2(request: Utterance) -> Echo:
-    """
-    Echo back the provided utterance.
-
-    Args:
-        request (Utterance): The utterance to echo back.
-
-    Returns:
-        Echo: The echo.
-
-    Raises:
-        422 Unprocessable Entity: If utterance is not provided or empty.
-    """
-    return Service.echo(request)
-
-
-app.mount("/v1", api_v1)
-app.mount("/v2", api_v2)
+# Mount all API versions to the main app
+for version in API_VERSIONS:
+    app.mount(f"/{version}", api_instances[version])

oe_python_template_example/cli.py

@@ -1,150 +1,22 @@
 """CLI (Command Line Interface) of OE Python Template Example."""
 
-import os
 import sys
-from enum import StrEnum
-from pathlib import Path
-from typing import Annotated
 
 import typer
-import uvicorn
-import yaml
-from rich.console import Console
 
-from . import Service, Utterance, __version__
-from .api import api_v1, api_v2
+from .constants import MODULES_TO_INSTRUMENT
+from .utils import __version__, boot, console, get_logger, prepare_cli
 
-cli = typer.Typer(help="Command Line Interface of OE Python Template Example")
-_service = Service()
-_console = Console()
+boot(MODULES_TO_INSTRUMENT)
+logger = get_logger(__name__)
 
+cli = typer.Typer(help="Command Line Interface of ")
+prepare_cli(cli, f"🧠 OE Python Template Example v{__version__} - built with love in Berlin 🐻")
 
-@cli.command()
-def health() -> None:
-    """Indicate if service is healthy."""
-    _console.print(_service.healthy())
-
-
-@cli.command()
-def info() -> None:
-    """Print info about service configuration."""
-    _console.print(_service.info())
-
-
-@cli.command()
-def echo(
-    text: Annotated[
-        str, typer.Argument(help="The text to echo")
-    ] = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
-    json: Annotated[
-        bool,
-        typer.Option(
-            help=("Print as JSON"),
-        ),
-    ] = False,
-) -> None:
-    """Echo the text."""
-    echo = Service.echo(Utterance(text=text))
-    if json:
-        _console.print_json(data={"text": echo.text})
-    else:
-        _console.print(echo.text)
-
-
-@cli.command()
-def hello_world() -> None:
-    """Print hello world message and what's in the environment variable THE_VAR."""
-    _console.print(_service.get_hello_world())
-
-
-@cli.command()
-def serve(
-    host: Annotated[str, typer.Option(help="Host to bind the server to")] = "127.0.0.1",
-    port: Annotated[int, typer.Option(help="Port to bind the server to")] = 8000,
-    watch: Annotated[bool, typer.Option(help="Enable auto-reload")] = True,
-) -> None:
-    """Start the API server."""
-    _console.print(f"Starting API server at http://{host}:{port}")
-    os.environ["UVICORN_HOST"] = host
-    os.environ["UVICORN_PORT"] = str(port)
-    uvicorn.run(
-        "oe_python_template_example.api:app",
-        host=host,
-        port=port,
-        reload=watch,
-    )
-
-
-class APIVersion(StrEnum):
-    """
-    Enum representing the API versions.
-
-    This enum defines the supported API verions:
-    - V1: Output doc for v1 API
-    - V2: Output doc for v2 API
-
-    Usage:
-        version = APIVersion.V1
-        print(f"Using {version} version")
-
-    """
-
-    V1 = "v1"
-    V2 = "v2"
-
-
-class OutputFormat(StrEnum):
-    """
-    Enum representing the supported output formats.
-
-    This enum defines the possible formats for output data:
-    - YAML: Output data in YAML format
-    - JSON: Output data in JSON format
-
-    Usage:
-        format = OutputFormat.YAML
-        print(f"Using {format} format")
-    """
-
-    YAML = "yaml"
-    JSON = "json"
-
-
-@cli.command()
-def openapi(
-    api_version: Annotated[APIVersion, typer.Option(help="API Version", case_sensitive=False)] = APIVersion.V1,
-    output_format: Annotated[
-        OutputFormat, typer.Option(help="Output format", case_sensitive=False)
-    ] = OutputFormat.YAML,
-) -> None:
-    """Dump the OpenAPI specification to stdout (YAML by default)."""
-    match api_version:
-        case APIVersion.V1:
-            schema = api_v1.openapi()
-        case APIVersion.V2:
-            schema = api_v2.openapi()
-    match output_format:
-        case OutputFormat.JSON:
-            _console.print_json(data=schema)
-        case OutputFormat.YAML:
-            _console.print(yaml.dump(schema, width=80, default_flow_style=False), end="")
-
-
-def _apply_cli_settings(cli: typer.Typer, epilog: str) -> None:
-    """Configure default behavior and add epilog to all typers in the tree."""
-    cli.info.no_args_is_help = True
-
-    if not any(arg.endswith("typer") for arg in Path(sys.argv[0]).parts):
-        cli.info.epilog = epilog
-        for command in cli.registered_commands:
-            command.epilog = cli.info.epilog
-
-
-_apply_cli_settings(
-    cli,
-    f"🧠 OE Python Template Example v{__version__} - built with love in Berlin 🐻",
-)
-
-
-if __name__ == "__main__":
-    cli()
+if __name__ == "__main__":  # pragma: no cover
+    try:
+        cli()
+    except Exception as e:  # noqa: BLE001
+        logger.critical("Fatal error occurred: %s", e)
+        console.print(f"Fatal error occurred: {e}", style="error")
+        sys.exit(1)

oe_python_template_example/constants.py

@@ -1,10 +1,7 @@
-"""Constants used throughout OE Python Template Example's codebase ."""
+"""Constants for the OE Python Template Example."""
 
-import importlib.metadata
-import pathlib
-
-__project_name__ = __name__.split(".")[0]
-__project_path__ = str(pathlib.Path(__file__).parent.parent.parent)
-__version__ = importlib.metadata.version(__project_name__)
-
-LOREM_IPSUM = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+API_VERSIONS = {
+    "v1": "1.0.0",
+    "v2": "2.0.0",
+}
+MODULES_TO_INSTRUMENT = ["oe_python_template_example.hello"]

oe_python_template_example/hello/__init__.py

@@ -0,0 +1,17 @@
+"""Hello module."""
+
+from ._api import api_v1, api_v2
+from ._cli import cli
+from ._models import Echo, Utterance
+from ._service import Service
+from ._settings import Settings
+
+__all__ = [
+    "Echo",
+    "Service",
+    "Settings",
+    "Utterance",
+    "api_v1",
+    "api_v2",
+    "cli",
+]

oe_python_template_example/hello/_api.py

@@ -0,0 +1,94 @@
+"""Webservice API of Hello module.
+
+This module provides a webservice API with several operations:
+- A hello/world operation that returns a greeting message
+- A hello/echo endpoint that echoes back the provided text
+"""
+
+from collections.abc import Generator
+from typing import Annotated
+
+from fastapi import Depends
+from pydantic import BaseModel, Field
+
+from oe_python_template_example.utils import VersionedAPIRouter
+
+from ._models import Echo, Utterance
+from ._service import Service
+
+HELLO_WORLD_EXAMPLE = "Hello, world!"
+
+# VersionedAPIRouters exported by modules via their __init__.py are automatically registered
+# and injected into the main API app, see ../api.py.
+api_v1 = VersionedAPIRouter("v1", prefix="/hello", tags=["hello"])
+api_v2 = VersionedAPIRouter("v2", prefix="/hello", tags=["hello"])
+
+
+def get_service() -> Generator[Service, None, None]:
+    """Get instance of Service.
+
+    Yields:
+        Service: The service instance.
+    """
+    service = Service()
+    try:
+        yield service
+    finally:
+        # Cleanup code if needed
+        pass
+
+
+class _HelloWorldResponse(BaseModel):
+    """Response model for hello-world endpoint."""
+
+    message: str = Field(
+        ...,
+        description="The hello world message",
+        examples=[HELLO_WORLD_EXAMPLE],
+    )
+
+
+@api_v1.get("/world")
+@api_v2.get("/world")
+def hello_world(service: Annotated[Service, Depends(get_service)]) -> _HelloWorldResponse:
+    """
+    Return a hello world message.
+
+    Returns:
+        _HelloWorldResponse: A response containing the hello world message.
+    """
+    return _HelloWorldResponse(message=service.get_hello_world())
+
+
+@api_v1.get("/echo/{text}")
+def echo(text: str) -> Echo:
+    """
+    Echo back the provided text.
+
+    Args:
+        text (str): The text to echo.
+
+    Returns:
+        Echo: The echo.
+
+    Raises:
+        422 Unprocessable Entity: If text is not provided or empty.
+    """
+    return Service.echo(Utterance(text=text))
+
+
+@api_v2.post("/echo")
+def echo_v2(request: Utterance) -> Echo:
+    """
+    Echo back the provided utterance.
+
+    Args:
+        request (Utterance): The utterance to echo back.
+
+    Returns:
+        Echo: The echo.
+
+    Raises:
+        422 Unprocessable Entity: If utterance is not provided or empty.
+    """
+    return Service.echo(request)

oe_python_template_example/hello/_cli.py

@@ -0,0 +1,47 @@
+"""CLI (Command Line Interface) of OE Python Template Example."""
+
+from typing import Annotated
+
+import typer
+
+from oe_python_template_example.utils import console, get_logger
+
+from ._models import Utterance
+from ._service import Service
+
+logger = get_logger(__name__)
+
+# CLI apps exported by modules via their __init__.py are automatically registered and injected into the main CLI app
+cli = typer.Typer(name="hello", help="Hello commands")
+_service = Service()
+
+
+@cli.command()
+def echo(
+    text: Annotated[
+        str, typer.Argument(help="The text to echo")
+    ] = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+    json: Annotated[
+        bool,
+        typer.Option(
+            help=("Print as JSON"),
+        ),
+    ] = False,
+) -> None:
+    """Echo the text.
+
+    Args:
+        text (str): The text to echo.
+        json (bool): Print as JSON.
+    """
+    echo = Service.echo(Utterance(text=text))
+    if json:
+        console.print_json(data={"text": echo.text})
+    else:
+        console.print(echo.text)
+
+
+@cli.command()
+def world() -> None:
+    """Print hello world message and what's in the environment variable THE_VAR."""
+    console.print(_service.get_hello_world())

oe_python_template_example/hello/_constants.py

@@ -0,0 +1,4 @@
+"""Constants of the hello module."""
+
+HELLO_WORLD_EN_US = "Hello, world!"
+HELLO_WORLD_DE_DE = "Hallo, Welt!"

oe_python_template_example/hello/_models.py

@@ -0,0 +1,28 @@
+"""Models of the hello module."""
+
+from pydantic import BaseModel, Field
+
+_UTTERANCE_EXAMPLE = "Hello, world!"
+_ECHO_EXAMPLE = "HELLO, WORLD!"
+
+
+class Utterance(BaseModel):
+    """Model representing a text utterance."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        description="The utterance to echo back",
+        examples=[_UTTERANCE_EXAMPLE],
+    )
+
+
+class Echo(BaseModel):
+    """Response model for echo endpoint."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        description="The echo",
+        examples=[_ECHO_EXAMPLE],
+    )