log-foundry 0.10.2.dev43__tar.gz → 0.10.2.dev44__tar.gz

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev43
+Version: 0.10.2.dev44
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -327,8 +327,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -341,7 +341,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -352,6 +353,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev44}/README.md

@@ -291,8 +291,8 @@ await fetch(4127)   # one trace_id; load's parent_span_id == fetch's span_id
 Emit your own structured events from inside a decorated call with the level functions
 `debug` / `info` / `warning` / `error` / `critical`. Each appends one event to the current
 span, so the whole call's logs flush together and share its `trace_id` / `span_id`. Keyword
-arguments land in the event's `fields`; the function name is captured, but arguments and
-return values never are.
+arguments land in the event's `fields` — except the three reserved names below; the function
+name is captured, but arguments and return values never are.
 
 ```python
 @lf.trace
@@ -305,7 +305,8 @@ def process_payment(user_id: int) -> str:
 
 - **`set_baggage(**kv)`** — attach trace-scoped context that is merged into the `fields` of
   every subsequent event in the same execution flow. Precedence, lowest to highest: config
-  `defaults` → span `defaults` → baggage → per-call `fields`. **Trace-scoped means it ends
+  `defaults` → span `defaults` → baggage → per-call fields (`fields=` first, then `**kwargs`
+  over it). **Trace-scoped means it ends
   with the trace:** when the outermost `@trace` call returns *or raises*, the baggage in effect
   before it is restored, so one request's keys do not reach the next request's events. Nested
   calls do not reset — baggage set three calls deep stays visible to its parent and to the
@@ -316,6 +317,18 @@ def process_payment(user_id: int) -> str:
 - **`echo=True`** — *additionally* write a human-readable `LEVEL   message` line to the console
   (`sys.stderr` by default), synchronously, without waiting for the async flush. The event
   still rides the normal pipeline to the sink — echo never redirects.
+- **`fields={...}`** — the escape hatch. `message`, `echo` and `fields` are **reserved**: they
+  are parameters, so `info("x", echo="the payload we echoed back")` would switch on the console
+  line instead of recording a field. Pass them — and any key that is not a Python identifier —
+  through `fields=`:
+
+  ```python
+  lf.info("proxied", fields={"echo": "the payload we echoed back", "content-type": "text/json"})
+  ```
+
+  It reaches its own name too (`fields={"fields": ...}`), so every reserved word has exactly one
+  route through. A key given both ways takes the keyword's value, since `**kwargs` is what you
+  wrote at the call site and `fields=` is usually a mapping built elsewhere.
 - **Orphan logs** — a level call made with no active span is not dropped: it emits a standalone
   one-event span with a fresh `trace_id`, flushed straight to the sink.
 

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev44}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev43"
+version = "0.10.2.dev44"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev43 → log_foundry-0.10.2.dev44}/src/log_foundry/api.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from log_foundry import _diag, context
 from log_foundry.config import _ensure_sink
 from log_foundry.console import ConsoleWriter
@@ -10,6 +12,9 @@ from log_foundry.decorator import _note_orphan_emit
 from log_foundry.ids import new_span_id, new_trace_id
 from log_foundry.model import Span, build_event
 
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
 __all__ = [
     "critical",
     "debug",
@@ -100,13 +105,66 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
             _diag.absorbed("echoing to the console", exc)
 
 
-def debug(message: str, *, echo: bool = False, **fields: object) -> None:
+def _merge(fields: Mapping[str, object] | None, kv: dict[str, object]) -> dict[str, object]:
+    """Combines the explicit ``fields=`` mapping with the keyword form.
+
+    ``echo`` and ``message`` were reserved words stolen from the caller's field namespace:
+    ``info("x", echo="incoming payload echoed back")`` dropped a real field *and* turned on an
+    unwanted console line, and ``message=`` raised ``TypeError`` (SPEC-034 FR-004). ``fields=``
+    is the way round all three — including its own name, which is why the escape hatch can
+    express every key including the ones this signature reserves — and the only way to pass a
+    key that is not a Python identifier.
+
+    The keyword form wins a collision. ``fields=`` is the bulk route, usually a mapping built
+    somewhere else; ``**kv`` is what the caller wrote at this call site, and a literal
+    overriding a base is what ``{**base, **overrides}`` already means in the language.
+
+    A ``fields=`` that is not a mapping is **absorbed, not raised**. This helper runs in the
+    emitter, before :func:`_log`, so it sits outside that function's orphan guard entirely: an
+    unguarded ``{**fields, **kv}`` propagated a ``TypeError`` into the application on all four
+    entry paths, including the orphan one where SPEC-025's promise holds today, and inside a span
+    the decorator then recorded ``status=error`` with an ``error.type`` the caller's code never
+    raised. It was also asymmetric in a way neither reading defends — ``fields=[]`` was silently
+    ignored while ``fields=["x"]`` crashed. The library coerces rather than validates (SPEC-017),
+    so the tolerant half is the one that matches, and the fault is announced by type.
+
+    Args:
+      fields: The explicit mapping, or ``None``.
+      kv: The keyword-collected fields.
+
+    Returns:
+      One mapping, with ``kv`` taking precedence. The caller's ``fields`` is never mutated, and a
+        ``fields=`` that could not be merged is dropped rather than costing the event.
+
+    Raises:
+      None.
+    """
+    if not fields:
+        return kv
+    try:
+        return {**fields, **kv}
+    except Exception as exc:
+        _diag.absorbed("merging the fields= argument", exc, "the fields= argument was ignored")
+        return kv
+
+
+def debug(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``DEBUG`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -114,16 +172,26 @@ def debug(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("DEBUG", message, echo, fields)
+    _log("DEBUG", message, echo, _merge(fields, kv))
 
 
-def info(message: str, *, echo: bool = False, **fields: object) -> None:
+def info(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits an ``INFO`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -131,16 +199,26 @@ def info(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("INFO", message, echo, fields)
+    _log("INFO", message, echo, _merge(fields, kv))
 
 
-def warning(message: str, *, echo: bool = False, **fields: object) -> None:
+def warning(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``WARNING`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -148,16 +226,26 @@ def warning(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("WARNING", message, echo, fields)
+    _log("WARNING", message, echo, _merge(fields, kv))
 
 
-def error(message: str, *, echo: bool = False, **fields: object) -> None:
+def error(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits an ``ERROR`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -165,16 +253,26 @@ def error(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("ERROR", message, echo, fields)
+    _log("ERROR", message, echo, _merge(fields, kv))
 
 
-def critical(message: str, *, echo: bool = False, **fields: object) -> None:
+def critical(
+    message: str,
+    *,
+    echo: bool = False,
+    fields: Mapping[str, object] | None = None,
+    **kv: object,
+) -> None:
     """Emits a ``CRITICAL`` event on the current span, or a standalone orphan span.
 
     Args:
       message: The message text.
       echo: Whether to also write a human-readable console line.
-      **fields: Per-call structured fields.
+      fields: Per-call structured fields, for names ``**kv`` cannot express — the three
+        reserved words ``message``, ``echo`` and ``fields`` itself, and any key that is not a
+        Python identifier at all. Merged **under** ``**kv``, so a name given both ways takes the
+        keyword's value.
+      **kv: Per-call structured fields.
 
     Returns:
       None.
@@ -182,4 +280,4 @@ def critical(message: str, *, echo: bool = False, **fields: object) -> None:
     Raises:
       None.
     """
-    _log("CRITICAL", message, echo, fields)
+    _log("CRITICAL", message, echo, _merge(fields, kv))