structguru 1.2.3__tar.gz → 1.3.0__tar.gz

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

@@ -34,9 +34,9 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "fancy-regex"
-version = "0.19.0"
+version = "0.19.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "476de73bddf2ef8490aa4ee8f1cf40b430bf1d56c48c22080e5186952cd580e6"
+checksum = "d301f5bf187b3c295fce6468d3875037a0bccc5f6b151c63cac2f85babf21912"
 dependencies = [
  "bit-set",
  "regex-automata",
@@ -227,7 +227,7 @@ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 3.0.4",
+ "syn 3.0.6",
 ]
 
 [[package]]
@@ -245,7 +245,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-core"
-version = "1.2.3"
+version = "1.3.0"
 dependencies = [
  "fancy-regex",
  "fastrand",
@@ -257,7 +257,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-py"
-version = "1.2.3"
+version = "1.3.0"
 dependencies = [
  "pyo3",
  "regex",
@@ -277,9 +277,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "3.0.4"
+version = "3.0.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -324,9 +324,9 @@ dependencies = [
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.24"
+version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
 
 [[package]]
 name = "zmij"

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structguru
-Version: 1.2.3
+Version: 1.3.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -98,7 +98,7 @@ Available extras: `otel`, `celery`, `flask`, `django`, `sqlalchemy`, `grpc`,
 ## Quick start
 
 ```python
-from structguru import configure, logger
+from structguru import Logger, configure, logger
 
 # Configure once at startup
 configure(service="myapp", level="DEBUG", format="json")
@@ -106,8 +106,66 @@ configure(service="myapp", level="DEBUG", format="json")
 # Use anywhere
 logger.info("Hello {name}", name="world")
 # → {"logger":"...","level":"INFO","severity":6,"timestamp":"...","service":"myapp","message":"Hello world"}
+
+# Or choose an explicit module name
+log = Logger(name=__name__)
 ```
 
+## Configuration
+
+Call `configure()` once at startup. Each call replaces the previous configuration:
+explicit keywords override environment values, which override built-in defaults.
+Use `update()` to retain existing options while changing selected ones:
+
+```python
+from structguru import Settings, configure, get_config, update
+
+configure(service="checkout", sensitive_patterns=[r"token=\w+"])
+update(otel=True, structured_exceptions=True)  # retains service and redaction
+current = get_config()  # Settings, or None after shutdown()
+
+# Applications can load a mapping themselves; no files are read automatically.
+settings = Settings.from_mapping({"service": "checkout", "level": "DEBUG"})
+configure(settings)  # uses this object instead of environment values
+```
+
+`Settings.from_env()` resolves environment values without applying them; pass a mapping
+instead of using the process environment when testing. `Settings` validates Python
+values and freezes collections. Native regex compilation and file access are checked
+when configuring; failure leaves the previous runtime active. Explicit keywords,
+including `None` and built-in default values, win over the selected base.
+
+`update()` never rereads the environment and requires an active runtime. An empty update
+does nothing. Level-only updates and `set_level()` preserve queues and rate-limit state;
+other updates rebuild writers and reset filter state. Snapshots describe configured
+options, not buffered records, counters, stdlib bridge state, or `logger.add()` sinks.
+Those registered sinks survive reconfiguration. Streams and callbacks retain their identity.
+
+Levels accept case-insensitive names (including `NOTSET`) or non-negative integer
+thresholds. Unknown names, booleans and negative integers raise `ValueError`.
+
+### Environment configuration
+
+| Variable | Default | Compatibility fallback |
+|---|---|---|
+| `STRUCTGURU_SERVICE` | `app` | — |
+| `STRUCTGURU_LEVEL` | `INFO` | `LOG_LEVEL` |
+| `STRUCTGURU_TARGET` | `stdout` | `STRUCTGURU_NATIVE_TARGET` |
+| `STRUCTGURU_FORMAT` | `json` | — |
+| `STRUCTGURU_SAMPLE_RATE` | `1.0` | `STRUCTGURU_NATIVE_SAMPLE_RATE` |
+| `STRUCTGURU_RATE_LIMIT` | disabled; period defaults to 60 seconds | `STRUCTGURU_NATIVE_RATE_LIMIT` |
+| `STRUCTGURU_AUTOCONFIGURE` | enabled | inverse of `STRUCTGURU_LEGACY` |
+
+New names win over their fallbacks; old names remain supported without warnings.
+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
+fail validation; an invalid import-time value must be corrected or autoconfiguration
+disabled before the application can call `configure()`.
+
+File output, redaction, exceptions and other settings currently use Python configuration.
+The stdlib bridge retains its separate `STRUCTGURU_STDLIB_*` options and explicit installer.
+
 ## Usage
 
 ### Log levels
@@ -191,6 +249,16 @@ that path. Install the [stdlib bridge](#stdlib-bridge) to receive them rendered
 and redacted instead — while it is installed the raw delivery is suspended, so a
 sink never sees the same record twice.
 
+Logs emitted inside a sink callback, whether it received a native record or a
+raw stdlib one, reach the native writer but skip callable and `logger.add()`
+sinks, preventing recursive delivery and worker deadlocks. Outside callbacks,
+`logger.remove()` waits for producers that already selected the removed sink
+and for raw stdlib deliveries in progress. Lifecycle calls inside a callback,
+including a stdlib handler's `emit()` on the raw path, cannot wait for the
+worker; previously selected deliveries finish as that worker drains.
+For native file/stdout mirroring, `writer_metrics()["sink_errors"]` includes
+failed destinations even when another destination successfully writes the record.
+
 Native delivery uses the bounded callable queue and is drained on
 reconfiguration, `shutdown()`, fork, and interpreter exit. Call
 `structguru.flush()` when you need to block until buffered records have actually
@@ -210,11 +278,11 @@ structguru.flush()  # returns once the line has reached its sink
 
 ```python
 # JSON (production)
-configure(service="myapp", format="json")
+update(service="myapp", format="json")
 # → {"logger":"...","level":"INFO","severity":6,"timestamp":"...","service":"myapp","message":"..."}
 
 # Console (development) — colored, human-readable
-configure(service="myapp", format="console")
+update(service="myapp", format="console")
 # → 2026-01-15T12:00:00.123456Z [INFO    ] Hello world
 ```
 
@@ -225,9 +293,9 @@ configure(service="myapp", format="console")
 Mask sensitive fields automatically:
 
 ```python
-from structguru import configure
+from structguru import update
 
-configure(
+update(
     sensitive_keys=["password", "token", "ssn"],
     sensitive_patterns=[r"\b\d{3}-\d{2}-\d{4}\b"],
     pattern_replacement="***",
@@ -235,7 +303,7 @@ configure(
 ```
 
 Patterns run on Rust's linear-time regex engine (no ReDoS), which rejects
-look-around and backreferences at `configure()` time. Most look-behinds rewrite
+look-around and backreferences at `update()` time. Most look-behinds rewrite
 as capture groups — `(?<=password=)\S+` becomes `(password=)\S+` with
 `pattern_replacement="$1[REDACTED]"`, so the prefix is re-emitted and the
 secret is replaced (`password=hunter2` → `password=[REDACTED]`). Put the
@@ -248,7 +316,7 @@ backtrack limit, it is redacted entirely (fail-closed) rather than emitted
 unchecked.
 
 ```python
-configure(
+update(
     sensitive_patterns=[r"(?<=password=)\S+"],
     allow_backtracking_patterns=True,
 )
@@ -259,9 +327,9 @@ configure(
 Suppress noisy logs:
 
 ```python
-from structguru import configure
+from structguru import update
 
-configure(sample_rate=0.1, rate_limit_max=5, rate_limit_period=60)
+update(sample_rate=0.1, rate_limit_max=5, rate_limit_period=60)
 ```
 
 ### Metric extraction
@@ -269,13 +337,13 @@ configure(sample_rate=0.1, rate_limit_max=5, rate_limit_period=60)
 Derive metrics from log events:
 
 ```python
-from structguru import MetricProcessor, configure
+from structguru import MetricProcessor, update
 
 metrics = MetricProcessor()
 metrics.counter("user.login", lambda ed: login_counter.inc())
 metrics.histogram("db.query", "duration_ms", lambda v, ed: query_hist.observe(v))
 
-configure(metric_processor=metrics)
+update(metric_processor=metrics)
 ```
 
 ### Exception formatting
@@ -283,35 +351,47 @@ configure(metric_processor=metrics)
 Render exceptions as JSON-serializable dictionaries:
 
 ```python
-from structguru import configure
+from structguru import update
 
-configure(structured_exceptions=True, exception_max_frames=20)
+update(structured_exceptions=True, exception_max_frames=20)
 ```
 
 `exception_max_frames=0` omits traceback frames entirely. Negative frame and
 local-representation limits are rejected during configuration.
 
+Formatted tracebacks (the default) carry CPython's per-frame position markers,
+the `~~~^^^` lines, and on Python 3.11+ computing them is most of the cost of
+`logger.exception()`. `exception_carets=False` omits them, which formats a
+traceback about five times faster and matches what CPython prints under
+`PYTHONNODEBUGRANGES=1`:
+
+```python
+update(exception_carets=False)
+```
+
 ### OpenTelemetry correlation
 
 Inject trace context into every log event:
 
 ```python
-from structguru import configure
+from structguru import update
 
-configure(otel=True)  # no-op injection when opentelemetry-api is absent
+update(otel=True)  # no-op injection when opentelemetry-api is absent
 ```
 
 ### Non-blocking logging
 
 Since v1.0, log I/O is offloaded to a background thread by default. The native
-Rust writer uses a bounded 8192-record queue with lossless backpressure. Set
+Rust writer uses a bounded 8192-record queue and waits for space while it is open. Set
 `overflow="drop"` to favor caller latency, or explicitly pass `maxsize=0` only
 when an unbounded queue is acceptable.
 
+
 ## Native runtime
 
 structguru ships a required Rust extension that renders and enqueues logging
-natively, off-thread. It is auto-enabled at import time. The runtime does not depend on `orjson`;
+natively, off-thread. It is auto-enabled at import time, and importing the package
+without the extension raises `RuntimeError`. The runtime does not depend on `orjson`;
 exotic values (`datetime`, `UUID`, `Enum`, dataclasses) are converted natively
 in Rust.
 
@@ -351,10 +431,10 @@ structguru.logger.bind(request_id="abc").info("order {id} accepted", id=987)
 # → JSON line written to /var/log/app.log by a background writer thread
 ```
 
-The default import-time configuration also honors environment variables:
+Import-time configuration and `configure()` without a Settings object honor environment variables:
 
 ```bash
-LOG_LEVEL=INFO STRUCTGURU_SERVICE=myapp python -m myapp
+STRUCTGURU_LEVEL=INFO STRUCTGURU_SERVICE=myapp python -m myapp
 ```
 
 Invalid native environment values fail import with an actionable exception. This
@@ -364,20 +444,24 @@ Public API:
 
 | Symbol | Purpose |
 |--------|---------|
-| `configure(...)` | Configure rendering, filtering, redaction, and output sinks. See the API reference for the complete signature. |
+| `configure(...)` | Replace rendering, filtering, redaction, and output settings. |
+| `Settings` | Validate reusable options; construct from Python values, a mapping, or the environment. |
+| `get_config()` | Return configured options, or `None` when shut down. |
+| `update(...)` | Change selected active options without rereading the environment. |
 | `shutdown()` | Stop the writer; logging is disabled until `configure()` is called. |
 | `set_level(level)` | Adjust the level threshold at runtime. |
-| `writer_metrics()` | Writer counters (enqueued/written/dropped/depth/...) plus filter counters (`sampled`/`rate_limited`) when active. |
-| `is_available()` | Whether the compiled extension is importable. |
+| `writer_metrics()` | Current writer counters (enqueued/written/dropped/depth/...) plus filter counters when active; `None` after shutdown. |
+| `lifecycle_metrics()` | Cumulative native deliveries rejected by closed writers; available after shutdown and across reconfiguration. |
+| `is_available()` | Compatibility helper; always `True` once the package has imported, because a missing extension fails import. |
 
 Behavior notes:
 
-- **Overflow**: the default `maxsize=8192` uses `overflow="block"` for bounded, lossless backpressure. Use `overflow="drop"` for drop-newest behavior with metrics and rate-limited warnings. `maxsize=0` explicitly opts into an unbounded queue.
+- **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.
 - **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.
+- **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`.
 - **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).
@@ -385,6 +469,14 @@ Behavior notes:
 - **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.
 
+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.
+
 ## Framework integrations
 
 ### ASGI (FastAPI / Starlette)
@@ -396,6 +488,13 @@ app = FastAPI()
 app.add_middleware(StructguruMiddleware, request_id_header="X-Request-ID")
 ```
 
+### Granian
+
+Route Granian's server logs through `StructguruHandler` using `--log-config`,
+and use `StructguruMiddleware` for ASGI request IDs and structured summaries.
+The [Granian integration guide](docs/integrations.md#granian) includes a complete
+logging dictionary, application and launcher examples, and access-log options.
+
 ### Celery
 
 ```python
@@ -448,11 +547,11 @@ server = grpc.server(
 ```python
 import logging
 
-from structguru import configure
+from structguru import update
 from structguru.integrations.sentry import SentryProcessor
 
 sentry = SentryProcessor(event_level=logging.ERROR, tag_keys=frozenset({"service"}))
-configure(sentry_processor=sentry)
+update(sentry_processor=sentry)
 ```
 
 ### Stdlib bridge