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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.1.0
+Version: 0.1.0.post1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -34,9 +34,20 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 ## API
 
 - Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
-- Structured logging helper: `instrukt_ai_logging.log_kv(logger, level, {"msg": "...", ...})`
+- Logger helper: `instrukt_ai_logging.get_logger(name)` (named `**kv` logging)
 - CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
 
+Example:
+
+```py
+import logging
+from instrukt_ai_logging import configure_logging
+
+configure_logging("teleclaude")
+logger = logging.getLogger("teleclaude.core")
+logger.info("job_started", job_id="abc123", user_id=123)
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

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

@@ -24,9 +24,20 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 ## API
 
 - Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
-- Structured logging helper: `instrukt_ai_logging.log_kv(logger, level, {"msg": "...", ...})`
+- Logger helper: `instrukt_ai_logging.get_logger(name)` (named `**kv` logging)
 - CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
 
+Example:
+
+```py
+import logging
+from instrukt_ai_logging import configure_logging
+
+configure_logging("teleclaude")
+logger = logging.getLogger("teleclaude.core")
+logger.info("job_started", job_id="abc123", user_id=123)
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

instruktai_python_logger-0.1.0.post1/instrukt_ai_logging/__init__.py

@@ -0,0 +1,19 @@
+"""InstruktAI logging standard library.
+
+See `README.md` for usage and `docs/design.md` for design intent.
+"""
+
+__all__ = [
+    "__version__",
+    "configure_logging",
+    "get_logger",
+]
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("instruktai-python-logger")
+except Exception:  # pragma: no cover
+    __version__ = "0.0.0"
+
+from instrukt_ai_logging.logging import configure_logging, get_logger  # noqa: E402  (intentional re-export)

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

@@ -4,7 +4,6 @@ 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
@@ -12,6 +11,42 @@ from pathlib import Path
 from typing import Any
 
 
+def _normalize_env_prefix(name: str) -> str:
+    # TELECLAUDE, MY_APP, etc.
+    raw = name.strip().upper()
+    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 env prefix")
+    return raw
+
+
+def _normalize_app_name(name: str) -> str:
+    # teleclaude, my-app, etc.
+    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 app name")
+    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:
@@ -143,24 +178,79 @@ class LogfmtFormatter(UtcMillisFormatter):
         return " ".join(parts)
 
 
-def log_kv(logger: logging.Logger, level: int, data: Mapping[str, Any]) -> None:
-    """Log a key/value event.
+class InstruktLogger(logging.Logger):
+    """Logger that accepts arbitrary `**kv` fields.
+
+    This lets callers use normal logger methods with named key/value pairs:
+      logging.getLogger("...").info("event_name", job_id=..., user_id=...)
 
-    `data` MUST include `msg` and may include any other serializable values.
+    All `**kv` values are serialized to text by the formatter.
     """
-    if "msg" not in data:
-        raise ValueError('log_kv requires a "msg" key')
 
-    msg = str(data["msg"])
-    kv: dict[str, object] = {}
-    for key, value in data.items():
-        if key == "msg":
-            continue
-        if not _SAFE_KEY.fullmatch(key):
-            raise ValueError(f"Invalid key for log_kv: {key!r}")
-        kv[key] = value
+    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 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)
+
+    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 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 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)
 
-    logger.log(level, msg, extra={"kv": 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 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 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 get_logger(name: str) -> logging.Logger:
+    """Compatibility helper (returns a normal logger, but with `**kv` support after configuration)."""
+    return logging.getLogger(name)
 
 
 class _ThirdPartySelectorFilter(logging.Filter):
@@ -225,10 +315,8 @@ def _ensure_log_dir(log_dir: Path) -> None:
 
 
 def configure_logging(
+    name: str,
     *,
-    env_prefix: str,
-    app_logger_prefix: str,
-    app_name: str,
     log_filename: str | None = None,
     max_message_chars: int = 4000,
 ) -> Path:
@@ -236,12 +324,23 @@ 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"
+
     contract = LoggingContract(
         env_prefix=env_prefix,
         app_logger_prefix=app_logger_prefix,
         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, ""))
@@ -259,7 +358,7 @@ def configure_logging(
         log_dir = _fallback_log_root(app_name)
         _ensure_log_dir(log_dir)
 
-    log_file = log_dir / (log_filename or f"{app_name}.log")
+    log_file = log_dir / log_filename
 
     formatter = LogfmtFormatter(max_message_chars=max_message_chars)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.1.0
+Version: 0.1.0.post1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -34,9 +34,20 @@ pip install git+ssh://git@github.com/InstruktAI/python-logger.git
 ## API
 
 - Python entrypoint: `instrukt_ai_logging.configure_logging(...)`
-- Structured logging helper: `instrukt_ai_logging.log_kv(logger, level, {"msg": "...", ...})`
+- Logger helper: `instrukt_ai_logging.get_logger(name)` (named `**kv` logging)
 - CLI entrypoint: `instrukt-ai-logs` (reads recent log lines)
 
+Example:
+
+```py
+import logging
+from instrukt_ai_logging import configure_logging
+
+configure_logging("teleclaude")
+logger = logging.getLogger("teleclaude.core")
+logger.info("job_started", job_id="abc123", user_id=123)
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

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

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

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

@@ -4,7 +4,7 @@ from tempfile import TemporaryDirectory
 
 import pytest
 
-from instrukt_ai_logging import configure_logging, log_kv
+from instrukt_ai_logging import configure_logging
 
 
 @pytest.fixture()
@@ -35,11 +35,7 @@ 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(
-            env_prefix="TELECLAUDE",
-            app_logger_prefix="teleclaude",
-            app_name="teleclaude",
-        )
+        log_path = configure_logging("teleclaude")
 
         logging.getLogger("teleclaude.core").debug("hello from ours")
         logging.getLogger("httpcore.http11").info("hello from third-party")
@@ -57,11 +53,7 @@ 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(
-            env_prefix="TELECLAUDE",
-            app_logger_prefix="teleclaude",
-            app_name="teleclaude",
-        )
+        log_path = configure_logging("teleclaude")
 
         # Ensure records are actually created even though root is WARNING in spotlight mode.
         httpcore_logger = logging.getLogger("httpcore")
@@ -85,39 +77,15 @@ def test_spotlight_allows_selected_third_party_only(isolated_logging, monkeypatc
         assert "telegram info" not in content
 
 
-def test_log_kv_requires_msg_key(isolated_logging, monkeypatch):
+def test_named_kv_logger_emits_pairs(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
         monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
 
-        configure_logging(
-            env_prefix="TELECLAUDE",
-            app_logger_prefix="teleclaude",
-            app_name="teleclaude",
-        )
+        log_path = configure_logging("teleclaude")
 
-        with pytest.raises(ValueError):
-            log_kv(logging.getLogger("teleclaude.core"), logging.INFO, {"session": "abc"})
-
-
-def test_log_kv_emits_pairs(isolated_logging, monkeypatch):
-    with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
-        monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
-        monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
-
-        log_path = configure_logging(
-            env_prefix="TELECLAUDE",
-            app_logger_prefix="teleclaude",
-            app_name="teleclaude",
-        )
-
-        log_kv(
-            logging.getLogger("teleclaude.core"),
-            logging.INFO,
-            {"msg": "hello", "session": "abc123", "n": 1},
-        )
+        logging.getLogger("teleclaude.core").info("hello", session="abc123", n=1)
 
         content = _read_text(log_path)
         assert 'msg="hello"' in content

instruktai_python_logger-0.1.0/instrukt_ai_logging/__init__.py

@@ -1,14 +0,0 @@
-"""InstruktAI logging standard library.
-
-See `README.md` for usage and `docs/design.md` for design intent.
-"""
-
-__all__ = [
-    "__version__",
-    "configure_logging",
-    "log_kv",
-]
-
-__version__ = "0.0.0"
-
-from instrukt_ai_logging.logging import configure_logging, log_kv  # noqa: E402  (intentional re-export)