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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.1.0
+Version: 0.1.1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -34,9 +34,19 @@ 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
+from instrukt_ai_logging import configure_logging, get_logger
+
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

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

@@ -24,9 +24,19 @@ 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
+from instrukt_ai_logging import configure_logging, get_logger
+
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

instruktai_python_logger-0.1.1/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.1}/instrukt_ai_logging/logging.py

@@ -12,6 +12,30 @@ 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 _level_name_to_int(level_name: str, default: int) -> int:
     name = level_name.strip().upper()
     if not name:
@@ -143,24 +167,60 @@ class LogfmtFormatter(UtcMillisFormatter):
         return " ".join(parts)
 
 
-def log_kv(logger: logging.Logger, level: int, data: Mapping[str, Any]) -> None:
-    """Log a key/value event.
-
-    `data` MUST include `msg` and may include any other serializable values.
-    """
-    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():
+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):
-            raise ValueError(f"Invalid key for log_kv: {key!r}")
-        kv[key] = value
+            continue
+        safe[key] = value
+
+    logger.log(level, msg, extra={"kv": safe})
 
-    logger.log(level, msg, extra={"kv": kv})
+
+class KVLogger:
+    """Ergonomic key/value logger.
+
+    Callers use `KVLogger` like a normal logger:
+      logger.info("event_name", job_id=..., user_id=...)
+
+    This keeps call sites human-friendly while still producing strict logfmt pairs.
+    """
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    @property
+    def name(self) -> str:
+        return self._logger.name
+
+    def debug(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.DEBUG, msg, kv)
+
+    def info(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.INFO, msg, kv)
+
+    def warning(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.WARNING, msg, kv)
+
+    def error(self, msg: str, **kv: Any) -> None:
+        _log_kv(self._logger, logging.ERROR, msg, kv)
+
+    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: str, **kv: Any) -> None:
+        _log_kv(self._logger, level, msg, kv)
+
+
+def get_logger(name: str) -> KVLogger:
+    """Return a `KVLogger` wrapper for the named logger."""
+    return KVLogger(logging.getLogger(name))
 
 
 class _ThirdPartySelectorFilter(logging.Filter):
@@ -226,9 +286,10 @@ def _ensure_log_dir(log_dir: Path) -> None:
 
 def configure_logging(
     *,
-    env_prefix: str,
     app_logger_prefix: str,
-    app_name: 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:
@@ -236,6 +297,15 @@ def configure_logging(
 
     Returns the resolved log file path in use.
     """
+    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,
         app_logger_prefix=app_logger_prefix,

{instruktai_python_logger-0.1.0 → 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
+Version: 0.1.1
 Summary: Centralized logging utilities for InstruktAI Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -34,9 +34,19 @@ 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
+from instrukt_ai_logging import configure_logging, get_logger
+
+configure_logging(name="teleclaude", app_logger_prefix="teleclaude")
+logger = get_logger("teleclaude.core")
+logger.info("job_started", job_id="abc123")
+```
+
 ## Environment variables (contract)
 
 Per-app prefix model (example uses `TELECLAUDE_`):

{instruktai_python_logger-0.1.0 → 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"
+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 → 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, log_kv
+from instrukt_ai_logging import configure_logging, get_logger
 
 
 @pytest.fixture()
@@ -36,9 +36,8 @@ def test_our_logs_respect_app_level_and_third_party_baseline(isolated_logging, m
         monkeypatch.delenv("TELECLAUDE_THIRD_PARTY_LOGGERS", raising=False)
 
         log_path = configure_logging(
-            env_prefix="TELECLAUDE",
             app_logger_prefix="teleclaude",
-            app_name="teleclaude",
+            name="teleclaude",
         )
 
         logging.getLogger("teleclaude.core").debug("hello from ours")
@@ -58,9 +57,8 @@ def test_spotlight_allows_selected_third_party_only(isolated_logging, monkeypatc
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOGGERS", "httpcore")
 
         log_path = configure_logging(
-            env_prefix="TELECLAUDE",
             app_logger_prefix="teleclaude",
-            app_name="teleclaude",
+            name="teleclaude",
         )
 
         # Ensure records are actually created even though root is WARNING in spotlight mode.
@@ -85,39 +83,19 @@ 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):
-    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",
-        )
-
-        with pytest.raises(ValueError):
-            log_kv(logging.getLogger("teleclaude.core"), logging.INFO, {"session": "abc"})
-
-
-def test_log_kv_emits_pairs(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")
 
         log_path = configure_logging(
-            env_prefix="TELECLAUDE",
             app_logger_prefix="teleclaude",
-            app_name="teleclaude",
+            name="teleclaude",
         )
 
-        log_kv(
-            logging.getLogger("teleclaude.core"),
-            logging.INFO,
-            {"msg": "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

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)