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

oe_python_template/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/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", "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/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/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/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/utils/_logfire.py

@@ -0,0 +1,67 @@
+"""Logfire integration for logging and instrumentation."""
+
+from typing import Annotated
+
+import logfire
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from ._constants import __env__, __env_file__, __project_name__, __repository_url__, __version__
+from ._settings import load_settings
+
+
+class LogfireSettings(BaseSettings):
+    """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,
+        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/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,
+        ),
+    )

oe_python_template/utils/_sentry.py

@@ -0,0 +1,96 @@
+"""Sentry integration for application monitoring."""
+
+from typing import Annotated
+
+import sentry_sdk
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sentry_sdk.integrations.typer import TyperIntegration
+
+from ._constants import __env__, __env_file__, __project_name__, __version__
+from ._settings import load_settings
+
+
+class SentrySettings(BaseSettings):
+    """Configuration settings for Sentry integration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=f"{__project_name__.upper()}_SENTRY_",
+        env_file=__env_file__,
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    dsn: Annotated[
+        SecretStr | None,
+        Field(description="Sentry DSN", examples=["https://SECRET@SECRET.ingest.de.sentry.io/SECRET"], default=None),
+    ]
+
+    debug: Annotated[
+        bool,
+        Field(description="Debug (https://docs.sentry.io/platforms/python/configuration/options/)", default=False),
+    ]
+
+    send_default_pii: Annotated[
+        bool,
+        Field(
+            description="Send default personal identifiable information (https://docs.sentry.io/platforms/python/configuration/options/)",
+            default=False,
+        ),
+    ]
+
+    max_breadcrumbs: Annotated[
+        int,
+        Field(
+            description="Max breadcrumbs (https://docs.sentry.io/platforms/python/configuration/options/#max_breadcrumbs)",
+            default=5.0,
+        ),
+    ]
+    sample_rate: Annotated[
+        float,
+        Field(
+            description="Sample Rate (https://docs.sentry.io/platforms/python/configuration/sampling/#sampling-error-events)",
+            default=1.0,
+        ),
+    ]
+    traces_sample_rate: Annotated[
+        float,
+        Field(
+            description="Traces Sample Rate (https://docs.sentry.io/platforms/python/configuration/sampling/#configuring-the-transaction-sample-rate)",
+            default=1.0,
+        ),
+    ]
+    profiles_sample_rate: Annotated[
+        float,
+        Field(
+            description="Traces Sample Rate (https://docs.sentry.io/platforms/python/tracing/#configure)",
+            default=1.0,
+        ),
+    ]
+
+
+def sentry_initialize() -> bool:
+    """Initialize Sentry integration.
+
+    Returns:
+        bool: True if initialized successfully, False otherwise
+    """
+    settings = load_settings(SentrySettings)
+
+    if settings.dsn is None:
+        return False
+
+    sentry_sdk.init(
+        release=f"{__project_name__}@{__version__}",  # https://docs.sentry.io/platforms/python/configuration/releases/,
+        environment=__env__,
+        dsn=settings.dsn.get_secret_value(),
+        max_breadcrumbs=settings.max_breadcrumbs,
+        debug=settings.debug,
+        send_default_pii=settings.send_default_pii,
+        sample_rate=settings.sample_rate,
+        traces_sample_rate=settings.traces_sample_rate,
+        profiles_sample_rate=settings.profiles_sample_rate,
+        integrations=[TyperIntegration()],
+    )
+
+    return True

oe_python_template/utils/_service.py

@@ -0,0 +1,39 @@
+"""Base class for services."""
+
+from abc import ABC, abstractmethod
+from typing import Any, TypeVar
+
+from pydantic_settings import BaseSettings
+
+from ._health import Health
+from ._settings import load_settings
+
+T = TypeVar("T", bound=BaseSettings)
+
+
+class BaseService(ABC):
+    """Base class for services."""
+
+    _settings: BaseSettings
+
+    def __init__(self, settings_class: type[T] | None = None) -> None:
+        """
+        Initialize service with optional settings.
+
+        Args:
+            settings_class: Optional settings class to load configuration.
+        """
+        if settings_class is not None:
+            self._settings = load_settings(settings_class)
+
+    def key(self) -> str:
+        """Return the module name of the instance."""
+        return self.__module__.split(".")[-2]
+
+    @abstractmethod
+    def health(self) -> Health:
+        """Get health of this service. Override in subclass."""
+
+    @abstractmethod
+    def info(self) -> dict[str, Any]:
+        """Get info of this service. Override in subclass."""

oe_python_template/utils/_settings.py

@@ -0,0 +1,68 @@
+"""Utilities around Pydantic settings."""
+
+import json
+import logging
+import sys
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+from rich.panel import Panel
+from rich.text import Text
+
+from ._console import console
+
+T = TypeVar("T", bound=BaseSettings)
+
+logger = logging.getLogger(__name__)
+
+
+def load_settings(settings_class: type[T]) -> T:
+    """
+    Load settings with error handling and nice formatting.
+
+    Args:
+        settings_class: The Pydantic settings class to instantiate
+
+    Returns:
+        (T): Instance of the settings class
+
+    Raises:
+        SystemExit: If settings validation fails
+    """
+    try:
+        return settings_class()
+    except ValidationError as e:
+        errors = json.loads(e.json())
+        text = Text()
+        text.append(
+            "Validation error(s): \n\n",
+            style="debug",
+        )
+
+        prefix = settings_class.model_config.get("env_prefix", "")
+        for error in errors:
+            env_var = f"{prefix}{error['loc'][0]}".upper()
+            logger.fatal(f"Configuration invalid! {env_var}: {error['msg']}")
+            text.append(f"• {env_var}", style="yellow bold")
+            text.append(f": {error['msg']}\n")
+
+        text.append(
+            "\nCheck settings defined in the process environment and in file ",
+            style="info",
+        )
+        env_file = str(settings_class.model_config.get("env_file", ".env") or ".env")
+        text.append(
+            str(Path(__file__).parent.parent.parent.parent / env_file),
+            style="bold blue underline",
+        )
+
+        console.print(
+            Panel(
+                text,
+                title="Configuration invalid!",
+                border_style="error",
+            ),
+        )
+        sys.exit(78)