log-foundry 0.10.2.dev4__tar.gz → 0.10.2.dev5__tar.gz

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev4
+Version: 0.10.2.dev5
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev5}/pyproject.toml

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

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev5}/src/log_foundry/__init__.py

@@ -3,8 +3,9 @@
 Public façade (module-function shape). Exposes configuration, the ``@trace`` decorator, the
 ``debug/info/warning/error/critical`` emitters, ``set_baggage``, the cross-process propagation
 pair (``continue_trace`` to adopt an inbound context; ``current_traceparent`` /
-``current_trace_context`` / ``current_baggage_header`` to publish this one), ``flush`` (drain and
-keep logging) and ``shutdown`` (drain, close the sink, and stop).
+``current_trace_context`` / ``current_baggage_header`` to publish this one), ``reset_context``
+(clear both for a caller who opens no span), ``flush`` (drain and keep logging) and ``shutdown``
+(drain, close the sink, and stop).
 """
 
 from importlib.metadata import PackageNotFoundError
@@ -16,6 +17,7 @@ from log_foundry.context import (
     current_baggage_header,
     current_trace_context,
     current_traceparent,
+    reset_context,
 )
 from log_foundry.decorator import continue_trace, trace
 from log_foundry.worker import Health
@@ -107,6 +109,7 @@ __all__ = [
     "get_config",
     "health",
     "info",
+    "reset_context",
     "set_baggage",
     "shutdown",
     "trace",

{log_foundry-0.10.2.dev4 → log_foundry-0.10.2.dev5}/src/log_foundry/context.py

@@ -33,6 +33,7 @@ __all__ = [
     "pop_span",
     "push_baggage_scope",
     "push_span",
+    "reset_context",
     "set_baggage",
 ]
 
@@ -133,6 +134,38 @@ def pop_baggage_scope(token: contextvars.Token[dict[str, object]]) -> None:
         _baggage.set(old if isinstance(old, dict) else {})
 
 
+def reset_context() -> None:
+    """Clear baggage and any adopted trace context outright (SPEC-024 FR-003).
+
+    For the caller who uses the emitters **without** ``@trace``: the orphan path opens no span,
+    so there is no root-span exit to hang the release on, and both values would otherwise live
+    as long as the context does. A ``@trace`` user does not need this —
+    :func:`pop_baggage_scope` already runs at every root span's exit.
+
+    It is also the remedy for the one case that scope cannot reach: an adoption made outside a
+    span whose root span then runs in a child context, where the clear lands in the copy. Call
+    this in the context that made the adoption.
+
+    One function rather than two because the two values have the same lifetime and the same
+    failure mode, and a caller who wants one almost always wants the other.
+
+    Unlike the scope release this **clears** rather than restores — a process-level baggage
+    default set before any span is erased too, which is the point of an explicit reset. Safe
+    with nothing ever set, with no span open, and inside an open span. Never raises, like every
+    other entry point on this path (arch §4).
+
+    Prefer calling it **outside** a span. Inside one it does the obvious thing to the events
+    that follow, but SPEC-015 backfills ``span.start`` and ``span.end`` from the baggage live at
+    *close*, so a mid-span reset also empties the two boundary events — which describe the whole
+    span and carry ``duration_ms``/``status`` — of baggage that was live for most of it. That
+    span's exit then restores the baggage from before the span, as it always does.
+    """
+    # Cleared in the same order as `pop_baggage_scope`, for the reason given there: a stale
+    # trace id is wrong data, a stale baggage field is only stale.
+    _adopted.set(None)
+    _baggage.set({})
+
+
 # -- adopted inbound context (SPEC-014) --------------------------------------------------