kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/utils/formatting.py

@@ -0,0 +1,338 @@
+"""Human-friendly formatting utilities powered by humanize and pendulum."""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+import humanize
+import pendulum
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+log = logging.getLogger(__name__)
+
+# Hard limits for datetime formatting (defined here to avoid circular import)
+# These values match the ones in limits.py for consistency
+_HARD_MAX_DATETIME_FORMAT_LENGTH = 64
+_HARD_MAX_TIMEZONE_LENGTH = 64
+_HARD_MIN_EPOCH_TIMESTAMP = 0  # Unix epoch start
+_HARD_MAX_EPOCH_TIMESTAMP = 4102444800  # Year 2100
+
+__all__ = [
+    "format_bytes",
+    "format_count",
+    "format_duration",
+    "format_time_delta",
+    "format_timestamp",
+    "parse_size_string",
+]
+
+#: Default datetime format (ISO-like).
+DEFAULT_DATETIME_FORMAT = "YYYY-MM-DD HH:mm:ss"
+
+#: Allowed characters in datetime format strings (deep defense).
+_DATETIME_FORMAT_PATTERN = re.compile(r"^[a-zA-Z0-9\s\-/:.,\[\]()]+$")
+
+
+def _get_datetime_config() -> tuple[str, str]:
+    """Get datetime format and timezone from config (lazy load).
+
+    Returns:
+        Tuple of (format_string, timezone_string).
+    """
+    try:
+        from kstlib.config import get_config
+        from kstlib.config.exceptions import ConfigNotLoadedError
+    except ImportError:
+        return DEFAULT_DATETIME_FORMAT, "local"
+
+    try:
+        config = get_config()
+        dt_config = config.get("datetime", {})  # type: ignore[no-untyped-call]
+        fmt = dt_config.get("format", DEFAULT_DATETIME_FORMAT)
+        tz = dt_config.get("timezone", "local")
+        return str(fmt), str(tz)
+    except ConfigNotLoadedError:
+        return DEFAULT_DATETIME_FORMAT, "local"
+
+
+def _validate_format_string(fmt: str) -> str:
+    """Validate and sanitize datetime format string (deep defense).
+
+    Args:
+        fmt: Format string to validate.
+
+    Returns:
+        Validated format string, or default if invalid.
+    """
+    if not fmt or not isinstance(fmt, str):
+        return DEFAULT_DATETIME_FORMAT
+
+    if len(fmt) > _HARD_MAX_DATETIME_FORMAT_LENGTH:
+        log.warning(
+            "Datetime format too long (%d > %d), using default",
+            len(fmt),
+            _HARD_MAX_DATETIME_FORMAT_LENGTH,
+        )
+        return DEFAULT_DATETIME_FORMAT
+
+    if not _DATETIME_FORMAT_PATTERN.match(fmt):
+        log.warning("Datetime format contains invalid characters, using default")
+        return DEFAULT_DATETIME_FORMAT
+
+    return fmt
+
+
+def _validate_timezone(tz: str) -> str:
+    """Validate timezone string (deep defense).
+
+    Args:
+        tz: Timezone string to validate.
+
+    Returns:
+        Validated timezone string, or "local" if invalid.
+    """
+    if not tz or not isinstance(tz, str):
+        return "local"
+
+    if len(tz) > _HARD_MAX_TIMEZONE_LENGTH:
+        log.warning(
+            "Timezone string too long (%d > %d), using local",
+            len(tz),
+            _HARD_MAX_TIMEZONE_LENGTH,
+        )
+        return "local"
+
+    if tz.lower() == "local":
+        return "local"
+
+    # Validate against pendulum's known timezones
+    try:
+        pendulum.timezone(tz)
+        return tz
+    except Exception:
+        log.warning("Unknown timezone '%s', using local", tz)
+        return "local"
+
+
+def format_timestamp(
+    epoch: float | str | None,
+    fmt: str | None = None,
+    tz: str | None = None,
+) -> str:
+    """Format an epoch timestamp as a human-readable datetime string.
+
+    Converts Unix epoch timestamps to formatted datetime strings using
+    pendulum for timezone-aware formatting. Configuration can be loaded
+    from kstlib.conf.yml or provided explicitly.
+
+    Args:
+        epoch: Unix timestamp (seconds since 1970-01-01 UTC).
+            Accepts int, float, or string representation.
+            Returns "(invalid)" if None or unparseable.
+        fmt: Datetime format string (pendulum tokens).
+            If None, uses config value or "YYYY-MM-DD HH:mm:ss".
+        tz: Timezone for display ("local", "UTC", or IANA name).
+            If None, uses config value or "local".
+
+    Returns:
+        Formatted datetime string, or "(invalid)" on error.
+
+    Examples:
+        >>> format_timestamp(1706234567, tz="UTC")
+        '2024-01-26 02:02:47'
+        >>> format_timestamp(1706234567, fmt="DD/MM/YYYY", tz="UTC")
+        '26/01/2024'
+        >>> format_timestamp(None)
+        '(invalid)'
+    """
+    # Handle None or empty
+    if epoch is None or epoch == "":
+        return "(invalid)"
+
+    # Convert string to numeric
+    if isinstance(epoch, str):
+        try:
+            epoch = float(epoch)
+        except ValueError:
+            log.warning("Cannot parse epoch string: %r", epoch)
+            return "(invalid)"
+
+    # Validate epoch bounds (deep defense)
+    if epoch < _HARD_MIN_EPOCH_TIMESTAMP or epoch > _HARD_MAX_EPOCH_TIMESTAMP:
+        log.warning(
+            "Epoch timestamp out of bounds: %s (valid: %d-%d)",
+            epoch,
+            _HARD_MIN_EPOCH_TIMESTAMP,
+            _HARD_MAX_EPOCH_TIMESTAMP,
+        )
+        return "(invalid)"
+
+    # Get config values if not provided
+    config_fmt, config_tz = _get_datetime_config()
+    fmt = _validate_format_string(fmt or config_fmt)
+    tz = _validate_timezone(tz or config_tz)
+
+    try:
+        # Create pendulum datetime from epoch
+        dt = pendulum.from_timestamp(epoch)
+
+        # Convert to target timezone
+        # pendulum.local_timezone is a module, not a function - use tz.local_timezone()
+        from pendulum.tz import local_timezone
+
+        local_tz = local_timezone()
+        dt = dt.in_timezone(tz) if tz != "local" else dt.in_timezone(local_tz)
+
+        return dt.format(fmt)
+    except Exception as e:
+        log.warning("Error formatting timestamp %s: %s", epoch, e)
+        return "(invalid)"
+
+
+def format_bytes(size: float, binary: bool = True) -> str:
+    """Format a byte count as a human-readable string.
+
+    Args:
+        size: Size in bytes (int or float).
+        binary: If True, use binary units (KiB, MiB). If False, use SI units (KB, MB).
+
+    Returns:
+        Human-readable size string (e.g., "25.0 MiB" or "25.0 MB").
+
+    Examples:
+        >>> format_bytes(25 * 1024 * 1024)
+        '25.0 MiB'
+        >>> format_bytes(25 * 1000 * 1000, binary=False)
+        '25.0 MB'
+    """
+    return humanize.naturalsize(size, binary=binary)
+
+
+def format_count(value: int) -> str:
+    """Format a count with comma separators for readability.
+
+    Args:
+        value: Integer count to format.
+
+    Returns:
+        Comma-separated string (e.g., "1,000,000").
+
+    Examples:
+        >>> format_count(1000000)
+        '1,000,000'
+    """
+    return humanize.intcomma(value)
+
+
+def format_duration(seconds: float) -> str:
+    """Format a duration in seconds as a human-readable string.
+
+    Args:
+        seconds: Duration in seconds.
+
+    Returns:
+        Human-readable duration (e.g., "5 minutes", "2 hours").
+
+    Examples:
+        >>> format_duration(300)
+        '5 minutes'
+        >>> format_duration(3661)
+        'an hour'
+    """
+    delta = timedelta(seconds=seconds)
+    return humanize.naturaldelta(delta)
+
+
+def format_time_delta(dt: datetime, other: datetime | None = None) -> str:
+    """Format a datetime as a relative time string.
+
+    Args:
+        dt: Target datetime.
+        other: Reference datetime (defaults to now).
+
+    Returns:
+        Relative time string (e.g., "2 hours ago", "in 3 days").
+
+    Examples:
+        >>> from datetime import datetime, timedelta
+        >>> past = datetime.now() - timedelta(hours=2)
+        >>> format_time_delta(past)
+        '2 hours ago'
+    """
+    return humanize.naturaltime(dt, when=other)
+
+
+#: Size unit multipliers for parsing human-readable size strings.
+_SIZE_UNITS: dict[str, int] = {
+    "b": 1,
+    "k": 1024,
+    "kb": 1024,
+    "kib": 1024,
+    "m": 1024**2,
+    "mb": 1024**2,
+    "mib": 1024**2,
+    "g": 1024**3,
+    "gb": 1024**3,
+    "gib": 1024**3,
+    "t": 1024**4,
+    "tb": 1024**4,
+    "tib": 1024**4,
+}
+
+#: Regex pattern for parsing size strings like "25M", "100 MiB", "1.5GB".
+_SIZE_PATTERN = __import__("re").compile(r"^\s*([\d.]+)\s*([a-zA-Z]*)\s*$")
+
+
+def parse_size_string(value: str | float) -> int:
+    """Parse a human-readable size string into bytes.
+
+    Accepts raw integers, floats, or strings with optional units.
+    Supported units: B, K, KB, KiB, M, MB, MiB, G, GB, GiB, T, TB, TiB.
+
+    Args:
+        value: Size as int, float, or string with optional unit suffix.
+
+    Returns:
+        Size in bytes as an integer.
+
+    Raises:
+        ValueError: If the string format is invalid or the unit is unknown.
+
+    Examples:
+        >>> parse_size_string(1024)
+        1024
+        >>> parse_size_string("25M")
+        26214400
+        >>> parse_size_string("100 MiB")
+        104857600
+        >>> parse_size_string("1.5GB")
+        1610612736
+    """
+    # Handle numeric types directly
+    if isinstance(value, int | float):
+        return int(value)
+
+    # Parse string format
+    match = _SIZE_PATTERN.match(value)
+    if not match:
+        raise ValueError(f"Invalid size format: {value!r}")
+
+    numeric_str, unit_str = match.groups()
+    try:
+        numeric_value = float(numeric_str)
+    except ValueError as exc:
+        raise ValueError(f"Invalid numeric value: {numeric_str!r}") from exc
+
+    if not unit_str:
+        return int(numeric_value)
+
+    multiplier = _SIZE_UNITS.get(unit_str.lower())
+    if multiplier is None:
+        raise ValueError(f"Unknown size unit: {unit_str!r}")
+
+    return int(numeric_value * multiplier)

kstlib/utils/http_trace.py

@@ -0,0 +1,237 @@
+"""HTTP trace logging utilities with sensitive data redaction."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs
+
+if TYPE_CHECKING:
+    import logging
+
+    import httpx
+
+# Default sensitive keys to redact in request bodies
+DEFAULT_SENSITIVE_KEYS: frozenset[str] = frozenset(
+    {
+        "client_secret",
+        "code",
+        "refresh_token",
+        "access_token",
+        "code_verifier",
+        "password",
+        "api_key",
+        "secret",
+        "token",
+    }
+)
+
+
+class HTTPTraceLogger:
+    """Reusable HTTP trace logger with sensitive data redaction.
+
+    This class provides httpx event hooks for logging HTTP requests and responses
+    at TRACE level with automatic redaction of sensitive data.
+
+    Args:
+        logger: Logger instance to use for trace output.
+        trace_level: Logging level for trace messages (default: 5 for TRACE).
+        sensitive_keys: Set of keys to redact in request bodies.
+        pretty_print: Whether to pretty-print JSON responses.
+        max_body_length: Maximum response body length before truncation.
+
+    Examples:
+        >>> import logging
+        >>> import httpx
+        >>> from kstlib.utils.http_trace import HTTPTraceLogger
+        >>> tracer = HTTPTraceLogger(logging.getLogger(__name__))
+        >>> client = httpx.Client(
+        ...     event_hooks={
+        ...         "request": [tracer.on_request],
+        ...         "response": [tracer.on_response],
+        ...     }
+        ... )
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        *,
+        trace_level: int = 5,
+        sensitive_keys: frozenset[str] | None = None,
+        pretty_print: bool = True,
+        max_body_length: int = 2000,
+    ) -> None:
+        """Initialize the HTTP trace logger."""
+        self._logger = logger
+        self._trace_level = trace_level
+        self._sensitive_keys = sensitive_keys or DEFAULT_SENSITIVE_KEYS
+        self._pretty_print = pretty_print
+        self._max_body_length = max_body_length
+
+    @property
+    def sensitive_keys(self) -> frozenset[str]:
+        """Return the set of sensitive keys being redacted."""
+        return self._sensitive_keys
+
+    def configure(
+        self,
+        *,
+        pretty_print: bool | None = None,
+        max_body_length: int | None = None,
+    ) -> None:
+        """Update trace configuration at runtime.
+
+        Args:
+            pretty_print: Whether to pretty-print JSON responses.
+            max_body_length: Maximum response body length before truncation.
+        """
+        if pretty_print is not None:
+            self._pretty_print = pretty_print
+        if max_body_length is not None:
+            self._max_body_length = max_body_length
+
+    def on_request(self, request: httpx.Request) -> None:
+        """httpx event hook for outgoing requests (TRACE logging).
+
+        Redacts sensitive data in request body and Authorization headers.
+
+        Args:
+            request: The outgoing HTTP request.
+        """
+        if not self._logger.isEnabledFor(self._trace_level):
+            return
+
+        body_str = self._redact_request_body(request.content)
+        safe_headers = {k: v for k, v in request.headers.items() if k.lower() != "authorization"}
+
+        self._logger.log(
+            self._trace_level,
+            "[HTTP] %s %s | headers=%s | body=%s",
+            request.method,
+            request.url,
+            dict(safe_headers) or "{}",
+            body_str,
+        )
+
+    def on_response(self, response: httpx.Response) -> None:
+        """httpx event hook for incoming responses (TRACE logging).
+
+        Optionally pretty-prints JSON and truncates long bodies.
+
+        Args:
+            response: The incoming HTTP response.
+        """
+        if not self._logger.isEnabledFor(self._trace_level):
+            return
+
+        body = self._format_response_body(response)
+
+        self._logger.log(
+            self._trace_level,
+            "[HTTP] %s %s | status=%d | body=\n%s",
+            response.request.method,
+            response.request.url,
+            response.status_code,
+            body,
+        )
+
+    def _redact_request_body(self, content: bytes | None) -> str:
+        """Redact sensitive values from request body.
+
+        Args:
+            content: Raw request body bytes.
+
+        Returns:
+            String representation with sensitive values redacted.
+        """
+        if not content:
+            return "{}"
+
+        try:
+            body_data = parse_qs(content.decode("utf-8"))
+            safe_data: dict[str, Any] = {}
+
+            for key, values in body_data.items():
+                val = values[0] if len(values) == 1 else values
+                if key in self._sensitive_keys:
+                    safe_data[key] = f"[REDACTED:{len(str(val))}chars]"
+                else:
+                    safe_data[key] = val
+
+            return str(safe_data) if safe_data else "{}"
+        except Exception:  # pylint: disable=broad-exception-caught
+            return "[binary or unparseable]"
+
+    def _format_response_body(self, response: httpx.Response) -> str:
+        """Format response body for logging.
+
+        Args:
+            response: The HTTP response.
+
+        Returns:
+            Formatted body string, possibly pretty-printed and truncated.
+        """
+        try:
+            response.read()  # Ensure body is available
+            body = response.text
+
+            if self._pretty_print and body:
+                try:
+                    parsed = json.loads(body)
+                    body = json.dumps(parsed, indent=2, ensure_ascii=False)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+
+            if len(body) > self._max_body_length:
+                body = f"{body[: self._max_body_length]}\n... [truncated, {len(body)} total chars]"
+
+            return body
+        except Exception:  # pylint: disable=broad-exception-caught
+            return "[unable to read body]"
+
+
+# Type alias for httpx event hooks - uses internal types for accurate typing
+EventHooksDict = dict[str, list["httpx._types.RequestHook | httpx._types.ResponseHook"]]  # type: ignore[name-defined]  # noqa: SLF001
+
+
+def create_trace_event_hooks(
+    logger: logging.Logger,
+    trace_level: int = 5,
+) -> tuple[EventHooksDict, bool]:
+    """Create httpx event hooks for TRACE logging.
+
+    This helper centralizes the common pattern of setting up HTTP trace logging
+    with HTTPTraceLogger for httpx clients.
+
+    Args:
+        logger: Logger instance to use for trace output.
+        trace_level: Logging level for trace messages (default: 5 for TRACE).
+
+    Returns:
+        Tuple of (event_hooks dict, trace_enabled bool).
+        The event_hooks dict can be passed directly to httpx.AsyncClient().
+
+    Examples:
+        >>> import logging
+        >>> import httpx
+        >>> from kstlib.utils.http_trace import create_trace_event_hooks
+        >>> log = logging.getLogger(__name__)
+        >>> hooks, enabled = create_trace_event_hooks(log)
+        >>> async with httpx.AsyncClient(event_hooks=hooks) as client:  # doctest: +SKIP
+        ...     response = await client.get("https://example.com")  # doctest: +SKIP
+    """
+    trace_enabled = logger.isEnabledFor(trace_level)
+    event_hooks: EventHooksDict = {}
+
+    if trace_enabled:
+        tracer = HTTPTraceLogger(logger, trace_level=trace_level)
+        event_hooks = {
+            "request": [tracer.on_request],
+            "response": [tracer.on_response],
+        }
+
+    return event_hooks, trace_enabled
+
+
+__all__ = ["DEFAULT_SENSITIVE_KEYS", "HTTPTraceLogger", "create_trace_event_hooks"]

kstlib/utils/lazy.py

@@ -0,0 +1,49 @@
+"""Lazy loading utilities for deferred module imports."""
+
+from __future__ import annotations
+
+import importlib
+from functools import wraps
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+
+def lazy_factory(module_path: str, class_name: str) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator for lazy loading of classes in factory functions.
+
+    Defers the import of the specified class until the factory is actually called,
+    reducing startup time when the factory is registered but not used.
+
+    Args:
+        module_path: Full dotted path to the module containing the class.
+        class_name: Name of the class to import from the module.
+
+    Returns:
+        A decorator that wraps the factory function with lazy import behavior.
+
+    Example:
+        >>> @lazy_factory("kstlib.secrets.providers.sops", "SOPSProvider")
+        ... def _sops_factory(**kwargs):
+        ...     ...  # Body is ignored, class is instantiated automatically
+        >>>
+        >>> # SOPSProvider is only imported when _sops_factory() is called
+        >>> provider = _sops_factory(path="secrets.sops.yml")
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(**kwargs: Any) -> T:
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+            return cast("T", cls(**kwargs))
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = ["lazy_factory"]