log-foundry 0.10.2.dev40__tar.gz → 0.10.2.dev42__tar.gz

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev40
+Version: 0.10.2.dev42
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -396,6 +396,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `get_baggage()` | Current baggage as a `dict`. A shallow copy — rebinding a key does not reach the library, but a nested mutable value is shared. |
 | `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
@@ -465,14 +466,20 @@ undoing the erasure. It never raises.
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
 receives already-built, batched event dicts and knows nothing about spans or context:
 
-```python
-class Sink(Protocol):
-    def emit(self, batch: list[dict[str, object]]) -> None: ...
-    def close(self) -> None: ...
+```
+emit(batch: list[dict[str, object]]) -> None
+close() -> None
 ```
 
+Satisfy it **structurally** — any object with those two methods is a sink, and every sink shipped
+here is one. You do not need to inherit. If you prefer to, `from log_foundry import Sink` gives you
+the protocol to annotate against or subclass; both methods are abstract, so a subclass that
+misspells `emit` fails at construction rather than silently accepting every batch and delivering
+nothing.
+
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
-call falls back to `StdoutSink()`. Sinks are **not** re-exported at the top level — import each
+call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
+`SinkDeliveryError`, `SinkLosses` and `read_losses`; the **concrete sinks** are not, so import each
 from its own module, e.g. `from log_foundry.sinks.sqs import SQSSink`.
 
 A few conventions hold across every sink below:
@@ -728,11 +735,14 @@ loss-reporting apparatus is built on them:
   whole operation that assumes exclusivity. If it holds none, you need do nothing. The library
   cannot serialize this for you: it does not own the calling thread.
 
+- **The batch is borrowed, not given.** The list and the dicts in it may go to other sinks after
+  you — `MultiSink` hands the same objects to every child in turn — so copy before you redact or
+  reshape. A child that cleared the list in place left the next child with nothing, and no error
+  anywhere.
 - **Raise when you delivered none of the batch**, after your own retries are spent. That is the
   signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
   a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
-  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
-  propagates.
+  `log_foundry`) or any exception of your own — the contract is that *something* propagates.
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
@@ -756,7 +766,7 @@ separate from the transport one so a poll never waits on an in-flight send:
 
 ```python
 import threading
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry import SinkDeliveryError, SinkLosses
 
 class MySink:
     def __init__(self) -> None:
@@ -764,6 +774,7 @@ class MySink:
         self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
+        self.log_foundry_stop_signal: threading.Event | None = None  # optional; see below
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         if not batch:
@@ -799,6 +810,48 @@ class MySink:
 simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
 failed to deliver.
 
+`log_foundry_stop_signal` is optional in the same way, and is an attribute rather than a method.
+Declare it as a plain `threading.Event | None` initialised to `None` and the library assigns the
+worker's shutdown event to it; leave it out and you are simply never offered one. **Honour it in
+your retry backoff** — pass it to `Event.wait(timeout)` instead of calling `time.sleep`:
+
+```python
+        if self.log_foundry_stop_signal is not None:
+            self.log_foundry_stop_signal.wait(delay)   # returns early when shutdown starts
+        else:
+            time.sleep(delay)
+```
+
+There is one drain thread, so your backoff pauses *all* log delivery, and it is held across
+`shutdown()` — which joins that thread. A sink that sleeps through a 30-second backoff holds
+process exit for 30 seconds. The name is prefixed because the library assigns this attribute onto
+an object it does not own: a bare `stop_signal` would silently overwrite one you already had.
+
+If you write a **wrapper** sink, forward it to whatever actually holds the retry loop — a plain
+attribute on the wrapper is assigned, stops there, and the inner sink never sees it. Measured: a
+wrapper built from the leaf template above left an inner sink's 4-second backoff uninterrupted,
+`shutdown(timeout=30)` ran the full 30 seconds, `stopped_reason` read `"ShutdownTimeout"` and the
+sink was left open — against 0.00 s for the same sink configured directly. Use a property:
+
+```python
+class MyWrapper:
+    def __init__(self, inner) -> None:
+        self._inner = inner
+        self._stop_signal: threading.Event | None = None
+
+    @property
+    def log_foundry_stop_signal(self) -> threading.Event | None:
+        return self._stop_signal
+
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        self._inner.log_foundry_stop_signal = signal   # the one line that matters
+```
+
+Every wrapper shipped here — `MultiSink`, `FilteringSink`, `TransformSink`, `SyslogSink`,
+`LogstashSink`, `SentrySink` — does exactly this.
+
 ### Flushing and shutdown
 
 Delivery is off the hot path. When a span ends, its events are handed to a per-process

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/README.md

@@ -360,6 +360,7 @@ def handler(event, context):
 | `current_traceparent()` | This span as a W3C `traceparent` string, or `None` if no span is active. |
 | `current_trace_context()` | `(trace_id, span_id)`, for when moving two fields beats moving a string. |
 | `current_baggage_header()` | Current baggage in W3C `baggage` format (`""` when empty). |
+| `get_baggage()` | Current baggage as a `dict`. A shallow copy — rebinding a key does not reach the library, but a nested mutable value is shared. |
 | `reset_context()` | Clear baggage and any adopted context. `@trace` users do not need it. Never raises. |
 
 Details worth knowing:
@@ -429,14 +430,20 @@ undoing the erasure. It never raises.
 A **sink** is the swappable output transport — any object satisfying the `Sink` protocol. It
 receives already-built, batched event dicts and knows nothing about spans or context:
 
-```python
-class Sink(Protocol):
-    def emit(self, batch: list[dict[str, object]]) -> None: ...
-    def close(self) -> None: ...
+```
+emit(batch: list[dict[str, object]]) -> None
+close() -> None
 ```
 
+Satisfy it **structurally** — any object with those two methods is a sink, and every sink shipped
+here is one. You do not need to inherit. If you prefer to, `from log_foundry import Sink` gives you
+the protocol to annotate against or subclass; both methods are abstract, so a subclass that
+misspells `emit` fails at construction rather than silently accepting every batch and delivering
+nothing.
+
 Wire one up by passing an instance to `configure(sink=...)`; if you never do, the first decorated
-call falls back to `StdoutSink()`. Sinks are **not** re-exported at the top level — import each
+call falls back to `StdoutSink()`. The **protocol** is a top-level export, alongside
+`SinkDeliveryError`, `SinkLosses` and `read_losses`; the **concrete sinks** are not, so import each
 from its own module, e.g. `from log_foundry.sinks.sqs import SQSSink`.
 
 A few conventions hold across every sink below:
@@ -692,11 +699,14 @@ loss-reporting apparatus is built on them:
   whole operation that assumes exclusivity. If it holds none, you need do nothing. The library
   cannot serialize this for you: it does not own the calling thread.
 
+- **The batch is borrowed, not given.** The list and the dicts in it may go to other sinks after
+  you — `MultiSink` hands the same objects to every child in turn — so copy before you redact or
+  reshape. A child that cleared the list in place left the next child with nothing, and no error
+  anywhere.
 - **Raise when you delivered none of the batch**, after your own retries are spent. That is the
   signal the worker's bounded retry and `health().failed_batches` depend on, and the one case where
   a retry cannot duplicate anything: nothing landed downstream. Raise `SinkDeliveryError` (from
-  `log_foundry.sinks.base`) or any exception of your own — the contract is that *something*
-  propagates.
+  `log_foundry`) or any exception of your own — the contract is that *something* propagates.
 - **Do not raise when you delivered some of it.** The worker retries whole batches, so raising on a
   partial success re-delivers the records that already arrived, and duplicates downstream are worse
   than a counted loss.
@@ -720,7 +730,7 @@ separate from the transport one so a poll never waits on an in-flight send:
 
 ```python
 import threading
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry import SinkDeliveryError, SinkLosses
 
 class MySink:
     def __init__(self) -> None:
@@ -728,6 +738,7 @@ class MySink:
         self._closed = False
         self._lock = threading.Lock()          # transport state
         self._counter_lock = threading.Lock()  # counters only, never held across I/O
+        self.log_foundry_stop_signal: threading.Event | None = None  # optional; see below
 
     def emit(self, batch: list[dict[str, object]]) -> None:
         if not batch:
@@ -763,6 +774,48 @@ class MySink:
 simply contributes nothing to `health().sink`. `emit([])` must be a no-op: an empty batch has not
 failed to deliver.
 
+`log_foundry_stop_signal` is optional in the same way, and is an attribute rather than a method.
+Declare it as a plain `threading.Event | None` initialised to `None` and the library assigns the
+worker's shutdown event to it; leave it out and you are simply never offered one. **Honour it in
+your retry backoff** — pass it to `Event.wait(timeout)` instead of calling `time.sleep`:
+
+```python
+        if self.log_foundry_stop_signal is not None:
+            self.log_foundry_stop_signal.wait(delay)   # returns early when shutdown starts
+        else:
+            time.sleep(delay)
+```
+
+There is one drain thread, so your backoff pauses *all* log delivery, and it is held across
+`shutdown()` — which joins that thread. A sink that sleeps through a 30-second backoff holds
+process exit for 30 seconds. The name is prefixed because the library assigns this attribute onto
+an object it does not own: a bare `stop_signal` would silently overwrite one you already had.
+
+If you write a **wrapper** sink, forward it to whatever actually holds the retry loop — a plain
+attribute on the wrapper is assigned, stops there, and the inner sink never sees it. Measured: a
+wrapper built from the leaf template above left an inner sink's 4-second backoff uninterrupted,
+`shutdown(timeout=30)` ran the full 30 seconds, `stopped_reason` read `"ShutdownTimeout"` and the
+sink was left open — against 0.00 s for the same sink configured directly. Use a property:
+
+```python
+class MyWrapper:
+    def __init__(self, inner) -> None:
+        self._inner = inner
+        self._stop_signal: threading.Event | None = None
+
+    @property
+    def log_foundry_stop_signal(self) -> threading.Event | None:
+        return self._stop_signal
+
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
+        self._stop_signal = signal
+        self._inner.log_foundry_stop_signal = signal   # the one line that matters
+```
+
+Every wrapper shipped here — `MultiSink`, `FilteringSink`, `TransformSink`, `SyslogSink`,
+`LogstashSink`, `SentrySink` — does exactly this.
+
 ### Flushing and shutdown
 
 Delivery is off the hot path. When a span ends, its events are handed to a per-process

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/pyproject.toml

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

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/__init__.py

@@ -4,15 +4,16 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _dist_version
 
 from log_foundry.api import critical, debug, error, info, set_baggage, warning
-from log_foundry.config import configure, get_config
+from log_foundry.config import Config, configure, get_config
 from log_foundry.context import (
     current_baggage_header,
     current_trace_context,
     current_traceparent,
+    get_baggage,
     reset_context,
 )
 from log_foundry.decorator import continue_trace, trace
-from log_foundry.sinks.base import SinkDeliveryError, SinkLosses
+from log_foundry.sinks.base import Sink, SinkDeliveryError, SinkLosses, read_losses
 from log_foundry.worker import DEFAULT_SHUTDOWN_TIMEOUT, Health
 
 try:
@@ -156,7 +157,9 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
 
 __all__ = [
     "DEFAULT_SHUTDOWN_TIMEOUT",
+    "Config",
     "Health",
+    "Sink",
     "SinkDeliveryError",
     "SinkLosses",
     "__version__",
@@ -169,9 +172,11 @@ __all__ = [
     "debug",
     "error",
     "flush",
+    "get_baggage",
     "get_config",
     "health",
     "info",
+    "read_losses",
     "reset_context",
     "set_baggage",
     "shutdown",

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/_lifecycle.py

@@ -165,11 +165,12 @@ def offer_stop_signal(sink: Sink, stop: threading.Event) -> None:
       None.
 
     Raises:
-      None. A sink whose ``stop_signal`` is a read-only property, or whose ``__setattr__``
+      None. A sink whose ``log_foundry_stop_signal`` is a read-only property, or whose
+      ``__setattr__``
         objects, loses interruptibility rather than preventing the caller from proceeding.
     """
     try:
-        if hasattr(sink, "stop_signal"):
-            sink.stop_signal = stop
+        if hasattr(sink, "log_foundry_stop_signal"):
+            sink.log_foundry_stop_signal = stop
     except Exception as exc:
         _diag.absorbed("handing the sink its stop signal", exc, "its backoff stays uninterruptible")

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/api.py

@@ -72,7 +72,7 @@ def _log(level: str, message: str, echo: bool, fields: dict[str, object]) -> Non
       None. A logging call must never hand the application an exception from a destination
         it never chose to talk to; absorbed faults are reported through ``_diag``.
     """
-    baggage = context.get_baggage()
+    baggage = context._live_baggage()
     span = context.current_span()
     event: dict[str, object] | None = None
     if span is not None:

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/config.py

@@ -181,13 +181,20 @@ def _swap_live_sink(sink: Sink) -> None:
 
 
 def get_config() -> Config:
-    """Returns the current global config singleton.
+    """Returns the current global config, for reading.
+
+    **Mutating what this returns is unsupported and will raise from 1.0** (SPEC-034 FR-003).
+    Today it hands back the live singleton, so assigning to it retargets what the config
+    *reports* while every event continues to the sink the worker already captured, and assigning
+    a ceiling bypasses the validation :func:`configure` performs — ``max_value_bytes = 0`` is
+    accepted and empties every event it touches. Both measured. :func:`configure` is the only
+    supported route to a change.
 
     Args:
       None.
 
     Returns:
-      The process-wide :class:`Config`.
+      The process-wide :class:`Config`, to be treated as read-only.
 
     Raises:
       None.

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/context.py

@@ -96,18 +96,48 @@ def pop_span(token: contextvars.Token[tuple[Span, ...]]) -> None:
 
 
 def get_baggage() -> dict[str, object]:
-    """Returns the current trace's baggage, which must not be mutated in place.
+    """Returns a copy of the current trace's baggage.
 
     The trace's own keys are discarded when the enclosing root span closes, restoring the
     baggage in effect before it, so a later trace sees only a process-level default set
     before any span opened. With no span open at all nothing releases them and they
     accumulate for the life of the context; :func:`reset_context` is the release there.
 
+    It is a **shallow** copy (SPEC-034 FR-005). This became public at 1.0, and a public accessor
+    that hands out the live mapping documented as "do not mutate" is FR-003's ``get_config()``
+    defect under another name. Shallow rather than deep because :func:`set_baggage` accepts
+    arbitrary values: a deep copy would run user objects through ``copy.deepcopy`` inside a
+    getter that must never raise, which trades a narrow sharing bound for a wide new failure —
+    and the library never mutates a baggage value either, so the sharing is only reachable
+    through the caller's own object. The library's own hot path does not pay even for the
+    shallow copy: :func:`_live_baggage` is the internal read, for the reason FR-003 AC-6 gives.
+
+    Args:
+      None.
+
+    Returns:
+      A shallow copy of the baggage mapping. Rebinding a key does not affect the library; a
+        nested mutable value is shared, and mutating one *does* reach every later event.
+
+    Raises:
+      None.
+    """
+    return dict(_baggage.get())
+
+
+def _live_baggage() -> dict[str, object]:
+    """Returns the baggage mapping itself, for callers inside the package.
+
+    :func:`api._log` reads baggage once per event, so a copy here would allocate per event —
+    the cost FR-003 AC-6 measures and refuses on the config's own hot path. Callers must treat
+    the result as read-only; the freeze is a guarantee to the library's *users*, not one the
+    library needs against itself.
+
     Args:
       None.
 
     Returns:
-      The baggage mapping, to be treated as read-only.
+      The live baggage mapping.
 
     Raises:
       None.
@@ -300,7 +330,7 @@ def current_baggage_header() -> str:
     Raises:
       None.
     """
-    return format_baggage_header(get_baggage())
+    return format_baggage_header(_live_baggage())
 
 
 def format_baggage_header(baggage: dict[str, object]) -> str:

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/decorator.py

@@ -853,7 +853,7 @@ def _close_span(span: Span, status: str, exc: BaseException | None) -> None:
         guard.
     """
     span.events.append(end_event(span, status, exc))
-    backfill_baggage(span, context.get_baggage())
+    backfill_baggage(span, context._live_baggage())
     _flush(span)
 
 

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/_socket.py

@@ -133,7 +133,7 @@ class SocketTransport:
         self._sock: socket.socket | None = None
         self.failed = 0
         self._counter_lock = threading.Lock()
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self._lock = threading.Lock()
         self._closed = False
 
@@ -243,7 +243,7 @@ class SocketTransport:
             except OSError as err:
                 self._reset()
                 if attempt < self._max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += 1

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from abc import abstractmethod
 from typing import NamedTuple, Protocol, runtime_checkable
 
 __all__ = ["Sink", "SinkDeliveryError", "SinkLosses", "read_losses"]
@@ -58,6 +59,34 @@ class Sink(Protocol):
     sink written against the pre-SPEC-026 interface satisfying this one. :func:`read_losses` is
     the probe.
 
+    :meth:`emit` and :meth:`close` are ``@abstractmethod`` (SPEC-034 FR-005). A ``Protocol`` is
+    normally satisfied *structurally* and that is still how every shipped sink satisfies this
+    one — but making it a public export invites inheritance, and an incomplete subclass of a
+    protocol whose members have empty bodies instantiates happily and returns ``None`` from the
+    method it failed to define. Reproduced before the decorators were added: one typo
+    (``def emmit``) and three events were gone with ``flush()`` reporting ``True`` and every
+    counter at zero — the "sink the worker believes" failure this file exists to prevent.
+    ``mypy`` already refused it; only the runtime did not. Inheriting is still not required, and
+    ``isinstance`` remains structural.
+
+    A fourth is optional in the same way and is an attribute rather than a method:
+    ``log_foundry_stop_signal``. A sink that defines it — a plain
+    ``threading.Event | None``, initialised to ``None`` — is handed the worker's shutdown event
+    whenever the library takes ownership of it, and a sink that does not is simply never
+    offered one. **Honouring it is how a retrying sink stays interruptible** (SPEC-027): the
+    worker owns a single drain thread, so a sink's backoff is a global pause on log delivery
+    held across ``shutdown()``, which joins that thread. Pass it to ``sinks/_retry.wait`` — or
+    wait on it directly — rather than calling ``time.sleep``, or a shutdown cannot cut the
+    wait short and a slow destination holds process exit for the length of its own backoff.
+    A **wrapper** sink must forward it to whatever actually holds the retry loop; set on a
+    wrapper and stopped there, the signal reaches nothing.
+
+    The name is namespaced deliberately (SPEC-034 FR-006). The library assigns this attribute
+    onto an object it does not own, by ``hasattr`` probe, so a bare ``stop_signal`` — which is
+    what shipped before 1.0 — silently overwrote any attribute of that name a third-party sink
+    already used, with a ``threading.Event``. Reproduced. A prefixed name cannot collide by
+    accident, and the cost is one verbose attribute on the sinks that want interruptibility.
+
     "Safe to call during an emit" is a concurrency requirement once :meth:`emit` is (SPEC-028
     FR-003). The shipped sinks keep their loss counters under a **dedicated** lock, separate
     from whatever guards their transport: an increment is a read-modify-write that Python does
@@ -68,6 +97,7 @@ class Sink(Protocol):
     both, the order is always transport then counter, never the reverse.
     """
 
+    @abstractmethod
     def emit(self, batch: list[dict[str, object]]) -> None:
         """Ships a batch of serialized event dicts.
 
@@ -111,7 +141,11 @@ class Sink(Protocol):
         docstring and a test holds it to it.
 
         Args:
-          batch: The events to ship. ``emit([])`` is a no-op and never raises, since an empty
+          batch: The events to ship. **Borrowed, not given** — the list and the dicts inside it
+            may be handed to other sinks afterwards, which ``MultiSink`` does to every child in
+            turn, so mutating either in place silently changes or empties what a later sink
+            receives. Copy before reshaping or redacting. Reproduced: a child that cleared the
+            list left the next child with nothing and no error anywhere. ``emit([])`` is a no-op and never raises, since an empty
             batch has not failed to deliver — closed or not.
 
         Returns:
@@ -122,6 +156,7 @@ class Sink(Protocol):
         """
         ...
 
+    @abstractmethod
     def close(self) -> None:
         """Flushes and releases any resources.
 

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/clickhouse.py

@@ -83,7 +83,7 @@ class ClickHouseSink:
         self._table = valid_identifier(table)
         self._chunk_size = chunk_size
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self._closed = False
         self._lock = threading.Lock()
@@ -198,7 +198,7 @@ class ClickHouseSink:
                 return 1
             except Exception as err:
                 if attempt < self.max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += len(rows)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/eventhubs.py

@@ -64,7 +64,7 @@ class AzureEventHubsSink:
             )
         self.producer = producer
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self._counter_lock = threading.Lock()
@@ -201,7 +201,7 @@ class AzureEventHubsSink:
                 return 1
             except Exception as err:
                 if attempt < self.max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += len(event_batch)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/filtering.py

@@ -105,7 +105,7 @@ class FilteringSink:
         return True
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -124,8 +124,8 @@ class FilteringSink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to the inner sink.
 
         Args:
@@ -139,7 +139,7 @@ class FilteringSink:
         """
         self._stop_signal = signal
         try:
-            self._inner.stop_signal = signal  # type: ignore[attr-defined]
+            self._inner.log_foundry_stop_signal = signal  # type: ignore[attr-defined]
         except Exception as err:
             _diag.absorbed(
                 "handing the inner sink its stop signal",

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/firehose.py

@@ -69,7 +69,7 @@ class FirehoseSink:
         self.delivery_stream = delivery_stream
         self.client = client
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
@@ -224,7 +224,7 @@ class FirehoseSink:
             if not records:
                 return sent
             if attempt < self.max_retries:
-                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
             if attempt >= self.max_retries:
                 with self._counter_lock:
                     self.failed += len(records)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/http.py

@@ -132,7 +132,7 @@ class HTTPSink:
         self.gzip = gzip
         self.max_retries = max(max_retries, 0)
         self.max_retry_after = max_retry_after
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self._opener = opener if opener is not None else urllib.request.urlopen
         self.failed = 0
         self.dropped_oversized = 0
@@ -364,7 +364,7 @@ class HTTPSink:
         """
         server = clamp_server_delay(retry_after, self.max_retry_after)
         delay = server if server is not None else _BACKOFF_BASE * (2**attempt)
-        wait(delay, self.stop_signal)
+        wait(delay, self.log_foundry_stop_signal)
 
     def _abandon(self, reason: str) -> NoReturn:
         """Counts and logs a request abandoned past the retry bound, then raises (FR-012).

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/kinesis.py

@@ -78,7 +78,7 @@ class KinesisSink:
         self.client = client
         self.partition_key_field = partition_key_field
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self.dropped_unadjudicated = 0
@@ -231,7 +231,7 @@ class KinesisSink:
             if not records:
                 return sent
             if attempt < self.max_retries:
-                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
             if attempt >= self.max_retries:
                 with self._counter_lock:
                     self.failed += len(records)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/logstash.py

@@ -130,7 +130,7 @@ class LogstashSink:
             self._socket.close()
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -149,8 +149,8 @@ class LogstashSink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to the active backend.
 
         Args:
@@ -164,9 +164,9 @@ class LogstashSink:
         """
         self._stop_signal = signal
         if self._http is not None:
-            self._http.stop_signal = signal
+            self._http.log_foundry_stop_signal = signal
         elif self._socket is not None:
-            self._socket.stop_signal = signal
+            self._socket.log_foundry_stop_signal = signal
 
     @property
     def failed(self) -> int:

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/mongodb.py

@@ -71,7 +71,7 @@ class MongoDBSink:
         self._client = client
         self._collection = client[database][collection]
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self._closed = False
@@ -150,7 +150,7 @@ class MongoDBSink:
                         ) from None
                     return
                 if attempt < self.max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += len(documents)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/multi.py

@@ -97,7 +97,7 @@ class MultiSink:
             raise first_error
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -116,8 +116,8 @@ class MultiSink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to every child.
 
         Children are not probed with ``hasattr`` first: setting it on a child that never reads
@@ -135,7 +135,7 @@ class MultiSink:
         self._stop_signal = signal
         for sink in self._sinks:
             try:
-                sink.stop_signal = signal  # type: ignore[attr-defined]
+                sink.log_foundry_stop_signal = signal  # type: ignore[attr-defined]
             except Exception as err:
                 _diag.absorbed(
                     "handing a MultiSink child its stop signal",

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/postgres.py

@@ -67,7 +67,7 @@ class PostgresSink:
         self._table = valid_identifier(table)
         self._chunk_size = chunk_size
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self._closed = False
         self._lock = threading.Lock()
@@ -156,7 +156,7 @@ class PostgresSink:
             except Exception as err:
                 self._conn.rollback()
                 if attempt < self.max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += len(batch)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/rabbitmq.py

@@ -66,7 +66,7 @@ class RabbitMQSink:
         self._routing_key = routing_key
         self._url = url
         self._max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self._owns_connection = connection is None
         self._connection = connection if connection is not None else self._connect()
         self._channel: Any = None
@@ -181,7 +181,7 @@ class RabbitMQSink:
             except Exception as err:
                 self._reset()
                 if attempt < self._max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += 1

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/redis.py

@@ -59,7 +59,7 @@ class _RedisSink:
             client = redis.Redis.from_url(url) if url else redis.Redis()
         self.client = client
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self._counter_lock = threading.Lock()
         self._closed = False
@@ -118,7 +118,7 @@ class _RedisSink:
                 return
             except Exception as err:
                 if attempt < self.max_retries:
-                    wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                    wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
                     continue
                 with self._counter_lock:
                     self.failed += len(batch)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/sentry.py

@@ -48,7 +48,7 @@ class SentrySink:
         dsn: str | None = None,
         *,
         min_level: str = "ERROR",
-        sdk: Any = None,
+        client: Any = None,
         opener: Any = None,
         max_retries: int = 3,
     ) -> None:
@@ -58,7 +58,7 @@ class SentrySink:
           dsn: The Sentry DSN. It is required for the fallback, which needs it to know where to
             POST.
           min_level: The lowest level worth sending.
-          sdk: A ``sentry_sdk``-shaped object to use instead of importing one.
+          client: A ``sentry_sdk``-shaped object to use instead of importing one.
           opener: A ``urlopen``-shaped callable for the fallback, for tests.
           max_retries: Retries the fallback's HTTP transport makes.
 
@@ -74,10 +74,10 @@ class SentrySink:
         self.skipped = 0
         self.transport_errors = 0
         self._counter_lock = threading.Lock()
-        self._sdk = sdk if sdk is not None else _import_sdk()
+        self.client = client if client is not None else _import_sdk()
         self._http: HTTPSink | None = None
         self._auth_header = ""
-        if self._sdk is None:
+        if self.client is None:
             if dsn is None:
                 raise ValueError(
                     "SentrySink without sentry-sdk requires a dsn for the HTTP-envelope fallback"
@@ -143,7 +143,7 @@ class SentrySink:
             self._http.close()
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -162,8 +162,8 @@ class SentrySink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to the HTTP fallback, which is what waits.
 
         Args:
@@ -177,7 +177,7 @@ class SentrySink:
         """
         self._stop_signal = signal
         if self._http is not None:
-            self._http.stop_signal = signal
+            self._http.log_foundry_stop_signal = signal
 
     @property
     def failed(self) -> int:
@@ -236,8 +236,8 @@ class SentrySink:
             Only the exception type is ever written (arch §6).
         """
         try:
-            if self._sdk is not None:
-                self._sdk.capture_event(self._sentry_event(event))
+            if self.client is not None:
+                self.client.capture_event(self._sentry_event(event))
             else:
                 self._post_envelope(event)
         except SinkDeliveryError:

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/sns.py

@@ -61,7 +61,7 @@ class SNSSink:
         self.topic_arn = topic_arn
         self.client = client
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.failed = 0
         self.dropped_oversized = 0
         self._counter_lock = threading.Lock()
@@ -171,7 +171,7 @@ class SNSSink:
             failed_ids = {entry["Id"] for entry in failed}
             entries = [entry for entry in entries if entry["Id"] in failed_ids]
             if attempt < self.max_retries:
-                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
             if attempt >= self.max_retries:
                 with self._counter_lock:
                     self.failed += len(entries)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/sqs.py

@@ -103,8 +103,8 @@ class SQSSink:
     def __init__(
         self,
         queue_url: str,
-        client: Any = None,
         *,
+        client: Any = None,
         max_retries: int = 3,
         fifo: bool | None = None,
         message_group_id: GroupIdSource = None,
@@ -144,7 +144,7 @@ class SQSSink:
         self.queue_url = queue_url
         self.client = client
         self.max_retries = max(max_retries, 0)
-        self.stop_signal: threading.Event | None = None
+        self.log_foundry_stop_signal: threading.Event | None = None
         self.fifo = queue_url.endswith(".fifo") if fifo is None else fifo
         self.message_group_id = message_group_id
         self.message_deduplication_id = message_deduplication_id
@@ -376,7 +376,7 @@ class SQSSink:
                 return accepted, False
             entries = [entry for entry in entries if entry["Id"] in retryable_ids]
             if attempt < self.max_retries:
-                wait(_BACKOFF_BASE * (2**attempt), self.stop_signal)
+                wait(_BACKOFF_BASE * (2**attempt), self.log_foundry_stop_signal)
             if attempt >= self.max_retries:
                 with self._counter_lock:
                     self.failed += len(entries)

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/syslog.py

@@ -124,7 +124,7 @@ class SyslogSink:
         self._socket.close()
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -143,8 +143,8 @@ class SyslogSink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to the socket transport.
 
         Args:
@@ -157,7 +157,7 @@ class SyslogSink:
           None.
         """
         self._stop_signal = signal
-        self._socket.stop_signal = signal
+        self._socket.log_foundry_stop_signal = signal
 
     @property
     def failed(self) -> int:

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/sinks/transform.py

@@ -73,7 +73,7 @@ class TransformSink:
             self._inner.emit(transformed)
 
     @property
-    def stop_signal(self) -> threading.Event | None:
+    def log_foundry_stop_signal(self) -> threading.Event | None:
         """The worker's shutdown event, forwarded to whatever actually holds the retry loop.
 
         The worker sets this on the configured sink (SPEC-027 FR-002), and a wrapper is not
@@ -92,8 +92,8 @@ class TransformSink:
         """
         return self._stop_signal
 
-    @stop_signal.setter
-    def stop_signal(self, signal: threading.Event | None) -> None:
+    @log_foundry_stop_signal.setter
+    def log_foundry_stop_signal(self, signal: threading.Event | None) -> None:
         """Forwards the stop signal to the inner sink.
 
         Args:
@@ -107,7 +107,7 @@ class TransformSink:
         """
         self._stop_signal = signal
         try:
-            self._inner.stop_signal = signal  # type: ignore[attr-defined]
+            self._inner.log_foundry_stop_signal = signal  # type: ignore[attr-defined]
         except Exception as err:
             _diag.absorbed(
                 "handing the inner sink its stop signal",

{log_foundry-0.10.2.dev40 → log_foundry-0.10.2.dev42}/src/log_foundry/worker.py

@@ -251,7 +251,7 @@ class Worker:
           None.
 
         Raises:
-          None. A sink whose ``stop_signal`` is a read-only property, or whose
+          None. A sink whose ``log_foundry_stop_signal`` is a read-only property, or whose
             ``__setattr__`` objects, loses interruptibility rather than preventing the worker
             from starting.
         """