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

oe_python_template_example/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_example.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)  # automatically loads and validates the 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_example/{settings.py → hello/_settings.py}

@@ -1,4 +1,4 @@
-"""Settings of OE Python Template Example."""
+"""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_example.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_example/system/__init__.py

@@ -0,0 +1,19 @@
+"""Hello module."""
+
+from ._api import api_routers
+from ._cli import cli
+from ._service import Service
+from ._settings import Settings
+
+__all__ = [
+    "Service",
+    "Settings",
+    "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_example/system/_api.py

@@ -0,0 +1,116 @@
+"""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, Any
+
+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("/system/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 making
+            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
+
+
+def register_info_endpoint(router: APIRouter) -> Callable[..., dict[str, Any]]:
+    """Register info endpoint to the given router.
+
+    Args:
+        router: The router to register the info endpoint to.
+
+    Returns:
+        Callable[..., Health]: The health endpoint function.
+    """
+
+    @router.get("/system/info")
+    def info_endpoint(
+        service: Annotated[Service, Depends(get_service)], response: Response, token: str
+    ) -> dict[str, Any]:
+        """Determine aggregate info of the system.
+
+        The info is aggregated from all modules making up this system.
+
+        If the token does not match the setting, a 403 Forbidden status code is returned.
+
+        Args:
+            service (Service): The service instance.
+            response (Response): The FastAPI response object.
+            token (str): Token to present.
+
+        Returns:
+            dict[str, Any]: The aggregate info of the system.
+        """
+        if service.is_token_valid(token):
+            return service.info(include_environ=True, filter_secrets=False)
+
+        response.status_code = status.HTTP_403_FORBIDDEN
+        return {"error": "Forbidden"}
+
+    return info_endpoint
+
+
+api_routers = {}
+for version in API_VERSIONS:
+    router = VersionedAPIRouter(version, tags=["system"])
+    api_routers[version] = router
+    health = register_health_endpoint(api_routers[version])
+    info = register_info_endpoint(api_routers[version])

oe_python_template_example/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_example/system/_service.py

@@ -0,0 +1,182 @@
+"""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
+    UNHIDE_SENSITIVE_INFO,
+    BaseService,
+    Health,
+    __env__,
+    __project_name__,
+    __project_path__,
+    __repository_url__,
+    __version__,
+    get_logger,
+    get_process_info,
+    load_settings,
+    locate_subclasses,
+)
+from ._settings import Settings
+
+logger = get_logger(__name__)
+
+
+class Service(BaseService):
+    """System service."""
+
+    _settings: Settings
+
+    def __init__(self) -> None:
+        """Initialize service."""
+        super().__init__(Settings)
+
+    @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)
+
+    def is_token_valid(self, token: str) -> bool:
+        """Check if the presented token is valid.
+
+        Returns:
+            bool: True if the token is valid, False otherwise.
+        """
+        logger.info(token)
+        if not self._settings.token:
+            logger.warning("Token is not set in settings.")
+            return False
+        return token == self._settings.token.get_secret_value()
+
+    @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 = settings_instance.model_dump(context={UNHIDE_SENSITIVE_INFO: not filter_secrets})
+            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_example/system/_settings.py

@@ -0,0 +1,31 @@
+"""Settings of the system module."""
+
+from typing import Annotated
+
+from pydantic import Field, PlainSerializer, SecretStr
+from pydantic_settings import SettingsConfigDict
+
+from ..utils import OpaqueSettings, __env_file__, __project_name__  # noqa: TID252
+
+
+class Settings(OpaqueSettings):
+    """Settings."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=f"{__project_name__.upper()}_SYSTEM_",
+        extra="ignore",
+        env_file=__env_file__,
+        env_file_encoding="utf-8",
+    )
+
+    token: Annotated[
+        SecretStr | None,
+        PlainSerializer(func=OpaqueSettings.serialize_sensitive_info, return_type=str, when_used="always"),
+        Field(
+            description=(
+                "Secret token to present when performing sensitive operations such as "
+                "retrieving info via webservice API"
+            ),
+            default=None,
+        ),
+    ]