utilityhub-logging 0.1.0__tar.gz

utilityhub_logging-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: utilityhub-logging
+Version: 0.1.0
+Summary: Project-agnostic logging orchestration utilities built on Python's stdlib logging package
+Author: Rajesh Das
+Author-email: Rajesh Das <rajesh@hyperoot.dev>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# utilityhub-logging
+
+`utilityhub-logging` is a small, project-agnostic package that extends Python's
+standard library `logging` module with deterministic setup and cleanup helpers.
+
+It focuses on the repetitive parts teams tend to rebuild:
+
+- resolving a safe logs directory
+- configuring one log file per application run
+- opening a scoped log for an operation
+- switching between plain text and JSON output
+- attaching async-safe contextual metadata
+- preventing duplicate handlers and cleaning them up reliably
+
+## Install
+
+```bash
+uv add utilityhub-logging
+```
+
+## Quick Start
+
+```python
+import logging
+
+from utilityhub_logging import (
+    LogFormat,
+    begin_scope_logging,
+    bind_context,
+    cleanup_logging,
+    configure_app_logging,
+)
+
+log_file = configure_app_logging(
+    app_name="demo-app",
+    level="INFO",
+    console=True,
+    log_format=LogFormat.PLAIN,
+)
+
+logger = logging.getLogger("demo")
+with bind_context(environment="dev", subsystem="worker"):
+    logger.info("Application started")
+
+scope_logger, scope_file = begin_scope_logging(
+    app_name="demo-app",
+    scope_type="job",
+    scope_id="job-42",
+    log_format=LogFormat.JSON,
+)
+scope_logger.info("Running scoped operation")
+
+cleanup_logging()
+```
+
+## Public API
+
+- `resolve_logs_path(...)`
+- `configure_app_logging(...)`
+- `begin_scope_logging(...)`
+- `end_scope_logging(...)`
+- `bind_context(...)`
+- `cleanup_logging(...)`
+
+## Defaults
+
+- UTF-8 file output
+- timestamped log files in UTC
+- platform-aware default log directories
+- `~/.local/state/<app>/logs` on Linux and similar Unix systems
+- `~/Library/Logs/<app>` on macOS
+- `%LOCALAPPDATA%\<app>\Logs` on Windows
+- no current-working-directory logging unless explicitly requested

utilityhub_logging-0.1.0/README.md

@@ -0,0 +1,73 @@
+# utilityhub-logging
+
+`utilityhub-logging` is a small, project-agnostic package that extends Python's
+standard library `logging` module with deterministic setup and cleanup helpers.
+
+It focuses on the repetitive parts teams tend to rebuild:
+
+- resolving a safe logs directory
+- configuring one log file per application run
+- opening a scoped log for an operation
+- switching between plain text and JSON output
+- attaching async-safe contextual metadata
+- preventing duplicate handlers and cleaning them up reliably
+
+## Install
+
+```bash
+uv add utilityhub-logging
+```
+
+## Quick Start
+
+```python
+import logging
+
+from utilityhub_logging import (
+    LogFormat,
+    begin_scope_logging,
+    bind_context,
+    cleanup_logging,
+    configure_app_logging,
+)
+
+log_file = configure_app_logging(
+    app_name="demo-app",
+    level="INFO",
+    console=True,
+    log_format=LogFormat.PLAIN,
+)
+
+logger = logging.getLogger("demo")
+with bind_context(environment="dev", subsystem="worker"):
+    logger.info("Application started")
+
+scope_logger, scope_file = begin_scope_logging(
+    app_name="demo-app",
+    scope_type="job",
+    scope_id="job-42",
+    log_format=LogFormat.JSON,
+)
+scope_logger.info("Running scoped operation")
+
+cleanup_logging()
+```
+
+## Public API
+
+- `resolve_logs_path(...)`
+- `configure_app_logging(...)`
+- `begin_scope_logging(...)`
+- `end_scope_logging(...)`
+- `bind_context(...)`
+- `cleanup_logging(...)`
+
+## Defaults
+
+- UTF-8 file output
+- timestamped log files in UTC
+- platform-aware default log directories
+- `~/.local/state/<app>/logs` on Linux and similar Unix systems
+- `~/Library/Logs/<app>` on macOS
+- `%LOCALAPPDATA%\<app>\Logs` on Windows
+- no current-working-directory logging unless explicitly requested

utilityhub_logging-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "utilityhub-logging"
+version = "0.1.0"
+description = "Project-agnostic logging orchestration utilities built on Python's stdlib logging package"
+readme = "README.md"
+authors = [{ name = "Rajesh Das", email = "rajesh@hyperoot.dev" }]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+utilityhub_logging = "utilityhub_logging:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"

utilityhub_logging-0.1.0/src/utilityhub_logging/__init__.py

@@ -0,0 +1,26 @@
+"""Composable logging utilities built on Python's standard library logging package."""
+
+from utilityhub_logging.cleanup import cleanup_logging
+from utilityhub_logging.context import bind_context
+from utilityhub_logging.formatters import JsonFormatter, PlainTextFormatter
+from utilityhub_logging.paths import resolve_logs_path
+from utilityhub_logging.scopes import begin_scope_logging, end_scope_logging
+from utilityhub_logging.setup import configure_app_logging
+from utilityhub_logging.types import LogFormat, LogPathConvention
+
+__all__: list[str] = [
+    "JsonFormatter",
+    "LogFormat",
+    "LogPathConvention",
+    "PlainTextFormatter",
+    "begin_scope_logging",
+    "bind_context",
+    "cleanup_logging",
+    "configure_app_logging",
+    "end_scope_logging",
+    "resolve_logs_path",
+]
+
+
+def main() -> None:
+    print("utilityhub-logging: import and configure via `configure_app_logging()`")

utilityhub_logging-0.1.0/src/utilityhub_logging/cleanup.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from utilityhub_logging.context import clear_context
+from utilityhub_logging.types import ManagedHandlerKind
+
+_MANAGED_HANDLER_FLAG = "_utilityhub_managed"
+_MANAGED_HANDLER_KIND = "_utilityhub_kind"
+_MANAGED_HANDLER_PATH = "_utilityhub_log_path"
+
+
+def mark_handler(
+    handler: logging.Handler,
+    *,
+    kind: ManagedHandlerKind,
+    file_path: Path | None = None,
+) -> logging.Handler:
+    setattr(handler, _MANAGED_HANDLER_FLAG, True)
+    setattr(handler, _MANAGED_HANDLER_KIND, kind.value)
+    setattr(handler, _MANAGED_HANDLER_PATH, file_path)
+    return handler
+
+
+def is_managed_handler(handler: logging.Handler, *, kind: ManagedHandlerKind | None = None) -> bool:
+    if not getattr(handler, _MANAGED_HANDLER_FLAG, False):
+        return False
+    if kind is None:
+        return True
+    return getattr(handler, _MANAGED_HANDLER_KIND, None) == kind.value
+
+
+def cleanup_logging(
+    logger: logging.Logger | None = None,
+    *,
+    kind: ManagedHandlerKind | None = None,
+    close_all_loggers: bool = False,
+) -> None:
+    if close_all_loggers:
+        logger_dict = logging.root.manager.loggerDict
+        for candidate in [logging.getLogger()] + [
+            value for value in logger_dict.values() if isinstance(value, logging.Logger)
+        ]:
+            cleanup_logging(candidate, kind=kind)
+        clear_context()
+        return
+
+    target = logging.getLogger() if logger is None else logger
+    handlers = list(target.handlers)
+    for handler in handlers:
+        if not is_managed_handler(handler, kind=kind):
+            continue
+        target.removeHandler(handler)
+        try:
+            handler.flush()
+        finally:
+            handler.close()

utilityhub_logging-0.1.0/src/utilityhub_logging/context.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import contextvars
+import logging
+from collections.abc import Mapping
+from contextlib import AbstractContextManager
+from contextvars import Token
+from typing import Any
+
+_LOG_CONTEXT: contextvars.ContextVar[dict[str, Any] | None] = contextvars.ContextVar(
+    "utilityhub_logging_context",
+    default=None,
+)
+
+_RESERVED_LOG_KEYS = {
+    "args",
+    "asctime",
+    "created",
+    "exc_info",
+    "exc_text",
+    "filename",
+    "funcName",
+    "levelname",
+    "levelno",
+    "lineno",
+    "message",
+    "module",
+    "msecs",
+    "msg",
+    "name",
+    "pathname",
+    "process",
+    "processName",
+    "relativeCreated",
+    "stack_info",
+    "thread",
+    "threadName",
+}
+
+
+def get_context() -> dict[str, Any]:
+    return dict(_LOG_CONTEXT.get() or {})
+
+
+class BoundContext(AbstractContextManager["BoundContext"]):
+    def __init__(self, token: Token[dict[str, Any] | None]) -> None:
+        self._token = token
+        self._closed = False
+
+    def __enter__(self) -> BoundContext:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if not self._closed:
+            _LOG_CONTEXT.reset(self._token)
+            self._closed = True
+
+
+def bind_context(**context: Any) -> BoundContext:
+    current = dict(_LOG_CONTEXT.get() or {})
+    current.update({key: value for key, value in context.items() if value is not None})
+    return BoundContext(_LOG_CONTEXT.set(current))
+
+
+def clear_context() -> None:
+    _LOG_CONTEXT.set({})
+
+
+class ContextFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        merged_context = get_context()
+        extra_context = getattr(record, "utilityhub_context", None)
+        if isinstance(extra_context, Mapping):
+            merged_context.update(extra_context)
+        record.utilityhub_context = merged_context
+        for key, value in merged_context.items():
+            if key.isidentifier() and key not in _RESERVED_LOG_KEYS:
+                setattr(record, key, value)
+        return True

utilityhub_logging-0.1.0/src/utilityhub_logging/formatters.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+
+def _format_timestamp(created: float) -> str:
+    dt = datetime.fromtimestamp(created, tz=UTC)
+    return dt.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class PlainTextFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        timestamp = _format_timestamp(record.created)
+        message = record.getMessage()
+        context = getattr(record, "utilityhub_context", {})
+        context_text = ""
+        if context:
+            pairs = " ".join(f"{key}={value}" for key, value in sorted(context.items()))
+            context_text = f" [{pairs}]"
+
+        parts = [timestamp, record.levelname, record.name, "-", message]
+        rendered = " ".join(parts) + context_text
+
+        if record.exc_info:
+            rendered = f"{rendered}\n{self.formatException(record.exc_info)}"
+        if record.stack_info:
+            rendered = f"{rendered}\n{self.formatStack(record.stack_info)}"
+        return rendered
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": _format_timestamp(record.created),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        context = getattr(record, "utilityhub_context", {})
+        if context:
+            payload["context"] = dict(sorted(context.items()))
+        if record.exc_info:
+            payload["exception"] = self.formatException(record.exc_info)
+        if record.stack_info:
+            payload["stack"] = self.formatStack(record.stack_info)
+        return json.dumps(payload, ensure_ascii=False, sort_keys=True)

utilityhub_logging-0.1.0/src/utilityhub_logging/paths.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from utilityhub_logging.types import LogPathConvention
+
+
+def resolve_logs_path(
+    app_name: str,
+    logs_path: str | os.PathLike[str] | None = None,
+    *,
+    default_convention: LogPathConvention | str = LogPathConvention.PLATFORM,
+    create: bool = True,
+) -> Path:
+    if not app_name.strip():
+        msg = "app_name must be a non-empty string"
+        raise ValueError(msg)
+
+    if logs_path is not None:
+        path = Path(logs_path).expanduser()
+    else:
+        convention = LogPathConvention(default_convention)
+        path = _resolve_default_logs_path(app_name=app_name, convention=convention)
+
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+
+    return path
+
+
+def _resolve_default_logs_path(app_name: str, *, convention: LogPathConvention) -> Path:
+    if convention is LogPathConvention.CWD:
+        return Path.cwd() / "logs" / app_name
+
+    if convention is LogPathConvention.HOME_HIDDEN:
+        return Path.home() / f".{app_name}" / "logs"
+
+    if os.name == "nt":
+        local_app_data = os.getenv("LOCALAPPDATA")
+        if local_app_data:
+            return Path(local_app_data) / app_name / "Logs"
+        return Path.home() / "AppData" / "Local" / app_name / "Logs"
+
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Logs" / app_name
+
+    return Path.home() / ".local" / "state" / app_name / "logs"

utilityhub_logging-0.1.0/src/utilityhub_logging/scopes.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from utilityhub_logging.cleanup import cleanup_logging, mark_handler
+from utilityhub_logging.context import ContextFilter, bind_context
+from utilityhub_logging.paths import resolve_logs_path
+from utilityhub_logging.setup import _build_formatter, _normalize_level, _slugify, _utc_now_stamp
+from utilityhub_logging.types import LogFormat, LogPathConvention, ManagedHandlerKind
+
+
+def begin_scope_logging(
+    scope_type: str,
+    scope_id: str,
+    *,
+    app_name: str,
+    level: int | str = "INFO",
+    logs_path: str | Path | None = None,
+    default_convention: LogPathConvention | str = LogPathConvention.PLATFORM,
+    log_format: LogFormat | str = LogFormat.PLAIN,
+    logger: logging.Logger | None = None,
+    propagate: bool = False,
+) -> tuple[logging.Logger, Path]:
+    if not scope_type.strip():
+        msg = "scope_type must be a non-empty string"
+        raise ValueError(msg)
+    if not scope_id.strip():
+        msg = "scope_id must be a non-empty string"
+        raise ValueError(msg)
+
+    target_logger = logger or logging.getLogger(f"{app_name}.{scope_type}.{scope_id}")
+    target_logger.setLevel(_normalize_level(level))
+    target_logger.propagate = propagate
+
+    cleanup_logging(target_logger, kind=ManagedHandlerKind.SCOPE)
+
+    root_logs_path = resolve_logs_path(
+        app_name=app_name,
+        logs_path=logs_path,
+        default_convention=default_convention,
+    )
+    scope_logs_path = root_logs_path / "scopes" / _slugify(scope_type)
+    scope_logs_path.mkdir(parents=True, exist_ok=True)
+    file_path = scope_logs_path / f"{_slugify(scope_id)}-{_utc_now_stamp()}.log"
+
+    handler = logging.FileHandler(file_path, encoding="utf-8")
+    handler.setLevel(_normalize_level(level))
+    handler.setFormatter(_build_formatter(log_format))
+    handler.addFilter(ContextFilter())
+    target_logger.addHandler(mark_handler(handler, kind=ManagedHandlerKind.SCOPE, file_path=file_path))
+
+    bind_context(scope_type=scope_type, scope_id=scope_id)
+    return target_logger, file_path
+
+
+def end_scope_logging(logger: logging.Logger | None = None) -> None:
+    cleanup_logging(logger, kind=ManagedHandlerKind.SCOPE)

utilityhub_logging-0.1.0/src/utilityhub_logging/setup.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+from utilityhub_logging.cleanup import cleanup_logging, mark_handler
+from utilityhub_logging.context import ContextFilter, bind_context
+from utilityhub_logging.formatters import JsonFormatter, PlainTextFormatter
+from utilityhub_logging.paths import resolve_logs_path
+from utilityhub_logging.types import LogFormat, LogPathConvention, ManagedHandlerKind
+
+
+def configure_app_logging(
+    app_name: str,
+    *,
+    level: int | str = "INFO",
+    logs_path: str | Path | None = None,
+    default_convention: LogPathConvention | str = LogPathConvention.PLATFORM,
+    console: bool = True,
+    log_format: LogFormat | str = LogFormat.PLAIN,
+    logger: logging.Logger | None = None,
+    propagate: bool = False,
+) -> Path:
+    target_logger = logging.getLogger() if logger is None else logger
+    target_logger.setLevel(_normalize_level(level))
+    target_logger.propagate = propagate
+
+    cleanup_logging(target_logger, kind=ManagedHandlerKind.APP)
+
+    resolved_logs_path = resolve_logs_path(
+        app_name=app_name,
+        logs_path=logs_path,
+        default_convention=default_convention,
+    )
+    session_id = uuid.uuid4().hex[:8]
+    timestamp = _utc_now_stamp()
+    file_path = resolved_logs_path / f"{_slugify(app_name)}-{timestamp}-{session_id}.log"
+
+    formatter = _build_formatter(log_format)
+    file_handler = logging.FileHandler(file_path, encoding="utf-8")
+    file_handler.setLevel(_normalize_level(level))
+    file_handler.setFormatter(formatter)
+    file_handler.addFilter(ContextFilter())
+    target_logger.addHandler(mark_handler(file_handler, kind=ManagedHandlerKind.APP, file_path=file_path))
+
+    if console:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(_normalize_level(level))
+        console_handler.setFormatter(formatter)
+        console_handler.addFilter(ContextFilter())
+        target_logger.addHandler(mark_handler(console_handler, kind=ManagedHandlerKind.APP))
+
+    bind_context(app_name=app_name, session_id=session_id)
+    return file_path
+
+
+def _build_formatter(log_format: LogFormat | str) -> logging.Formatter:
+    selected = LogFormat(log_format)
+    if selected is LogFormat.JSON:
+        return JsonFormatter()
+    return PlainTextFormatter()
+
+
+def _normalize_level(level: int | str) -> int:
+    if isinstance(level, int):
+        return level
+    normalized = logging.getLevelName(level.upper())
+    if isinstance(normalized, int):
+        return normalized
+    msg = f"Unsupported log level: {level!r}"
+    raise ValueError(msg)
+
+
+def _utc_now_stamp() -> str:
+    return datetime.now(tz=UTC).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _slugify(value: str) -> str:
+    chars = [char.lower() if char.isalnum() else "-" for char in value.strip()]
+    slug = "".join(chars).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug or "log"

utilityhub_logging-0.1.0/src/utilityhub_logging/types.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+
+class LogFormat(StrEnum):
+    PLAIN = "plain"
+    JSON = "json"
+
+
+class LogPathConvention(StrEnum):
+    PLATFORM = "platform"
+    HOME_HIDDEN = "home_hidden"
+    CWD = "cwd"
+
+
+class ManagedHandlerKind(StrEnum):
+    APP = "app"
+    SCOPE = "scope"
+
+
+@dataclass(frozen=True, slots=True)
+class ManagedHandlerRecord:
+    logger_name: str
+    handler_name: str
+    kind: ManagedHandlerKind
+    file_path: Path | None = None