instruktai-python-logger 0.1.0.post1__tar.gz → 0.1.1__tar.gz

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.1.0.post1
+Version: 0.1.1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -40,12 +40,11 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 Example:
 
 ```py
-import logging
-from instrukt_ai_logging import configure_logging
+from instrukt_ai_logging import configure_logging, get_logger
 
-configure_logging("teleclaude")
-logger = logging.getLogger("teleclaude.core")
-logger.info("job_started", job_id="abc123", user_id=123)
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
 ```
 
 ## Environment variables (contract)

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/README.md

@@ -30,12 +30,11 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 Example:
 
 ```py
-import logging
-from instrukt_ai_logging import configure_logging
+from instrukt_ai_logging import configure_logging, get_logger
 
-configure_logging("teleclaude")
-logger = logging.getLogger("teleclaude.core")
-logger.info("job_started", job_id="abc123", user_id=123)
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
 ```
 
 ## Environment variables (contract)

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/instrukt_ai_logging/logging.py

@@ -4,6 +4,7 @@ import logging
 import os
 import re
 import sys
+from collections.abc import Mapping
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from logging.handlers import WatchedFileHandler
@@ -35,18 +36,6 @@ def _normalize_app_name(name: str) -> str:
     return raw
 
 
-def _normalize_logger_prefix(name: str) -> str:
-    # teleclaude, crypto_ai, etc. (match Python package style)
-    raw = name.strip().lower()
-    if not raw:
-        raise ValueError("name must be non-empty")
-    raw = re.sub(r"[^a-z0-9]+", "_", raw)
-    raw = re.sub(r"_+", "_", raw).strip("_")
-    if not raw:
-        raise ValueError("name did not produce a valid logger prefix")
-    return raw
-
-
 def _level_name_to_int(level_name: str, default: int) -> int:
     name = level_name.strip().upper()
     if not name:
@@ -178,79 +167,60 @@ class LogfmtFormatter(UtcMillisFormatter):
         return " ".join(parts)
 
 
-class InstruktLogger(logging.Logger):
-    """Logger that accepts arbitrary `**kv` fields.
+def _log_kv(logger: logging.Logger, level: int, msg: str, kv: Mapping[str, Any]) -> None:
+    """Internal helper: attach `kv` pairs without forcing callers to use `extra`."""
+    safe: dict[str, object] = {}
+    for key, value in kv.items():
+        if not isinstance(key, str):
+            continue
+        if key == "msg":
+            continue
+        if not _SAFE_KEY.fullmatch(key):
+            continue
+        safe[key] = value
+
+    logger.log(level, msg, extra={"kv": safe})
+
+
+class KVLogger:
+    """Ergonomic key/value logger.
 
-    This lets callers use normal logger methods with named key/value pairs:
-      logging.getLogger("...").info("event_name", job_id=..., user_id=...)
+    Callers use `KVLogger` like a normal logger:
+      logger.info("event_name", job_id=..., user_id=...)
 
-    All `**kv` values are serialized to text by the formatter.
+    This keeps call sites human-friendly while still producing strict logfmt pairs.
     """
 
-    def _log_with_kv(self, level: int, msg: object, args: tuple[object, ...], **kwargs: Any) -> None:
-        exc_info = kwargs.pop("exc_info", None)
-        stack_info = kwargs.pop("stack_info", False)
-        stacklevel = kwargs.pop("stacklevel", 1)
-        extra = kwargs.pop("extra", None)
-
-        # Remaining kwargs are treated as `kv`.
-        kv: dict[str, object] = {k: v for k, v in kwargs.items() if _SAFE_KEY.fullmatch(k)}
-
-        merged_extra: dict[str, object] = {}
-        if isinstance(extra, dict):
-            merged_extra.update(extra)
-
-        existing_kv = merged_extra.get("kv")
-        if isinstance(existing_kv, dict):
-            merged_extra["kv"] = {**existing_kv, **kv}
-        else:
-            merged_extra["kv"] = kv
-
-        super()._log(
-            level,
-            msg,
-            args,
-            exc_info=exc_info,
-            extra=merged_extra,
-            stack_info=stack_info,
-            stacklevel=stacklevel,
-        )
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
 
-    def debug(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if self.isEnabledFor(logging.DEBUG):
-            self._log_with_kv(logging.DEBUG, msg, args, **kwargs)
+    @property
+    def name(self) -> str:
+        return self._logger.name
 
-    def info(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if self.isEnabledFor(logging.INFO):
-            self._log_with_kv(logging.INFO, msg, args, **kwargs)
+    def debug(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.DEBUG, msg, kv)
 
-    def warning(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if self.isEnabledFor(logging.WARNING):
-            self._log_with_kv(logging.WARNING, msg, args, **kwargs)
+    def info(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.INFO, msg, kv)
 
-    def error(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if self.isEnabledFor(logging.ERROR):
-            self._log_with_kv(logging.ERROR, msg, args, **kwargs)
+    def warning(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.WARNING, msg, kv)
 
-    def critical(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if self.isEnabledFor(logging.CRITICAL):
-            self._log_with_kv(logging.CRITICAL, msg, args, **kwargs)
+    def error(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.ERROR, msg, kv)
 
-    def exception(self, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        kwargs.setdefault("exc_info", True)
-        if self.isEnabledFor(logging.ERROR):
-            self._log_with_kv(logging.ERROR, msg, args, **kwargs)
+    def exception(self, msg: str, **kv: Any) -> None:
+        # Match logging.exception behavior (includes exc_info=True).
+        self._logger.exception(msg, extra={"kv": {k: v for k, v in kv.items() if _SAFE_KEY.fullmatch(k)}})
 
-    def log(self, level: int, msg: object, *args: object, **kwargs: Any) -> None:  # type: ignore[override]
-        if not isinstance(level, int):
-            raise TypeError("level must be an int")
-        if self.isEnabledFor(level):
-            self._log_with_kv(level, msg, args, **kwargs)
+    def log(self, level: int, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, level, msg, kv)
 
 
-def get_logger(name: str) -> logging.Logger:
-    """Compatibility helper (returns a normal logger, but with `**kv` support after configuration)."""
-    return logging.getLogger(name)
+def get_logger(name: str) -> KVLogger:
+    """Return a `KVLogger` wrapper for the named logger."""
+    return KVLogger(logging.getLogger(name))
 
 
 class _ThirdPartySelectorFilter(logging.Filter):
@@ -315,8 +285,11 @@ def _ensure_log_dir(log_dir: Path) -> None:
 
 
 def configure_logging(
-    name: str,
     *,
+    app_logger_prefix: str,
+    name: str | None = None,
+    env_prefix: str | None = None,
+    app_name: str | None = None,
     log_filename: str | None = None,
     max_message_chars: int = 4000,
 ) -> Path:
@@ -324,10 +297,14 @@ def configure_logging(
 
     Returns the resolved log file path in use.
     """
-    env_prefix = _normalize_env_prefix(name)
-    app_logger_prefix = _normalize_logger_prefix(name)
-    app_name = app_logger_prefix
-    log_filename = log_filename or f"{app_logger_prefix}.log"
+    if name is not None:
+        if env_prefix is not None or app_name is not None:
+            raise ValueError("Pass either name= OR env_prefix/app_name (not both)")
+        env_prefix = _normalize_env_prefix(name)
+        app_name = _normalize_app_name(name)
+
+    if env_prefix is None or app_name is None:
+        raise ValueError("Missing required config: name= OR both env_prefix= and app_name=")
 
     contract = LoggingContract(
         env_prefix=env_prefix,
@@ -335,12 +312,6 @@ def configure_logging(
         app_name=app_name,
     )
 
-    # Ensure all loggers accept arbitrary `**kv` (no wrapper at call sites).
-    logging.setLoggerClass(InstruktLogger)
-    for obj in logging.root.manager.loggerDict.values():
-        if isinstance(obj, logging.Logger) and not isinstance(obj, InstruktLogger):
-            obj.__class__ = InstruktLogger
-
     our_level_name = (os.getenv(contract.env_log_level) or "INFO").upper()
     third_party_level_name = (os.getenv(contract.env_third_party_level) or "WARNING").upper()
     spotlight = _parse_csv(os.getenv(contract.env_third_party_loggers, ""))
@@ -358,7 +329,7 @@ def configure_logging(
         log_dir = _fallback_log_root(app_name)
         _ensure_log_dir(log_dir)
 
-    log_file = log_dir / log_filename
+    log_file = log_dir / (log_filename or f"{app_name}.log")
 
     formatter = LogfmtFormatter(max_message_chars=max_message_chars)
 

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/instruktai_python_logger.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.1.0.post1
+Version: 0.1.1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -40,12 +40,11 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 Example:
 
 ```py
-import logging
-from instrukt_ai_logging import configure_logging
+from instrukt_ai_logging import configure_logging, get_logger
 
-configure_logging("teleclaude")
-logger = logging.getLogger("teleclaude.core")
-logger.info("job_started", job_id="abc123", user_id=123)
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
 ```
 
 ## Environment variables (contract)

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instruktai-python-logger"
-version = "0.1.0.post1"
+version = "0.1.1"
 description = "Centralized logging utilities for InstruktAI Python services."
 readme = "README.md"
 requires-python = ">=3.11"

{instruktai_python_logger-0.1.0.post1 → instruktai_python_logger-0.1.1}/tests/test_configure_logging.py

@@ -4,7 +4,7 @@ from tempfile import TemporaryDirectory
 
 import pytest
 
-from instrukt_ai_logging import configure_logging
+from instrukt_ai_logging import configure_logging, get_logger
 
 
 @pytest.fixture()
@@ -35,7 +35,10 @@ def test_our_logs_respect_app_level_and_third_party_baseline(isolated_logging, m
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
         monkeypatch.delenv("TELECLAUDE_THIRD_PARTY_LOGGERS", raising=False)
 
-        log_path = configure_logging("teleclaude")
+        log_path = configure_logging(
+            app_logger_prefix="teleclaude",
+            name="teleclaude",
+        )
 
         logging.getLogger("teleclaude.core").debug("hello from ours")
         logging.getLogger("httpcore.http11").info("hello from third-party")
@@ -53,7 +56,10 @@ def test_spotlight_allows_selected_third_party_only(isolated_logging, monkeypatc
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOGGERS", "httpcore")
 
-        log_path = configure_logging("teleclaude")
+        log_path = configure_logging(
+            app_logger_prefix="teleclaude",
+            name="teleclaude",
+        )
 
         # Ensure records are actually created even though root is WARNING in spotlight mode.
         httpcore_logger = logging.getLogger("httpcore")
@@ -83,9 +89,13 @@ def test_named_kv_logger_emits_pairs(isolated_logging, monkeypatch):
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
 
-        log_path = configure_logging("teleclaude")
+        log_path = configure_logging(
+            app_logger_prefix="teleclaude",
+            name="teleclaude",
+        )
 
-        logging.getLogger("teleclaude.core").info("hello", session="abc123", n=1)
+        logger = get_logger("teleclaude.core")
+        logger.info("hello", session="abc123", n=1)
 
         content = _read_text(log_path)
         assert 'msg="hello"' in content