oe-python-template 0.9.7__py3-none-any.whl → 0.10.0__py3-none-any.whl

oe_python_template/hello/_service.py

@@ -0,0 +1,96 @@
+"""Service of the hello module."""
+
+import secrets
+import string
+from http import HTTPStatus
+from typing import Any
+
+import requests
+
+from oe_python_template.utils import BaseService, Health
+
+from ._constants import HELLO_WORLD_DE_DE, HELLO_WORLD_EN_US
+from ._models import Echo, Utterance
+from ._settings import Language, Settings
+
+
+# Services derived from BaseService and exported by modules via their __init__.py are automatically registered
+# with the system module, enabling for dynamic discovery of health, info and further functionality.
+class Service(BaseService):
+    """Service of the hello module."""
+
+    _settings: Settings
+
+    def __init__(self) -> None:
+        """Initialize service."""
+        super().__init__(Settings)
+
+    def info(self) -> dict[str, Any]:  # noqa: PLR6301
+        """Determine info of this service.
+
+        Returns:
+            dict[str,Any]: The info of this service.
+        """
+        random_string = "".join(secrets.choice(string.ascii_letters + string.digits) for _ in range(5))
+
+        return {"noise": random_string}
+
+    @staticmethod
+    def _determine_connectivity() -> Health:
+        """Determine healthiness of connectivity with the Internet.
+
+        - Performs HTTP GET request to https://connectivitycheck.gstatic.com/generate_204
+        - If the call fails or does not return the expected response status, the health is DOWN.
+        - If the call succeeds, the health is UP.
+
+        Returns:
+            Health: The healthiness of connectivity.
+        """
+        try:
+            response = requests.get("https://connectivitycheck.gstatic.com/generate_204", timeout=5)
+            if response.status_code == HTTPStatus.NO_CONTENT:
+                return Health(status=Health.Code.UP)
+            return Health(status=Health.Code.DOWN, reason=f"Unexpected response status: {response.status_code}")
+        except requests.RequestException as e:
+            return Health(status=Health.Code.DOWN, reason=str(e))
+
+    def health(self) -> Health:
+        """Determine health of hello service.
+
+        Returns:
+            Health: The health of the service.
+        """
+        return Health(
+            status=Health.Code.UP,
+            components={
+                "connectivity": self._determine_connectivity(),
+            },
+        )
+
+    def get_hello_world(self) -> str:
+        """
+        Get a hello world message.
+
+        Returns:
+            str: Hello world message.
+        """
+        match self._settings.language:
+            case Language.GERMAN:
+                return HELLO_WORLD_DE_DE
+        return HELLO_WORLD_EN_US
+
+    @staticmethod
+    def echo(utterance: Utterance) -> Echo:
+        """
+        Loudly echo utterance.
+
+        Args:
+            utterance (Utterance): The utterance to echo.
+
+        Returns:
+            Echo: The loudly echoed utterance.
+
+        Raises:
+            ValueError: If the utterance is empty or contains only whitespace.
+        """
+        return Echo(text=utterance.text.upper())

oe_python_template/{settings.py → hello/_settings.py}

@@ -1,4 +1,4 @@
-"""Settings of OE Python Template."""
+"""Settings of the hello module."""
 
 from enum import StrEnum
 from typing import Annotated
@@ -6,7 +6,7 @@ from typing import Annotated
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from . import __project_name__
+from oe_python_template.utils import __env_file__, __project_name__
 
 
 class Language(StrEnum):
@@ -16,13 +16,15 @@ class Language(StrEnum):
     US_ENGLISH = "en_US"
 
 
+# Settings derived from BaseSettings and exported by modules via their __init__.py are automatically registered
+# by the system module e.g. for showing all settings via the system info command.
 class Settings(BaseSettings):
     """Settings."""
 
     model_config = SettingsConfigDict(
-        env_prefix=f"{__project_name__.upper()}_",
+        env_prefix=f"{__project_name__.upper()}_HELLO_",
         extra="ignore",
-        env_file=".env",
+        env_file=__env_file__,
         env_file_encoding="utf-8",
     )
 

oe_python_template/system/__init__.py

@@ -0,0 +1,17 @@
+"""Hello module."""
+
+from ._api import api_routers
+from ._cli import cli
+from ._service import Service
+
+__all__ = [
+    "Service",
+    "api_routers",
+    "cli",
+]
+
+# Export all individual API routers so they are picked up by depdency injection (DI)
+for version, router in api_routers.items():
+    router_name = f"api_{version}"
+    globals()[router_name] = router
+    del router

oe_python_template/system/_api.py

@@ -0,0 +1,78 @@
+"""API operations of system module.
+
+This module provides a webservice API with several operations:
+- A health/healthz endpoint that returns the health status of the service
+
+The endpoints use Pydantic models for request and response validation.
+"""
+
+from collections.abc import Callable, Generator
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Response, status
+
+from ..constants import API_VERSIONS  # noqa: TID252
+from ..utils import Health, VersionedAPIRouter  # noqa: TID252
+from ._service import Service
+
+
+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
+
+
+def register_health_endpoint(router: APIRouter) -> Callable[..., Health]:
+    """Register health endpoint to the given router.
+
+    Args:
+        router: The router to register the health endpoint to.
+
+    Returns:
+        Callable[..., Health]: The health endpoint function.
+    """
+
+    @router.get("/healthz")
+    @router.get("/health")
+    def health_endpoint(service: Annotated[Service, Depends(get_service)], response: Response) -> Health:
+        """Determine aggregate health of the system.
+
+        The health is aggregated from all modules that make
+            up this system including external dependencies.
+
+        The response is to be interpreted as follows:
+        - The 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 503 Service Unavailable status code if the service is unhealthy.
+
+        Args:
+            service (Service): The service instance.
+            response (Response): The FastAPI response object.
+
+        Returns:
+            Health: The health of the system.
+        """
+        health = service.health()
+        if health.status == Health.Code.DOWN:
+            response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+
+        return health
+
+    return health_endpoint
+
+
+api_routers = {}
+for version in API_VERSIONS:
+    router = VersionedAPIRouter(version, tags=["system"])
+    api_routers[version] = router
+    health = register_health_endpoint(api_routers[version])

oe_python_template/system/_cli.py

@@ -0,0 +1,165 @@
+"""System CLI commands."""
+
+import json
+import os
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+import uvicorn
+import yaml
+
+from ..constants import API_VERSIONS  # noqa: TID252
+from ..utils import __project_name__, console, get_logger  # noqa: TID252
+from ._service import Service
+
+logger = get_logger(__name__)
+
+cli = typer.Typer(name="system", help="System commands")
+
+_service = Service()
+
+
+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 health(
+    output_format: Annotated[
+        OutputFormat, typer.Option(help="Output format", case_sensitive=False)
+    ] = OutputFormat.JSON,
+) -> None:
+    """Determine and print system health.
+
+    Args:
+        output_format (OutputFormat): Output format (JSON or YAML).
+    """
+    match output_format:
+        case OutputFormat.JSON:
+            console.print_json(data=_service.health().model_dump())
+        case OutputFormat.YAML:
+            console.print(
+                yaml.dump(data=json.loads(_service.health().model_dump_json()), width=80, default_flow_style=False),
+                end="",
+            )
+
+
+@cli.command()
+def info(
+    include_environ: Annotated[bool, typer.Option(help="Include environment variables")] = False,
+    filter_secrets: Annotated[bool, typer.Option(help="Filter secrets")] = True,
+    output_format: Annotated[
+        OutputFormat, typer.Option(help="Output format", case_sensitive=False)
+    ] = OutputFormat.JSON,
+) -> None:
+    """Determine and print system info.
+
+    Args:
+        include_environ (bool): Include environment variables.
+        filter_secrets (bool): Filter secrets from the output.
+        output_format (OutputFormat): Output format (JSON or YAML).
+    """
+    info = _service.info(include_environ=include_environ, filter_secrets=filter_secrets)
+    match output_format:
+        case OutputFormat.JSON:
+            console.print_json(data=info)
+        case OutputFormat.YAML:
+            console.print(yaml.dump(info, width=80, default_flow_style=False), end="")
+
+
+@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 webservice API server.
+
+    Args:
+        host (str): Host to bind the server to.
+        port (int): Port to bind the server to.
+        watch (bool): Enable auto-reload.
+    """
+    console.print(f"Starting API server at http://{host}:{port}")
+    # using environ to pass host/port to api.py to generate doc link
+    os.environ["UVICORN_HOST"] = host
+    os.environ["UVICORN_PORT"] = str(port)
+    uvicorn.run(
+        f"{__project_name__}.api:app",
+        host=host,
+        port=port,
+        reload=watch,
+    )
+
+
+@cli.command()
+def openapi(
+    api_version: Annotated[
+        str, typer.Option(help=f"API Version. Available: {', '.join(API_VERSIONS.keys())}", case_sensitive=False)
+    ] = next(iter(API_VERSIONS.keys())),
+    output_format: Annotated[
+        OutputFormat, typer.Option(help="Output format", case_sensitive=False)
+    ] = OutputFormat.JSON,
+) -> None:
+    """Dump the OpenAPI specification.
+
+    Args:
+        api_version (str): API version to dump.
+        output_format (OutputFormat): Output format (JSON or YAML).
+
+    Raises:
+        typer.Exit: If an invalid API version is provided.
+    """
+    from ..api import api_instances  # noqa: PLC0415, TID252
+
+    if api_version not in API_VERSIONS:
+        available_versions = ", ".join(API_VERSIONS.keys())
+        console.print(
+            f"[bold red]Error:[/] Invalid API version '{api_version}'. Available versions: {available_versions}"
+        )
+        raise typer.Exit(code=1)
+
+    schema = api_instances[api_version].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="")
+
+
+@cli.command()
+def fail() -> None:
+    """Fail by dividing by zero.
+
+    - Used to validate error handling and instrumentation.
+    """
+    Service.div_by_zero()
+
+
+@cli.command()
+def sleep(
+    seconds: Annotated[int, typer.Option(help="Duration in seconds")] = 10,
+) -> None:
+    """Sleep given for given number of seconds.
+
+    Args:
+        seconds (int): Number of seconds to sleep.
+
+    - Used to validate performance profiling.
+    """
+    Service.sleep(seconds)

oe_python_template/system/_service.py

@@ -0,0 +1,163 @@
+"""System service."""
+
+import json
+import os
+import platform
+import pwd
+import sys
+import time
+from typing import Any
+
+from pydantic_settings import BaseSettings
+
+from ..utils import (  # noqa: TID252
+    BaseService,
+    Health,
+    __env__,
+    __project_name__,
+    __project_path__,
+    __repository_url__,
+    __version__,
+    get_process_info,
+    load_settings,
+    locate_subclasses,
+)
+
+
+class Service(BaseService):
+    """System service."""
+
+    def __init__(self) -> None:
+        """Initialize service."""
+        super().__init__()
+
+    @staticmethod
+    def _is_healthy() -> bool:
+        """Check if the service itself is healthy.
+
+        Returns:
+            bool: True if the service is healthy, False otherwise.
+        """
+        return True
+
+    def health(self) -> Health:
+        """Determine aggregate health of the system.
+
+        - Health exposed by implementations of BaseService in other
+            modules is automatically included into the health tree.
+        - See utils/_health.py:Health for an explanation of the health tree.
+
+        Returns:
+            Health: The aggregate health of the system.
+        """
+        components: dict[str, Health] = {}
+        for service_class in locate_subclasses(BaseService):
+            if service_class is not Service:
+                components[f"{service_class.__module__}.{service_class.__name__}"] = service_class().health()
+
+        # Set the system health status based on is_healthy attribute
+        status = Health.Code.UP if self._is_healthy() else Health.Code.DOWN
+        reason = None if self._is_healthy() else "System marked as unhealthy"
+        return Health(status=status, components=components, reason=reason)
+
+    @staticmethod
+    def info(include_environ: bool = False, filter_secrets: bool = True) -> dict[str, Any]:
+        """
+        Get info about configuration of service.
+
+        - Runtime information is automatically compiled.
+        - Settings are automatically aggregated from all implementations of
+            Pydantic BaseSettings in this package.
+        - Info exposed by implementations of BaseService in other modules is
+            automatically included into the info dict.
+
+        Returns:
+            dict[str, Any]: Service configuration.
+        """
+        rtn = {
+            "package": {
+                "version": __version__,
+                "name": __project_name__,
+                "repository": __repository_url__,
+                "local": __project_path__,
+            },
+            "runtime": {
+                "environment": __env__,
+                "python": {
+                    "version": platform.python_version(),
+                    "compiler": platform.python_compiler(),
+                    "implementation": platform.python_implementation(),
+                },
+                "interpreter_path": sys.executable,
+                "command_line": " ".join(sys.argv),
+                "entry_point": sys.argv[0] if sys.argv else None,
+                "process_info": json.loads(get_process_info().model_dump_json()),
+                "username": pwd.getpwuid(os.getuid())[0],
+                "host": {
+                    "system": platform.system(),
+                    "release": platform.release(),
+                    "version": platform.version(),
+                    "machine": platform.machine(),
+                    "processor": platform.processor(),
+                    "hostname": platform.node(),
+                    "ip_address": platform.uname().node,
+                    "cpu_count": os.cpu_count(),
+                },
+            },
+        }
+
+        if include_environ:
+            if filter_secrets:
+                rtn["runtime"]["environ"] = {
+                    k: v
+                    for k, v in os.environ.items()
+                    if not (
+                        "token" in k.lower()
+                        or "key" in k.lower()
+                        or "secret" in k.lower()
+                        or "password" in k.lower()
+                        or "auth" in k.lower()
+                    )
+                }
+            else:
+                rtn["runtime"]["environ"] = dict(os.environ)
+
+        settings = {}
+        for settings_class in locate_subclasses(BaseSettings):
+            settings_instance = load_settings(settings_class)
+            env_prefix = settings_instance.model_config.get("env_prefix", "")
+            settings_dict = json.loads(settings_instance.model_dump_json())
+            for key, value in settings_dict.items():
+                flat_key = f"{env_prefix}{key}".upper()
+                settings[flat_key] = value
+        rtn["settings"] = settings
+
+        for service_class in locate_subclasses(BaseService):
+            if service_class is not Service:
+                service = service_class()
+                rtn[service.key()] = service.info()
+
+        return rtn
+
+    @staticmethod
+    def div_by_zero() -> float:
+        """Divide by zero to trigger an error.
+
+        - This function is used to validate error handling and instrumentation
+            in the system.
+
+        Returns:
+            float: This function will raise a ZeroDivisionError before returning.
+        """
+        return 1 / 0
+
+    @staticmethod
+    def sleep(seconds: int) -> None:
+        """Sleep for a given number of seconds.
+
+        - This function is used to validate performance profiling in the system.
+
+        Args:
+            seconds (int): Number of seconds to sleep.
+        """
+        time.sleep(seconds)

oe_python_template/utils/__init__.py

@@ -0,0 +1,57 @@
+"""Utilities module."""
+
+from ._api import VersionedAPIRouter
+from ._cli import prepare_cli
+from ._console import console
+from ._constants import (
+    __author_email__,
+    __author_name__,
+    __documentation__url__,
+    __env__,
+    __env_file__,
+    __is_development_mode__,
+    __is_running_in_container__,
+    __project_name__,
+    __project_path__,
+    __repository_url__,
+    __version__,
+)
+from ._di import locate_implementations, locate_subclasses
+from ._health import Health
+from ._log import LogSettings, get_logger
+from ._logfire import LogfireSettings
+from ._process import ProcessInfo, get_process_info
+from ._sentry import SentrySettings
+from ._service import BaseService
+from ._settings import load_settings
+from .boot import boot
+
+__all__ = [
+    "BaseService",
+    "Health",
+    "LogSettings",
+    "LogSettings",
+    "LogfireSettings",
+    "ProcessInfo",
+    "SentrySettings",
+    "VersionedAPIRouter",
+    "__author_email__",
+    "__author_name__",
+    "__documentation__url__",
+    "__env__",
+    "__env_file__",
+    "__is_development_mode__",
+    "__is_running_in_container__",
+    "__project_name__",
+    "__project_path__",
+    "__repository_url__",
+    "__version__",
+    "boot",
+    "console",
+    "get_logger",
+    "get_process_info",
+    "load_settings",
+    "locate_implementations",
+    "locate_subclasses",
+    "prepare_cli",
+]

oe_python_template/utils/_api.py

@@ -0,0 +1,18 @@
+from fastapi import APIRouter
+
+
+class VersionedAPIRouter(APIRouter):
+    """APIRouter with version attribute.
+
+    - Use this class to create versioned routers for your FastAPI application
+        that are automatically registered into the FastAPI app.
+    - The version attribute is used to identify the version of the API
+        that the router corresponds to.
+    - See constants.por versions defined for this system.
+    """
+
+    version: str
+
+    def __init__(self, version: str, *args, **kwargs) -> None:  # type: ignore[no-untyped-def]
+        super().__init__(*args, **kwargs)
+        self.version = version

oe_python_template/utils/_cli.py

@@ -0,0 +1,68 @@
+"""Command-line interface utilities."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from ._di import locate_implementations
+
+
+def prepare_cli(cli: typer.Typer, epilog: str) -> None:
+    """
+    Dynamically locate, register and prepare subcommands.
+
+    Args:
+        cli (typer.Typer): Typer instance
+        epilog (str): Epilog to add
+    """
+    for _cli in locate_implementations(typer.Typer):
+        if _cli != cli:
+            cli.add_typer(_cli)
+
+    cli.info.epilog = epilog
+    cli.info.no_args_is_help = True
+    if not any(arg.endswith("typer") for arg in Path(sys.argv[0]).parts):
+        for command in cli.registered_commands:
+            command.epilog = cli.info.epilog
+
+    # add epilog for all subcommands
+    if not any(arg.endswith("typer") for arg in Path(sys.argv[0]).parts):
+        _add_epilog_recursively(cli, epilog)
+
+    # add no_args_is_help for all subcommands
+    _no_args_is_help_recursively(cli)
+
+
+def _add_epilog_recursively(cli: typer.Typer, epilog: str) -> None:
+    """
+    Add epilog to all typers in the tree.
+
+    Args:
+        cli (typer.Typer): Typer instance
+        epilog (str): Epilog to add
+    """
+    cli.info.epilog = epilog
+    for group in cli.registered_groups:
+        if isinstance(group, typer.models.TyperInfo):
+            typer_instance = group.typer_instance
+            if (typer_instance is not cli) and typer_instance:
+                _add_epilog_recursively(typer_instance, epilog)
+    for command in cli.registered_commands:
+        if isinstance(command, typer.models.CommandInfo):
+            command.epilog = cli.info.epilog
+
+
+def _no_args_is_help_recursively(cli: typer.Typer) -> None:
+    """
+    Show help if no command is given by the user.
+
+    Args:
+        cli (typer.Typer): Typer instance
+    """
+    for group in cli.registered_groups:
+        if isinstance(group, typer.models.TyperInfo):
+            group.no_args_is_help = True
+            typer_instance = group.typer_instance
+            if (typer_instance is not cli) and typer_instance:
+                _no_args_is_help_recursively(typer_instance)