structguru 1.3.0__tar.gz → 1.4.0__tar.gz

{structguru-1.3.0 → structguru-1.4.0}/Cargo.lock

@@ -245,7 +245,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-core"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
  "fancy-regex",
  "fastrand",
@@ -257,7 +257,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-py"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
  "pyo3",
  "regex",

{structguru-1.3.0 → structguru-1.4.0}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/structguru-core", "crates/structguru-py"]
 resolver = "2"
 
 [workspace.package]
-version = "1.3.0"
+version = "1.4.0"
 edition = "2024"
 rust-version = "1.89"
 license = "MIT"

{structguru-1.3.0 → structguru-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structguru
-Version: 1.3.0
+Version: 1.4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -157,6 +157,7 @@ thresholds. Unknown names, booleans and negative integers raise `ValueError`.
 | `STRUCTGURU_AUTOCONFIGURE` | enabled | inverse of `STRUCTGURU_LEGACY` |
 
 New names win over their fallbacks; old names remain supported without warnings.
+Level variables accept a name or a non-negative integer threshold (`LOG_LEVEL=10`).
 Rate limits use `MAX` or `MAX/PERIOD`, with integer counts and seconds for the period.
 Autoconfiguration accepts `1/0`, `true/false`, `yes/no`, or `on/off` and controls import
 only. Set it to `0` before import to configure explicitly later. Invalid selected values
@@ -195,6 +196,17 @@ logger.info("User {user_id} logged in", user_id=42, ip="10.0.0.1")
 # user_id is consumed by formatting and not duplicated
 ```
 
+The message is formatted whenever positional or keyword arguments are passed, as
+`str.format` would (`"a }} b"` becomes `"a } b"`); `exc_info` and `stack_info` alone
+do not count, so `logger.exception("{{x}}")` logs `{{x}}` like `logger.error`. Fields
+named in a nested format spec (`"{x:{width}}"`) are consumed too. A placeholder that
+names a sensitive key — as the root (`{token}`) or an attribute or index
+(`{creds[password]}`) — is interpolated as `[REDACTED]`. A value interpolated whole
+(`{creds}`) is covered by `sensitive_patterns` only. The message is positional-only,
+so `message=` and `self=` are ordinary fields. A template that fails to format, or a
+message whose `str()` raises, is logged raw or as a placeholder with a one-shot
+`UserWarning`; logging calls do not raise for their arguments.
+
 ### Bound context
 
 ```python
@@ -240,6 +252,14 @@ logger.remove(handler_id)
 logger.remove()
 ```
 
+Handler ids are process-wide: any `Logger` can remove a sink that another one added.
+Removing an id that names no active sink raises `ValueError` (a non-integer raises
+`TypeError`), as in loguru; `remove()` without an id removes the sinks added through
+that logger and its `bind()`/`opt()` children. `level` accepts a name or a non-negative
+integer and raises `ValueError` for anything else, like `configure(level=...)`.
+A `logging.Handler` passed to `add()` keeps its own level and formatter: its formatter
+wraps the rendered line, only `level` gates what it receives, and `remove()` closes it.
+
 On Unix, new files created by either `logger.add(path)` or the native rotating
 file sink are owner-only (`0600`). Existing files retain their permissions.
 
@@ -302,6 +322,11 @@ update(
 )
 ```
 
+Patterns apply to the message, field names, and string values at any depth,
+and to integers by their decimal digits (a matching integer is emitted as the
+redacted string). If redaction makes two keys of one map equal, the record
+keeps one key with the last value.
+
 Patterns run on Rust's linear-time regex engine (no ReDoS), which rejects
 look-around and backreferences at `update()` time. Most look-behinds rewrite
 as capture groups — `(?<=password=)\S+` becomes `(password=)\S+` with
@@ -406,10 +431,13 @@ traceback still ship:
 - `<cycle: dict>` for a container that refers back to itself.
 - `<max depth exceeded>` beyond 64 levels of nesting.
 
-Integers outside the 64-bit range are written as JSON numbers, non-string
+Integers outside the 64-bit range are written as JSON numbers, `int` and
+`float` subclasses (such as `numpy.float64`) are written by value, non-string
 mapping keys are rendered as strings (`{200: 3}` becomes `{"200": 3}`), and
-unpaired surrogates in text become U+FFFD. Markers are redacted like any other
-string. The policy applies to native `logger` fields and to `extra=` fields
+each unpaired surrogate in text becomes one U+FFFD while a split surrogate pair
+decodes to its character. Keys that render to the same text never produce
+duplicate JSON keys: the later value wins at the earlier key's position.
+Markers are redacted like any other string. The policy applies to native `logger` fields and to `extra=` fields
 bridged from the standard library alike.
 
 ```python
@@ -457,15 +485,15 @@ Public API:
 Behavior notes:
 
 - **Overflow**: the default `maxsize=8192` uses `overflow="block"` to wait for queue space. Use `overflow="drop"` for drop-newest behavior with metrics and rate-limited warnings. `maxsize=0` explicitly opts into an unbounded queue.
-- **Redaction, level filtering, exceptions, and OpenTelemetry** injection are supported natively; redaction covers the message and all structured string values before rendering or Sentry export. `sensitive_keys` overrides the default redaction keys. Rust's linear-time regex engine rejects backreferences and look-around with `ValueError` at configuration time.
+- **Redaction, level filtering, exceptions, and OpenTelemetry** injection are supported natively; redaction covers the message, field names, string values, and integers at any depth before rendering or Sentry export, and message placeholders that name a sensitive key are interpolated as `[REDACTED]` (see the redaction API reference for the exact coverage). `sensitive_keys` overrides the default redaction keys. Rust's linear-time regex engine rejects backreferences and look-around with `ValueError` at configuration time.
 - **Sampling & rate limiting** (`sample_rate`, `rate_limit_max`, `rate_limit_period`) are applied as native pre-render filters — dropped records cost zero rendering. `sampled` and `rate_limited` counters are distinct from the transport `dropped` counter. `sample_max_level` restricts sampling to records at or below that level; more severe records always pass.
-- **Metric hooks** (`metric_processor=...`) invoke a structlog-style processor (e.g. `MetricProcessor`) for every *kept* record on the caller's thread, with `(None, method, {"event": message, **fields})`. Dropped records (level/sampling/rate-limit) never reach it; hook errors are swallowed.
-- **Fork/shutdown safe** — the writer is flushed on exit and respawned in forked children (gunicorn/celery prefork). Rotating-file writers sharing a path coordinate through an owner-only `.lock` sidecar; distributed hosts should still prefer stdout and an external collector.
-- **Structured exceptions** (`structured_exceptions=True`) render `type`, `message`, `module`, and frames as a dictionary, with optional redacted/truncated locals controlled by the `exception_*` options. Exception groups include nested members under `exceptions`, with the same frame limits and redaction. Traversal stops at ten nesting levels or 100 exception nodes; `exceptions_truncated` counts omitted direct children. Failed message conversions produce a marker instead of interrupting logging.
-- **`stack_info` is supported natively**: the stack is captured in Python and rendered in the same position as `StackInfoRenderer` (`stack` between `service` and `message`). Unlike the standard path, the stack ends at the *user's* calling frame (structguru-internal frames are skipped, the way structlog skips its own).
-- **Console mode** (`format="console"`): renders colored, human-readable lines instead of JSON — structguru's own stable dev format (`<timestamp> [<LEVEL>] <message>  k=v`), with ANSI colors by default on a TTY. Override with `colors=True/False`.
+- **Metric hooks** (`metric_processor=...`) invoke a structlog-style processor (e.g. `MetricProcessor`) for every *kept* record on the caller's thread, with `(None, method, {"event": message, **fields})`; the message stays in `"event"` even when a field has that name. Dropped records (level/sampling/rate-limit) never reach it; hook errors are swallowed.
+- **Fork/shutdown safe** — the writer is flushed on exit and respawned in forked children (gunicorn/celery prefork). The exit drain is registered when structguru is imported, so `atexit` handlers registered afterwards can still log. Rotating-file writers sharing a path coordinate through an owner-only `.lock` sidecar; distributed hosts should still prefer stdout and an external collector.
+- **Structured exceptions** (`structured_exceptions=True`) render `type`, `message`, `module`, and frames as a dictionary, with optional redacted/truncated locals controlled by the `exception_*` options. A local named like a sensitive key is redacted, and so is any value under a sensitive key inside a mapping, list, tuple, named tuple, set, dataclass with its generated `__repr__`, or `SimpleNamespace` (walked with bounded depth and size, cycle-safe); other objects' own `repr()` text is covered by `sensitive_patterns`, which see each local's full rendering before it is truncated to `exception_max_local_repr`. Exception groups include nested members under `exceptions`, with the same frame limits and redaction. Traversal stops at ten nesting levels or 100 exception nodes; `exceptions_truncated` counts omitted direct children. Failed message conversions produce a marker instead of interrupting logging.
+- **`stack_info` is supported natively**: the stack is captured in Python and rendered in the same position as `StackInfoRenderer` (`stack` between `service` and `message`). Unlike the standard path, the stack ends at the *user's* calling frame (frames of the `structguru` package are skipped, the way structlog skips its own).
+- **Console mode** (`format="console"`): renders colored, human-readable lines instead of JSON — structguru's own stable dev format (`<timestamp> [<LEVEL>] <message>  k=v`), with ANSI colors by default on a TTY. Override with `colors=True/False`. String values are double-quoted with `"` and `\` escaped, keys containing spaces, `=`, quotes, or backslashes are quoted, and control characters, U+2028/U+2029, and bidirectional controls are escaped everywhere, so a field key or value cannot forge another field or line. Floats use the JSON renderer's text (`1.0`, `1e+300`); the stack and a formatted `exception` follow as indented blocks.
 - **File sinks** (`file_path=...`): write to a rotating file natively. Defaults mirror `RotatingFileHandler` (50 MB, 5 backups); configure via `file_max_bytes`/`file_backup_count`. Set `also_stdout=True` to mirror output to both file and stdout (e.g. container + persistent log).
-- **Callable sinks** (`callable_sinks=[fn, ...]`): use a bounded queue (`callable_queue_maxsize=1024`). `overflow="block"` provides lossless backpressure; `overflow="drop"` reports `callable_dropped` metrics. Flush and lifecycle operations drain queued calls.
+- **Callable sinks** (`callable_sinks=[fn, ...]`): use a bounded queue (`callable_queue_maxsize=1024`). `overflow="block"` provides lossless backpressure; `overflow="drop"` reports `callable_dropped` metrics. One background thread at a time calls the sinks, in log order, also across reconfiguration; `logger.add()` never waits for the queue. Sink exceptions are counted in `callable_errors` with a rate-limited warning. Flush and lifecycle operations drain queued calls; a sink that makes no progress for 10 seconds is abandoned with a warning instead of blocking them.
 - **Sentry integration** (`sentry_processor=SentryProcessor(...)`): receives the already-redacted event and raw `exc_info` only for exception capture.
 - **Scope**: the native renderer covers JSON and console rendering, file/stdout/callable sinks, redaction, sampling/rate limiting, metrics, exceptions, and stack information. `logger.add()` sinks receive native and stdlib records.
 
@@ -473,9 +501,9 @@ Shutdown and reconfiguration drain records already accepted by the native queue.
 Calls still formatting or waiting for space may be rejected when their writer closes,
 even in block mode. `lifecycle_metrics()["rejected"]` counts these native deliveries
 without queue-full warnings and survives shutdown and configuration changes; forked
-children start at zero. Another destination, such as a synchronous stream, may already
-have received the event. Calls begun while logging is disabled are no-ops and are not
-counted. See the [lifecycle contract](docs/api/config.md#runtime-control) for details.
+children start at zero. A rejected record reaches no other destination either: the
+synchronous stream, callable sinks, and Sentry follow the native writer's outcome.
+Calls begun while logging is disabled are no-ops and are not counted. See the [lifecycle contract](docs/api/config.md#runtime-control) for details.
 
 ## Framework integrations
 
@@ -501,7 +529,7 @@ logging dictionary, application and launcher examples, and access-log options.
 from structguru.integrations.celery import setup_celery_logging
 
 setup_celery_logging(propagate_context=True, context_keys=["request_id"])
-# Binds task_id/task_name to context, propagates selected keys via headers
+# Binds task_id/task_name; propagates selected keys (redacted, JSON-safe) via headers
 ```
 
 ### Flask
@@ -622,7 +650,8 @@ bridge = install_stdlib_bridge_from_env()
 ## Requirements
 
 - Python 3.11+
-- The compiled Rust extension (shipped as abi3 wheels for Linux/macOS/Windows)
+- The compiled Rust extension (shipped as abi3 wheels for Linux/macOS/Windows, plus
+  free-threaded CPython 3.14t wheels for Linux x86_64, macOS arm64, and Windows x64)
 
 ## Documentation & Examples
 

{structguru-1.3.0 → structguru-1.4.0}/README.md

@@ -113,6 +113,7 @@ thresholds. Unknown names, booleans and negative integers raise `ValueError`.
 | `STRUCTGURU_AUTOCONFIGURE` | enabled | inverse of `STRUCTGURU_LEGACY` |
 
 New names win over their fallbacks; old names remain supported without warnings.
+Level variables accept a name or a non-negative integer threshold (`LOG_LEVEL=10`).
 Rate limits use `MAX` or `MAX/PERIOD`, with integer counts and seconds for the period.
 Autoconfiguration accepts `1/0`, `true/false`, `yes/no`, or `on/off` and controls import
 only. Set it to `0` before import to configure explicitly later. Invalid selected values
@@ -151,6 +152,17 @@ logger.info("User {user_id} logged in", user_id=42, ip="10.0.0.1")
 # user_id is consumed by formatting and not duplicated
 ```
 
+The message is formatted whenever positional or keyword arguments are passed, as
+`str.format` would (`"a }} b"` becomes `"a } b"`); `exc_info` and `stack_info` alone
+do not count, so `logger.exception("{{x}}")` logs `{{x}}` like `logger.error`. Fields
+named in a nested format spec (`"{x:{width}}"`) are consumed too. A placeholder that
+names a sensitive key — as the root (`{token}`) or an attribute or index
+(`{creds[password]}`) — is interpolated as `[REDACTED]`. A value interpolated whole
+(`{creds}`) is covered by `sensitive_patterns` only. The message is positional-only,
+so `message=` and `self=` are ordinary fields. A template that fails to format, or a
+message whose `str()` raises, is logged raw or as a placeholder with a one-shot
+`UserWarning`; logging calls do not raise for their arguments.
+
 ### Bound context
 
 ```python
@@ -196,6 +208,14 @@ logger.remove(handler_id)
 logger.remove()
 ```
 
+Handler ids are process-wide: any `Logger` can remove a sink that another one added.
+Removing an id that names no active sink raises `ValueError` (a non-integer raises
+`TypeError`), as in loguru; `remove()` without an id removes the sinks added through
+that logger and its `bind()`/`opt()` children. `level` accepts a name or a non-negative
+integer and raises `ValueError` for anything else, like `configure(level=...)`.
+A `logging.Handler` passed to `add()` keeps its own level and formatter: its formatter
+wraps the rendered line, only `level` gates what it receives, and `remove()` closes it.
+
 On Unix, new files created by either `logger.add(path)` or the native rotating
 file sink are owner-only (`0600`). Existing files retain their permissions.
 
@@ -258,6 +278,11 @@ update(
 )
 ```
 
+Patterns apply to the message, field names, and string values at any depth,
+and to integers by their decimal digits (a matching integer is emitted as the
+redacted string). If redaction makes two keys of one map equal, the record
+keeps one key with the last value.
+
 Patterns run on Rust's linear-time regex engine (no ReDoS), which rejects
 look-around and backreferences at `update()` time. Most look-behinds rewrite
 as capture groups — `(?<=password=)\S+` becomes `(password=)\S+` with
@@ -362,10 +387,13 @@ traceback still ship:
 - `<cycle: dict>` for a container that refers back to itself.
 - `<max depth exceeded>` beyond 64 levels of nesting.
 
-Integers outside the 64-bit range are written as JSON numbers, non-string
+Integers outside the 64-bit range are written as JSON numbers, `int` and
+`float` subclasses (such as `numpy.float64`) are written by value, non-string
 mapping keys are rendered as strings (`{200: 3}` becomes `{"200": 3}`), and
-unpaired surrogates in text become U+FFFD. Markers are redacted like any other
-string. The policy applies to native `logger` fields and to `extra=` fields
+each unpaired surrogate in text becomes one U+FFFD while a split surrogate pair
+decodes to its character. Keys that render to the same text never produce
+duplicate JSON keys: the later value wins at the earlier key's position.
+Markers are redacted like any other string. The policy applies to native `logger` fields and to `extra=` fields
 bridged from the standard library alike.
 
 ```python
@@ -413,15 +441,15 @@ Public API:
 Behavior notes:
 
 - **Overflow**: the default `maxsize=8192` uses `overflow="block"` to wait for queue space. Use `overflow="drop"` for drop-newest behavior with metrics and rate-limited warnings. `maxsize=0` explicitly opts into an unbounded queue.
-- **Redaction, level filtering, exceptions, and OpenTelemetry** injection are supported natively; redaction covers the message and all structured string values before rendering or Sentry export. `sensitive_keys` overrides the default redaction keys. Rust's linear-time regex engine rejects backreferences and look-around with `ValueError` at configuration time.
+- **Redaction, level filtering, exceptions, and OpenTelemetry** injection are supported natively; redaction covers the message, field names, string values, and integers at any depth before rendering or Sentry export, and message placeholders that name a sensitive key are interpolated as `[REDACTED]` (see the redaction API reference for the exact coverage). `sensitive_keys` overrides the default redaction keys. Rust's linear-time regex engine rejects backreferences and look-around with `ValueError` at configuration time.
 - **Sampling & rate limiting** (`sample_rate`, `rate_limit_max`, `rate_limit_period`) are applied as native pre-render filters — dropped records cost zero rendering. `sampled` and `rate_limited` counters are distinct from the transport `dropped` counter. `sample_max_level` restricts sampling to records at or below that level; more severe records always pass.
-- **Metric hooks** (`metric_processor=...`) invoke a structlog-style processor (e.g. `MetricProcessor`) for every *kept* record on the caller's thread, with `(None, method, {"event": message, **fields})`. Dropped records (level/sampling/rate-limit) never reach it; hook errors are swallowed.
-- **Fork/shutdown safe** — the writer is flushed on exit and respawned in forked children (gunicorn/celery prefork). Rotating-file writers sharing a path coordinate through an owner-only `.lock` sidecar; distributed hosts should still prefer stdout and an external collector.
-- **Structured exceptions** (`structured_exceptions=True`) render `type`, `message`, `module`, and frames as a dictionary, with optional redacted/truncated locals controlled by the `exception_*` options. Exception groups include nested members under `exceptions`, with the same frame limits and redaction. Traversal stops at ten nesting levels or 100 exception nodes; `exceptions_truncated` counts omitted direct children. Failed message conversions produce a marker instead of interrupting logging.
-- **`stack_info` is supported natively**: the stack is captured in Python and rendered in the same position as `StackInfoRenderer` (`stack` between `service` and `message`). Unlike the standard path, the stack ends at the *user's* calling frame (structguru-internal frames are skipped, the way structlog skips its own).
-- **Console mode** (`format="console"`): renders colored, human-readable lines instead of JSON — structguru's own stable dev format (`<timestamp> [<LEVEL>] <message>  k=v`), with ANSI colors by default on a TTY. Override with `colors=True/False`.
+- **Metric hooks** (`metric_processor=...`) invoke a structlog-style processor (e.g. `MetricProcessor`) for every *kept* record on the caller's thread, with `(None, method, {"event": message, **fields})`; the message stays in `"event"` even when a field has that name. Dropped records (level/sampling/rate-limit) never reach it; hook errors are swallowed.
+- **Fork/shutdown safe** — the writer is flushed on exit and respawned in forked children (gunicorn/celery prefork). The exit drain is registered when structguru is imported, so `atexit` handlers registered afterwards can still log. Rotating-file writers sharing a path coordinate through an owner-only `.lock` sidecar; distributed hosts should still prefer stdout and an external collector.
+- **Structured exceptions** (`structured_exceptions=True`) render `type`, `message`, `module`, and frames as a dictionary, with optional redacted/truncated locals controlled by the `exception_*` options. A local named like a sensitive key is redacted, and so is any value under a sensitive key inside a mapping, list, tuple, named tuple, set, dataclass with its generated `__repr__`, or `SimpleNamespace` (walked with bounded depth and size, cycle-safe); other objects' own `repr()` text is covered by `sensitive_patterns`, which see each local's full rendering before it is truncated to `exception_max_local_repr`. Exception groups include nested members under `exceptions`, with the same frame limits and redaction. Traversal stops at ten nesting levels or 100 exception nodes; `exceptions_truncated` counts omitted direct children. Failed message conversions produce a marker instead of interrupting logging.
+- **`stack_info` is supported natively**: the stack is captured in Python and rendered in the same position as `StackInfoRenderer` (`stack` between `service` and `message`). Unlike the standard path, the stack ends at the *user's* calling frame (frames of the `structguru` package are skipped, the way structlog skips its own).
+- **Console mode** (`format="console"`): renders colored, human-readable lines instead of JSON — structguru's own stable dev format (`<timestamp> [<LEVEL>] <message>  k=v`), with ANSI colors by default on a TTY. Override with `colors=True/False`. String values are double-quoted with `"` and `\` escaped, keys containing spaces, `=`, quotes, or backslashes are quoted, and control characters, U+2028/U+2029, and bidirectional controls are escaped everywhere, so a field key or value cannot forge another field or line. Floats use the JSON renderer's text (`1.0`, `1e+300`); the stack and a formatted `exception` follow as indented blocks.
 - **File sinks** (`file_path=...`): write to a rotating file natively. Defaults mirror `RotatingFileHandler` (50 MB, 5 backups); configure via `file_max_bytes`/`file_backup_count`. Set `also_stdout=True` to mirror output to both file and stdout (e.g. container + persistent log).
-- **Callable sinks** (`callable_sinks=[fn, ...]`): use a bounded queue (`callable_queue_maxsize=1024`). `overflow="block"` provides lossless backpressure; `overflow="drop"` reports `callable_dropped` metrics. Flush and lifecycle operations drain queued calls.
+- **Callable sinks** (`callable_sinks=[fn, ...]`): use a bounded queue (`callable_queue_maxsize=1024`). `overflow="block"` provides lossless backpressure; `overflow="drop"` reports `callable_dropped` metrics. One background thread at a time calls the sinks, in log order, also across reconfiguration; `logger.add()` never waits for the queue. Sink exceptions are counted in `callable_errors` with a rate-limited warning. Flush and lifecycle operations drain queued calls; a sink that makes no progress for 10 seconds is abandoned with a warning instead of blocking them.
 - **Sentry integration** (`sentry_processor=SentryProcessor(...)`): receives the already-redacted event and raw `exc_info` only for exception capture.
 - **Scope**: the native renderer covers JSON and console rendering, file/stdout/callable sinks, redaction, sampling/rate limiting, metrics, exceptions, and stack information. `logger.add()` sinks receive native and stdlib records.
 
@@ -429,9 +457,9 @@ Shutdown and reconfiguration drain records already accepted by the native queue.
 Calls still formatting or waiting for space may be rejected when their writer closes,
 even in block mode. `lifecycle_metrics()["rejected"]` counts these native deliveries
 without queue-full warnings and survives shutdown and configuration changes; forked
-children start at zero. Another destination, such as a synchronous stream, may already
-have received the event. Calls begun while logging is disabled are no-ops and are not
-counted. See the [lifecycle contract](docs/api/config.md#runtime-control) for details.
+children start at zero. A rejected record reaches no other destination either: the
+synchronous stream, callable sinks, and Sentry follow the native writer's outcome.
+Calls begun while logging is disabled are no-ops and are not counted. See the [lifecycle contract](docs/api/config.md#runtime-control) for details.
 
 ## Framework integrations
 
@@ -457,7 +485,7 @@ logging dictionary, application and launcher examples, and access-log options.
 from structguru.integrations.celery import setup_celery_logging
 
 setup_celery_logging(propagate_context=True, context_keys=["request_id"])
-# Binds task_id/task_name to context, propagates selected keys via headers
+# Binds task_id/task_name; propagates selected keys (redacted, JSON-safe) via headers
 ```
 
 ### Flask
@@ -578,7 +606,8 @@ bridge = install_stdlib_bridge_from_env()
 ## Requirements
 
 - Python 3.11+
-- The compiled Rust extension (shipped as abi3 wheels for Linux/macOS/Windows)
+- The compiled Rust extension (shipped as abi3 wheels for Linux/macOS/Windows, plus
+  free-threaded CPython 3.14t wheels for Linux x86_64, macOS arm64, and Windows x64)
 
 ## Documentation & Examples
 

structguru-1.4.0/crates/structguru-core/src/clock.rs

@@ -0,0 +1,113 @@
+//! Timestamp generation for the native render path.
+//!
+//! Produces an ISO-8601 UTC timestamp matching structlog's
+//! `TimeStamper(fmt="iso", utc=True)` output, e.g. `2026-07-08T16:19:24.616660Z`.
+//!
+//! The whole-second prefix (`YYYY-MM-DDTHH:MM:SS`) is cached per thread and only
+//! re-rendered when the second rolls over; the microsecond suffix is appended
+//! cheaply on every call. This keeps the calendar breakdown off the hot path
+//! (architecture §5/§14).
+
+use std::cell::RefCell;
+
+use time::OffsetDateTime;
+use time::macros::format_description;
+
+thread_local! {
+    // (unix_second, "YYYY-MM-DDTHH:MM:SS")
+    static PREFIX_CACHE: RefCell<(i64, String)> = const { RefCell::new((i64::MIN, String::new())) };
+}
+
+/// Current time as an ISO-8601 UTC string with microsecond precision + `Z`.
+pub fn now_iso8601() -> String {
+    let now = OffsetDateTime::now_utc();
+    let secs = now.unix_timestamp();
+    let micros = now.microsecond(); // 0..1_000_000
+
+    PREFIX_CACHE.with(|cell| {
+        let mut cache = cell.borrow_mut();
+        if cache.0 != secs {
+            let fmt = format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");
+            cache.1 = now.format(&fmt).unwrap_or_default();
+            cache.0 = secs;
+        }
+        format!("{}.{:06}Z", cache.1, micros)
+    })
+}
+
+/// Unix seconds bounding years 1 through 9999, the range of Python's `datetime`.
+const UNIX_SECONDS_RANGE: std::ops::Range<f64> = -62_135_596_800.0..253_402_300_800.0;
+
+/// `seconds` since the Unix epoch, as `time.time()` and `LogRecord.created`
+/// give them, in the [`now_iso8601`] format; `None` when the value is not
+/// finite or falls outside years 1 through 9999.
+///
+/// The fraction rounds to the nearest microsecond, ties to even, the way
+/// `datetime.fromtimestamp` rounds it.
+pub fn unix_to_iso8601(seconds: f64) -> Option<String> {
+    if !UNIX_SECONDS_RANGE.contains(&seconds) {
+        return None;
+    }
+    let whole = seconds.floor();
+    // `seconds - whole` is exact, so this rounds only once, like CPython.
+    let micros = ((seconds - whole) * 1_000_000.0).round_ties_even();
+    let (whole, micros) = if micros >= 1_000_000.0 {
+        (whole + 1.0, 0)
+    } else {
+        (whole, micros as u32)
+    };
+    let datetime = OffsetDateTime::from_unix_timestamp(whole as i64).ok()?;
+    let fmt = format_description!("[year]-[month]-[day]T[hour]:[minute]:[second]");
+    Some(format!("{}.{micros:06}Z", datetime.format(&fmt).ok()?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{now_iso8601, unix_to_iso8601};
+
+    #[test]
+    fn produces_iso8601_microsecond_utc() {
+        let ts = now_iso8601();
+        // e.g. 2026-07-08T16:19:24.616660Z
+        assert_eq!(ts.len(), 27, "unexpected timestamp: {ts}");
+        assert!(ts.ends_with('Z'));
+        assert_eq!(&ts[4..5], "-");
+        assert_eq!(&ts[10..11], "T");
+        assert_eq!(&ts[19..20], ".");
+    }
+
+    #[test]
+    fn formats_unix_seconds_like_datetime_fromtimestamp() {
+        let cases = [
+            (0.0, "1970-01-01T00:00:00.000000Z"),
+            (1_000_000_000.123456, "2001-09-09T01:46:40.123456Z"),
+            // Rounds to the nearest microsecond, carrying into the second.
+            (1_700_000_000.999_999_6, "2023-11-14T22:13:21.000000Z"),
+            // A tie rounds to even: 1/128 s is 7812.5 us.
+            (0.0078125, "1970-01-01T00:00:00.007812Z"),
+            (-1.5, "1969-12-31T23:59:58.500000Z"),
+            (-62_135_596_800.0, "0001-01-01T00:00:00.000000Z"),
+        ];
+        for (seconds, expected) in cases {
+            assert_eq!(
+                unix_to_iso8601(seconds).as_deref(),
+                Some(expected),
+                "{seconds}"
+            );
+        }
+    }
+
+    #[test]
+    fn rejects_unrepresentable_unix_seconds() {
+        for seconds in [
+            f64::NAN,
+            f64::INFINITY,
+            f64::NEG_INFINITY,
+            1e20,
+            -62_135_596_801.0,
+            253_402_300_800.0,
+        ] {
+            assert_eq!(unix_to_iso8601(seconds), None, "{seconds}");
+        }
+    }
+}

{structguru-1.3.0 → structguru-1.4.0}/crates/structguru-core/src/filter.rs

@@ -18,23 +18,26 @@ pub enum Decision {
 /// A pre-render filter deciding whether a record should be rendered.
 pub trait RecordFilter: Send + Sync {
     /// Inspect `key` (the rate-limit grouping key, usually the formatted message)
-    /// and `level` (the canonical method name) and return `Keep` or `Drop`.
-    fn allow(&self, key: &str, level: &str) -> Decision;
+    /// and `level` (the record's numeric level, as in `logging`) and return
+    /// `Keep` or `Drop`.
+    fn allow(&self, key: &str, level: u32) -> Decision;
 }
 
 /// Numeric level for a method name; unknown names rank as `info`.
-fn method_level_num(method: &str) -> u8 {
-    crate::level_number(method).unwrap_or(20)
+pub fn method_level_number(method: &str) -> u32 {
+    u32::from(crate::level_number(method).unwrap_or(20))
 }
 
 /// Probabilistic sampler: keeps a record with probability `rate`.
 ///
 /// With `max_level_num` set, only records at or below that level are sampled;
 /// more severe records always pass — the native analog of wrapping
-/// `SamplingProcessor` in `ConditionalProcessor(max_level=...)`.
+/// `SamplingProcessor` in `ConditionalProcessor(max_level=...)`. Levels
+/// compare by number, so a custom stdlib level between two named ones ranks
+/// by its own value.
 pub struct Sampler {
     rate: f64,
-    max_level_num: Option<u8>,
+    max_level_num: Option<u32>,
 }
 
 impl Sampler {
@@ -43,15 +46,15 @@ impl Sampler {
     pub fn new(rate: f64, max_level: Option<&str>) -> Self {
         Self {
             rate: rate.clamp(0.0, 1.0),
-            max_level_num: max_level.map(method_level_num),
+            max_level_num: max_level.map(method_level_number),
         }
     }
 }
 
 impl RecordFilter for Sampler {
-    fn allow(&self, _key: &str, level: &str) -> Decision {
+    fn allow(&self, _key: &str, level: u32) -> Decision {
         if let Some(max) = self.max_level_num
-            && method_level_num(level) > max
+            && level > max
         {
             return Decision::Keep;
         }
@@ -201,7 +204,7 @@ fn evict_least_recent(state: &mut RateLimiterState, keep: usize) {
 }
 
 impl RecordFilter for RateLimiter {
-    fn allow(&self, key: &str, _level: &str) -> Decision {
+    fn allow(&self, key: &str, _level: u32) -> Decision {
         self.allow_key(key, Instant::now())
     }
 }
@@ -254,8 +257,9 @@ impl Pipeline {
         }
     }
 
-    /// Returns `false` when any stage drops the record.
-    pub fn allow(&self, key: &str, level: &str) -> bool {
+    /// Returns `false` when any stage drops the record. `level` is the
+    /// record's numeric level; see [`method_level_number`] for method names.
+    pub fn allow(&self, key: &str, level: u32) -> bool {
         for stage in &self.stages {
             let (decision, sampled, rate_limited) = match stage {
                 Stage::Sampler(f) => {
@@ -300,7 +304,7 @@ mod tests {
     fn sampler_rate_zero_drops_all() {
         let s = Sampler::new(0.0, None);
         for _ in 0..100 {
-            assert_eq!(s.allow("k", "info"), Decision::Drop);
+            assert_eq!(s.allow("k", 20), Decision::Drop);
         }
     }
 
@@ -308,7 +312,7 @@ mod tests {
     fn sampler_rate_one_keeps_all() {
         let s = Sampler::new(1.0, None);
         for _ in 0..100 {
-            assert_eq!(s.allow("k", "info"), Decision::Keep);
+            assert_eq!(s.allow("k", 20), Decision::Keep);
         }
     }
 
@@ -318,7 +322,7 @@ mod tests {
         let s = Sampler::new(0.5, None);
         let mut kept = 0;
         for _ in 0..1000 {
-            if s.allow("k", "info") == Decision::Keep {
+            if s.allow("k", 20) == Decision::Keep {
                 kept += 1;
             }
         }
@@ -329,20 +333,45 @@ mod tests {
     fn sampler_max_level_gates_sampling_to_low_levels() {
         // rate=0 would drop everything, but only records <= INFO are sampled.
         let s = Sampler::new(0.0, Some("info"));
-        assert_eq!(s.allow("k", "debug"), Decision::Drop);
-        assert_eq!(s.allow("k", "info"), Decision::Drop);
-        assert_eq!(s.allow("k", "success"), Decision::Drop);
-        assert_eq!(s.allow("k", "warning"), Decision::Keep);
-        assert_eq!(s.allow("k", "error"), Decision::Keep);
-        assert_eq!(s.allow("k", "critical"), Decision::Keep);
+        for (method, expected) in [
+            ("debug", Decision::Drop),
+            ("info", Decision::Drop),
+            ("success", Decision::Drop),
+            ("warning", Decision::Keep),
+            ("error", Decision::Keep),
+            ("critical", Decision::Keep),
+        ] {
+            assert_eq!(
+                s.allow("k", method_level_number(method)),
+                expected,
+                "{method}"
+            );
+        }
+    }
+
+    #[test]
+    fn sampler_max_level_ranks_custom_levels_by_number() {
+        // A stdlib level between INFO (20) and WARNING (30) is more severe
+        // than INFO, so it is never sampled.
+        let s = Sampler::new(0.0, Some("info"));
+        assert_eq!(s.allow("k", 19), Decision::Drop);
+        assert_eq!(s.allow("k", 20), Decision::Drop);
+        assert_eq!(s.allow("k", 21), Decision::Keep);
+        assert_eq!(s.allow("k", 25), Decision::Keep);
+    }
+
+    #[test]
+    fn unknown_method_names_rank_as_info() {
+        assert_eq!(method_level_number("notice"), 20);
+        assert_eq!(method_level_number("WARN"), 30);
     }
 
     #[test]
     fn pipeline_level_gated_sampler_counts_only_gated_drops() {
         let p = Pipeline::new(0.0, Some("debug"), None, Duration::from_secs(60));
-        assert!(!p.allow("k", "debug"));
-        assert!(p.allow("k", "info"));
-        assert!(p.allow("k", "error"));
+        assert!(!p.allow("k", 10));
+        assert!(p.allow("k", 20));
+        assert!(p.allow("k", 40));
         let stats = p.stats();
         assert_eq!(stats.sampled, 1);
     }
@@ -411,7 +440,7 @@ mod tests {
         let p = Pipeline::new(1.0, None, None, Duration::from_secs(60));
         assert!(p.is_empty());
         for _ in 0..10 {
-            assert!(p.allow("k", "info"));
+            assert!(p.allow("k", 20));
         }
         let stats = p.stats();
         assert_eq!(stats.sampled, 0);
@@ -422,7 +451,7 @@ mod tests {
     fn pipeline_sampler_only_counts_sampled() {
         let p = Pipeline::new(0.0, None, None, Duration::from_secs(60));
         for _ in 0..5 {
-            assert!(!p.allow("k", "info"));
+            assert!(!p.allow("k", 20));
         }
         let stats = p.stats();
         assert_eq!(stats.sampled, 5);
@@ -432,9 +461,9 @@ mod tests {
     #[test]
     fn pipeline_rate_limiter_only_counts_rate_limited() {
         let p = Pipeline::new(1.0, None, Some(2), Duration::from_secs(60));
-        assert!(p.allow("k", "info"));
-        assert!(p.allow("k", "info"));
-        assert!(!p.allow("k", "info"));
+        assert!(p.allow("k", 20));
+        assert!(p.allow("k", 20));
+        assert!(!p.allow("k", 20));
         let stats = p.stats();
         assert_eq!(stats.sampled, 0);
         assert_eq!(stats.rate_limited, 1);
@@ -445,7 +474,7 @@ mod tests {
         // rate=0 drops everything; the rate limiter never runs, so its counter stays 0.
         let p = Pipeline::new(0.0, None, Some(2), Duration::from_secs(60));
         for _ in 0..10 {
-            assert!(!p.allow("k", "info"));
+            assert!(!p.allow("k", 20));
         }
         let stats = p.stats();
         assert_eq!(stats.sampled, 10);
@@ -456,9 +485,9 @@ mod tests {
     fn pipeline_sampler_then_rate_limiter_both_count() {
         // rate=1 so the sampler always keeps; the rate limiter governs drops.
         let p = Pipeline::new(1.0, None, Some(1), Duration::from_secs(60));
-        assert!(p.allow("alpha", "info"));
-        assert!(!p.allow("alpha", "info"));
-        assert!(p.allow("beta", "info"));
+        assert!(p.allow("alpha", 20));
+        assert!(!p.allow("alpha", 20));
+        assert!(p.allow("beta", 20));
         let stats = p.stats();
         assert_eq!(stats.sampled, 0);
         assert_eq!(stats.rate_limited, 1);

{structguru-1.3.0 → structguru-1.4.0}/crates/structguru-core/src/lib.rs

@@ -9,13 +9,15 @@ mod render;
 mod value;
 mod worker;
 
-pub use clock::now_iso8601;
-pub use filter::{Decision, FilterStats, Pipeline, RateLimiter, RecordFilter, Sampler};
+pub use clock::{now_iso8601, unix_to_iso8601};
+pub use filter::{
+    Decision, FilterStats, Pipeline, RateLimiter, RecordFilter, Sampler, method_level_number,
+};
 pub use render::{DEFAULT_SENSITIVE_KEYS, RedactionPattern, render_line, render_line_console};
-pub use value::{Value, ValueStats};
+pub use value::{Value, ValueStats, collapse_duplicate_keys};
 pub use worker::{
-    EnqueueError, MemorySink, MemorySinkHandle, MultiSink, RotatingFileSink, SinkError, StringSink,
-    StringWriter, WorkerMetrics, WriteSink,
+    EnqueueError, MemorySink, MemorySinkHandle, MultiSink, RotatingFileSink, SinkError, StdoutSink,
+    StringSink, StringWriter, WorkerMetrics, WriteSink,
 };
 
 /// Return the Rust core crate version.