oe-python-template-example 0.3.5__py3-none-any.whl → 0.3.7__py3-none-any.whl

oe_python_template_example/utils/__init__.py

@@ -0,0 +1,59 @@
+"""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 UNHIDE_SENSITIVE_INFO, OpaqueSettings, load_settings
+from .boot import boot
+
+__all__ = [
+    "UNHIDE_SENSITIVE_INFO",
+    "BaseService",
+    "Health",
+    "LogSettings",
+    "LogSettings",
+    "LogfireSettings",
+    "OpaqueSettings",
+    "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_example/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_example/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)

oe_python_template_example/utils/_console.py

@@ -0,0 +1,14 @@
+"""Themed rich console."""
+
+from rich.console import Console
+from rich.theme import Theme
+
+console = Console(
+    theme=Theme({
+        "logging.level.info": "purple4",
+        "debug": "light_cyan3",
+        "info": "purple4",
+        "warning": "yellow1",
+        "error": "red1",
+    }),
+)

oe_python_template_example/utils/_constants.py

@@ -0,0 +1,48 @@
+"""Constants used throughout."""
+
+import os
+import sys
+from importlib import metadata
+from pathlib import Path
+
+__project_name__ = __name__.split(".")[0]
+__project_path__ = str(Path(__file__).parent.parent.parent)
+__version__ = metadata.version(__project_name__)
+__is_development_mode__ = "uvx" not in sys.argv[0].lower()
+__is_running_in_container__ = os.getenv(f"{__project_name__.upper()}_RUNNING_IN_CONTAINER")
+__env__ = os.getenv("ENV", os.getenv("VERCEL_ENV", "local"))
+__env_file__ = [
+    Path.home() / f".{__project_name__}" / ".env",
+    Path.home() / f".{__project_name__}" / f".env.{__env__}",
+    Path(".env"),
+    Path(f".env.{__env__}"),
+]
+env_file_path = os.getenv(f"{__project_name__.upper()}_ENV_FILE")
+if env_file_path:
+    __env_file__.insert(2, Path(env_file_path))
+
+
+def get_project_url_by_label(prefix: str) -> str:
+    """Get labeled Project-URL.
+
+    See https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-project-url
+
+    Args:
+        prefix(str): The prefix to match at the beginning of URL entries.
+
+    Returns:
+        The extracted URL string if found, or an empty string if not found.
+    """
+    for url_entry in metadata.metadata(__project_name__).get_all("Project-URL", []):
+        if url_entry.startswith(prefix):
+            return str(url_entry.split(", ", 1)[1])
+
+    return ""
+
+
+_authors = metadata.metadata(__project_name__).get_all("Author-email", [])
+_author = _authors[0] if _authors else None
+__author_name__ = _author.split("<")[0].strip() if _author else None
+__author_email__ = _author.split("<")[1].strip(" >") if _author else None
+__repository_url__ = get_project_url_by_label("Source")
+__documentation__url__ = get_project_url_by_label("Documentation")

oe_python_template_example/utils/_di.py

@@ -0,0 +1,70 @@
+"""Module for dynamic import and discovery of implementations and subclasses."""
+
+import importlib
+import pkgutil
+from inspect import isclass
+from typing import Any
+
+from ._constants import __project_name__
+
+_implementation_cache: dict[Any, list[Any]] = {}
+_subclass_cache: dict[Any, list[Any]] = {}
+
+
+def locate_implementations(_class: type[Any]) -> list[Any]:
+    """
+    Dynamically discover all instances of some class.
+
+    Args:
+        _class (type[Any]): Class to search for.
+
+    Returns:
+        list[Any]: List of discovered implementations of the given class.
+    """
+    if _class in _implementation_cache:
+        return _implementation_cache[_class]
+
+    implementations = []
+    package = importlib.import_module(__project_name__)
+
+    for _, name, _ in pkgutil.iter_modules(package.__path__):
+        module = importlib.import_module(f"{__project_name__}.{name}")
+        # Check all members of the module
+        for member_name in dir(module):
+            member = getattr(module, member_name)
+            if isinstance(member, _class):
+                implementations.append(member)
+
+    _implementation_cache[_class] = implementations
+    return implementations
+
+
+def locate_subclasses(_class: type[Any]) -> list[Any]:
+    """
+    Dynamically discover all classes that are subclasses of some type.
+
+    Args:
+        _class (type[Any]): Parent class of subclasses to search for.
+
+    Returns:
+        list[type[Any]]: List of discovered subclasses of the given class.
+    """
+    if _class in _subclass_cache:
+        return _subclass_cache[_class]
+
+    subclasses = []
+    package = importlib.import_module(__project_name__)
+
+    for _, name, _ in pkgutil.iter_modules(package.__path__):
+        try:
+            module = importlib.import_module(f"{__project_name__}.{name}")
+            # Check all members of the module
+            for member_name in dir(module):
+                member = getattr(module, member_name)
+                if isclass(member) and issubclass(member, _class) and member != _class:
+                    subclasses.append(member)
+        except ImportError:
+            continue
+
+    _subclass_cache[_class] = subclasses
+    return subclasses

oe_python_template_example/utils/_health.py

@@ -0,0 +1,107 @@
+"""Health models and status definitions for service health checks."""
+
+from enum import StrEnum
+from typing import ClassVar, Self
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class _HealthStatus(StrEnum):
+    UP = "UP"
+    DOWN = "DOWN"
+
+
+class Health(BaseModel):
+    """Represents the health status of a service with optional components and failure reasons.
+
+    - A health object can have child components, i.e. health forms a tree.
+    - Any node in the tree can set itself to DOWN. In this case the node is required
+        to set the reason attribute. If reason is not set when DOWN,
+        automatic model validation of the tree will fail.
+    - DOWN'ness is propagated to parent health objects. I.e. the health of a parent
+        node is automatically set to DOWN if any of its child components are DOWN. The
+        child components leading to this will be listed in the reason.
+    - The root of the health tree is computed in the system module. The health of other
+        modules is automatically picked up by the system module.
+    """
+
+    Code: ClassVar[type[_HealthStatus]] = _HealthStatus
+    status: _HealthStatus
+    reason: str | None = None
+    components: dict[str, "Health"] = Field(default_factory=dict)
+
+    def compute_health_from_components(self) -> Self:
+        """Recursively compute health status from components.
+
+        - If health is already DOWN, it remains DOWN with its original reason.
+        - If health is UP but any component is DOWN, health becomes DOWN with
+            a reason listing all failed components.
+
+        Returns:
+            Self: The updated health instance with computed status.
+        """
+        # Skip recomputation if already known to be DOWN
+        if self.status == _HealthStatus.DOWN:
+            return self
+
+        # No components means we keep the existing status
+        if not self.components:
+            return self
+
+        # Find all DOWN components
+        down_components = []
+        for component_name, component in self.components.items():
+            # Recursively compute health for each component
+            component.compute_health_from_components()
+            if component.status == _HealthStatus.DOWN:
+                down_components.append(component_name)
+
+        # If any components are DOWN, mark the parent as DOWN
+        if down_components:
+            self.status = _HealthStatus.DOWN
+            if len(down_components) == 1:
+                self.reason = f"Component '{down_components[0]}' is DOWN"
+            else:
+                component_list = "', '".join(down_components)
+                self.reason = f"Components '{component_list}' are DOWN"
+
+        return self
+
+    @model_validator(mode="after")
+    def validate_health_state(self) -> Self:
+        """Validate the health state and ensure consistency.
+
+        - Compute overall health based on component health
+        - Ensure UP status has no associated reason
+        - Ensure DOWN status always has a reason
+
+        Returns:
+            Self: The validated model instance with correct health status.
+
+        Raises:
+            ValueError: If validation fails due to inconsistency.
+        """
+        # First compute health from components
+        self.compute_health_from_components()
+
+        # Validate that UP status has no reason
+        if (self.status == _HealthStatus.UP) and self.reason:
+            msg = f"Health {self.status} must not have reason"
+            raise ValueError(msg)
+
+        # Validate that DOWN status always has a reason
+        if (self.status == _HealthStatus.DOWN) and not self.reason:
+            msg = "Health DOWN must have a reason"
+            raise ValueError(msg)
+
+        return self
+
+    def __str__(self) -> str:
+        """Return string representation of health status with optional reason for DOWN state.
+
+        Returns:
+            str: The health status value, with reason appended if status is DOWN.
+        """
+        if self.status == _HealthStatus.DOWN and self.reason:
+            return f"{self.status.value}: {self.reason}"
+        return self.status.value

oe_python_template_example/utils/_log.py

@@ -0,0 +1,122 @@
+"""Logging configuration and utilities."""
+
+import logging as python_logging
+import typing as t
+from logging import FileHandler
+from typing import Annotated, Literal
+
+import click
+import logfire
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from rich.console import Console
+from rich.logging import RichHandler
+
+from ._constants import __env_file__, __project_name__
+from ._settings import load_settings
+
+
+def get_logger(name: str | None) -> python_logging.Logger:
+    """
+    Get a logger instance with the given name or project name as default.
+
+    Args:
+        name(str): The name for the logger. If None, uses project name.
+
+    Returns:
+        Logger: Configured logger instance.
+    """
+    if (name is None) or (name == __project_name__):
+        return python_logging.getLogger(__project_name__)
+    return python_logging.getLogger(f"{__project_name__}.{name}")
+
+
+class LogSettings(BaseSettings):
+    """Settings for configuring logging behavior."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=f"{__project_name__.upper()}_LOG_",
+        extra="ignore",
+        env_file=__env_file__,
+        env_file_encoding="utf-8",
+    )
+
+    level: Annotated[
+        Literal["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"],
+        Field(description="Logging level", default="INFO"),
+    ]
+    file_enabled: Annotated[
+        bool,
+        Field(description="Enable logging to file", default=False),
+    ]
+    file_name: Annotated[
+        str,
+        Field(description="Name of the log file", default=f"{__project_name__}.log"),
+    ]
+    console_enabled: Annotated[
+        bool,
+        Field(description="Enable logging to console", default=False),
+    ]
+
+
+class CustomFilter(python_logging.Filter):
+    """Custom filter for log records."""
+
+    @staticmethod
+    def filter(_record: python_logging.LogRecord) -> bool:
+        """
+        Filter log records based on custom criteria.
+
+        Args:
+            record: The log record to filter.
+
+        Returns:
+            bool: True if record should be logged, False otherwise.
+        """
+        return True
+
+
+def logging_initialize(log_to_logfire: bool = False) -> None:
+    """Initialize logging configuration."""
+    log_filter = CustomFilter()
+
+    handlers = []
+
+    settings = load_settings(LogSettings)
+
+    if settings.file_enabled:
+        file_handler = python_logging.FileHandler(settings.file_name)
+        file_formatter = python_logging.Formatter(
+            fmt="%(asctime)s %(process)d %(levelname)s %(name)s %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        file_handler.setFormatter(file_formatter)
+        file_handler.addFilter(log_filter)
+        handlers.append(file_handler)
+
+    if settings.console_enabled:
+        rich_handler = RichHandler(
+            console=Console(stderr=True),
+            markup=True,
+            rich_tracebacks=True,
+            tracebacks_suppress=[click],
+            show_time=True,
+            omit_repeated_times=True,
+            show_path=True,
+            show_level=True,
+            enable_link_path=True,
+        )
+        rich_handler.addFilter(log_filter)
+        handlers.append(t.cast("FileHandler", rich_handler))
+
+    if log_to_logfire:
+        logfire_handler = logfire.LogfireLoggingHandler()
+        logfire_handler.addFilter(log_filter)
+        handlers.append(t.cast("FileHandler", logfire_handler))
+
+    python_logging.basicConfig(
+        level=settings.level,
+        format="%(name)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=handlers,
+    )

oe_python_template_example/utils/_logfire.py

@@ -0,0 +1,68 @@
+"""Logfire integration for logging and instrumentation."""
+
+from typing import Annotated
+
+import logfire
+from pydantic import Field, PlainSerializer, SecretStr
+from pydantic_settings import SettingsConfigDict
+
+from ._constants import __env__, __env_file__, __project_name__, __repository_url__, __version__
+from ._settings import OpaqueSettings, load_settings
+
+
+class LogfireSettings(OpaqueSettings):
+    """Configuration settings for Logfire integration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=f"{__project_name__.upper()}_LOGFIRE_",
+        env_file=__env_file__,
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    token: Annotated[
+        SecretStr | None,
+        PlainSerializer(func=OpaqueSettings.serialize_sensitive_info, return_type=str, when_used="always"),
+        Field(description="Logfire token. Leave empty to disable logfire.", examples=["YOUR_TOKEN"], default=None),
+    ]
+    instrument_system_metrics: Annotated[
+        bool,
+        Field(description="Enable system metrics instrumentation", default=False),
+    ]
+
+
+def logfire_initialize(modules: list["str"]) -> bool:
+    """Initialize Logfire integration.
+
+    Args:
+        modules(list["str"]): List of modules to be instrumented.
+
+    Returns:
+        bool: True if initialized successfully False otherwise
+    """
+    settings = load_settings(LogfireSettings)
+
+    if settings.token is None:
+        return False
+
+    logfire.configure(
+        send_to_logfire="if-token-present",
+        token=settings.token.get_secret_value(),
+        environment=__env__,
+        service_name=__project_name__,
+        console=False,
+        code_source=logfire.CodeSource(
+            repository=__repository_url__,
+            revision=__version__,
+            root_path="",
+        ),
+    )
+
+    if settings.instrument_system_metrics:
+        logfire.instrument_system_metrics(base="full")
+
+    logfire.instrument_pydantic()
+
+    logfire.install_auto_tracing(modules=modules, min_duration=0.0)
+
+    return True

oe_python_template_example/utils/_process.py

@@ -0,0 +1,41 @@
+"""Process related utilities."""
+
+from pathlib import Path
+
+import psutil
+from pydantic import BaseModel
+
+
+class ParentProcessInfo(BaseModel):
+    """Information about a parent process."""
+
+    name: str | None = None
+    pid: int | None = None
+
+
+class ProcessInfo(BaseModel):
+    """Information about the current process."""
+
+    project_root: str
+    pid: int
+    parent: ParentProcessInfo
+
+
+def get_process_info() -> ProcessInfo:
+    """
+    Get information about the current process and its parent.
+
+    Returns:
+        ProcessInfo: Object containing process information.
+    """
+    current_process = psutil.Process()
+    parent = current_process.parent()
+
+    return ProcessInfo(
+        project_root=str(Path(__file__).parent.parent.parent.parent),
+        pid=current_process.pid,
+        parent=ParentProcessInfo(
+            name=parent.name() if parent else None,
+            pid=parent.pid if parent else None,
+        ),
+    )