structguru 1.0.2__tar.gz → 1.0.4__tar.gz

{structguru-1.0.2 → structguru-1.0.4}/Cargo.lock

@@ -300,7 +300,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-core"
-version = "1.0.2"
+version = "1.0.4"
 dependencies = [
  "fancy-regex",
  "rand",
@@ -312,7 +312,7 @@ dependencies = [
 
 [[package]]
 name = "structguru-py"
-version = "1.0.2"
+version = "1.0.4"
 dependencies = [
  "pyo3",
  "regex",

{structguru-1.0.2 → structguru-1.0.4}/Cargo.toml

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

{structguru-1.0.2 → structguru-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: structguru
-Version: 1.0.2
+Version: 1.0.4
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -101,7 +101,7 @@ Available extras: `otel`, `celery`, `flask`, `django`, `sqlalchemy`, `grpc`,
 from structguru import configure, logger
 
 # Configure once at startup
-configure(service="myapp", level="DEBUG", json=True)
+configure(service="myapp", level="DEBUG", format="json")
 
 # Use anywhere
 logger.info("Hello {name}", name="world")
@@ -187,18 +187,21 @@ file sink are owner-only (`0600`). Existing files retain their permissions.
 
 All sink forms receive structguru records. They are also registered with the
 stdlib root logger for third-party records. Native delivery uses the bounded
-callable queue and participates in `flush_native()`, reconfiguration, disable,
-fork, and shutdown draining.
+callable queue and is drained on flush, reconfiguration, `shutdown()`, fork, and
+interpreter exit.
 
 ### Console vs JSON output
 
+`format=` selects the renderer: `"json"` (default, production) or `"console"`
+(colored, human-readable development output).
+
 ```python
 # JSON (production)
-configure(service="myapp", json=True)
+configure(service="myapp", format="json")
 # → {"timestamp": "...", "service": "myapp", "level": "INFO", "message": "..."}
 
 # Console (development) — colored, human-readable
-configure(service="myapp", json=False)
+configure(service="myapp", format="console")
 # → 2025-01-15 12:00:00 [info     ] Hello world
 ```
 
@@ -306,8 +309,6 @@ structguru.logger.info("order {id} accepted", id=987)
 
 No configuration is required for the default JSON-to-stdout behavior. Call
 `configure(...)` to customize the renderer, filtering, or sinks.
-`configure_structlog(...)` remains as a deprecated compatibility wrapper for
-its simpler service/level/format/stream interface and will be removed in v2.0.
 
 ```python
 import structguru
@@ -331,11 +332,10 @@ Public API:
 | Symbol | Purpose |
 |--------|---------|
 | `configure(...)` | Configure rendering, filtering, redaction, and output sinks. See the API reference for the complete signature. |
-| `configure_structlog(...)` | Deprecated compatibility wrapper; use `configure()`. Removed in v2.0. |
-| `disable_native()` | Stop the writer; logging is disabled until `configure()` is called. |
-| `set_native_level(level)` | Adjust the level threshold at runtime. |
-| `native_metrics()` | Writer counters (enqueued/written/dropped/depth/...) plus filter counters (`sampled`/`rate_limited`) when active. |
-| `native_available()` | Whether the compiled extension is importable. |
+| `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. |
 
 Behavior notes:
 
@@ -346,7 +346,7 @@ Behavior notes:
 - **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.
 - **`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** (`json=False`): 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`.
+- **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).
 - **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.
 - **Sentry integration** (`sentry_processor=SentryProcessor(...)`): receives the already-redacted event and raw `exc_info` only for exception capture.

{structguru-1.0.2 → structguru-1.0.4}/README.md

@@ -57,7 +57,7 @@ Available extras: `otel`, `celery`, `flask`, `django`, `sqlalchemy`, `grpc`,
 from structguru import configure, logger
 
 # Configure once at startup
-configure(service="myapp", level="DEBUG", json=True)
+configure(service="myapp", level="DEBUG", format="json")
 
 # Use anywhere
 logger.info("Hello {name}", name="world")
@@ -143,18 +143,21 @@ file sink are owner-only (`0600`). Existing files retain their permissions.
 
 All sink forms receive structguru records. They are also registered with the
 stdlib root logger for third-party records. Native delivery uses the bounded
-callable queue and participates in `flush_native()`, reconfiguration, disable,
-fork, and shutdown draining.
+callable queue and is drained on flush, reconfiguration, `shutdown()`, fork, and
+interpreter exit.
 
 ### Console vs JSON output
 
+`format=` selects the renderer: `"json"` (default, production) or `"console"`
+(colored, human-readable development output).
+
 ```python
 # JSON (production)
-configure(service="myapp", json=True)
+configure(service="myapp", format="json")
 # → {"timestamp": "...", "service": "myapp", "level": "INFO", "message": "..."}
 
 # Console (development) — colored, human-readable
-configure(service="myapp", json=False)
+configure(service="myapp", format="console")
 # → 2025-01-15 12:00:00 [info     ] Hello world
 ```
 
@@ -262,8 +265,6 @@ structguru.logger.info("order {id} accepted", id=987)
 
 No configuration is required for the default JSON-to-stdout behavior. Call
 `configure(...)` to customize the renderer, filtering, or sinks.
-`configure_structlog(...)` remains as a deprecated compatibility wrapper for
-its simpler service/level/format/stream interface and will be removed in v2.0.
 
 ```python
 import structguru
@@ -287,11 +288,10 @@ Public API:
 | Symbol | Purpose |
 |--------|---------|
 | `configure(...)` | Configure rendering, filtering, redaction, and output sinks. See the API reference for the complete signature. |
-| `configure_structlog(...)` | Deprecated compatibility wrapper; use `configure()`. Removed in v2.0. |
-| `disable_native()` | Stop the writer; logging is disabled until `configure()` is called. |
-| `set_native_level(level)` | Adjust the level threshold at runtime. |
-| `native_metrics()` | Writer counters (enqueued/written/dropped/depth/...) plus filter counters (`sampled`/`rate_limited`) when active. |
-| `native_available()` | Whether the compiled extension is importable. |
+| `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. |
 
 Behavior notes:
 
@@ -302,7 +302,7 @@ Behavior notes:
 - **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.
 - **`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** (`json=False`): 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`.
+- **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).
 - **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.
 - **Sentry integration** (`sentry_processor=SentryProcessor(...)`): receives the already-redacted event and raw `exc_info` only for exception capture.

{structguru-1.0.2 → structguru-1.0.4}/crates/structguru-core/src/filter.rs

@@ -24,7 +24,7 @@ pub trait RecordFilter: Send + Sync {
     fn allow(&self, key: &str, level: &str) -> Decision;
 }
 
-/// Numeric level for a method name (mirrors `_LEVEL_NUM` in `_native.py`).
+/// Numeric level for a method name (mirrors `_LEVEL_NUM` in `_runtime.py`).
 fn method_level_num(method: &str) -> u8 {
     match method {
         "trace" => 5,

{structguru-1.0.2 → structguru-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "structguru"
-version = "1.0.2"
+version = "1.0.4"
 description = "Native structured logging with a loguru-style Python API"
 readme = "README.md"
 license = "MIT"
@@ -131,6 +131,3 @@ ignore_missing_imports = true
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"
-filterwarnings = [
-    "ignore:configure_structlog\\(\\) is deprecated; use configure\\(\\) instead\\. It will be removed in v2\\.0\\.:DeprecationWarning",
-]

{structguru-1.0.2 → structguru-1.0.4}/src/structguru/__init__.py

@@ -1,19 +1,18 @@
 """structguru — ergonomic structured logging with a native Rust runtime."""
 
-from structguru._native import (
+from structguru._runtime import (
     configure,
-    disable_native,
-    native_available,
-    native_metrics,
-    set_native_level,
+    is_available,
+    set_level,
+    shutdown,
+    writer_metrics,
 )
-from structguru.config import configure_structlog
 from structguru.core import Logger, logger
 from structguru.metrics import MetricProcessor
 from structguru.otel import add_otel_context
 from structguru.redaction import DEFAULT_SENSITIVE_KEYS
 
-__version__ = "1.0.2"
+__version__ = "1.0.4"
 
 __all__ = [
     "DEFAULT_SENSITIVE_KEYS",
@@ -21,10 +20,9 @@ __all__ = [
     "MetricProcessor",
     "add_otel_context",
     "configure",
-    "configure_structlog",
-    "disable_native",
+    "is_available",
     "logger",
-    "native_available",
-    "native_metrics",
-    "set_native_level",
+    "set_level",
+    "shutdown",
+    "writer_metrics",
 ]

structguru-1.0.2/src/structguru/_native.py → structguru-1.0.4/src/structguru/_runtime.py

@@ -40,6 +40,10 @@ _LEVEL_NUM: dict[str, int] = {
     "fatal": 50,
 }
 
+# Supported output renderers. ``format=`` on configure() accepts these names;
+# the choice maps to the ``console`` runtime flag until more than two formats exist.
+_FORMATS: tuple[str, ...] = ("json", "console")
+
 
 class _NativeWriter(Protocol):
     def try_enqueue(self, message: str) -> bool: ...
@@ -161,7 +165,7 @@ def _load_rust_module() -> _RustModule | None:
 _RUST = _load_rust_module()
 
 
-def native_available() -> bool:
+def is_available() -> bool:
     """Return whether the compiled native extension is importable."""
     return _RUST is not None
 
@@ -206,10 +210,10 @@ _lifecycle_generation = 0
 
 
 _callable_dispatcher = CallableSinkDispatcher()
-# Synchronous stream sink: when set (by configure_structlog), rendered lines are
-# written to this stream synchronously on the caller's thread IN ADDITION to the
-# Rust writer. This preserves the pre-1.0 contract that logger output is available
-# on the configured stream immediately after the call (no flush needed).
+# Synchronous stream sink: when set (via configure(stream_sink=...)), rendered
+# lines are written to this stream synchronously on the caller's thread IN
+# ADDITION to the Rust writer, so logger output is available on the configured
+# stream immediately after the call (no flush needed).
 _hooks_registered = False
 _drop_count = 0
 _drop_lock = threading.Lock()
@@ -231,7 +235,7 @@ def is_below_level(method: str, runtime: _RuntimeState | None = None) -> bool:
     return state is None or _LEVEL_NUM.get(method, _LEVEL_NUM["info"]) < state.level_threshold
 
 
-def set_native_level(level: str) -> None:
+def set_level(level: str) -> None:
     """Adjust the native level threshold at runtime (per-process)."""
     global _runtime, _lifecycle_generation
     with _state_lock:
@@ -436,7 +440,7 @@ def configure(
     exception_include_locals: bool = False,
     exception_max_frames: int = 20,
     exception_max_local_repr: int = 200,
-    json: bool = True,
+    format: str = "json",
     colors: bool | None = None,
     file_path: str | None = None,
     file_max_bytes: int = 50 * 1024 * 1024,
@@ -454,7 +458,7 @@ def configure(
     The output queue is bounded to 8192 records by default. ``overflow`` governs a
     full queue: ``"block"`` (default, no loss — the caller waits with the GIL
     released) or ``"drop"`` (drop the new record, count it, and emit a rate-limited
-    warning; see :func:`native_metrics`). Pass ``maxsize=0`` only to explicitly opt
+    warning; see :func:`writer_metrics`). Pass ``maxsize=0`` only to explicitly opt
     into an unbounded queue.
 
     ``sensitive_patterns`` is a list of regex source strings applied (in addition
@@ -479,7 +483,7 @@ def configure(
     ``sample_rate`` (0.0–1.0) and ``rate_limit_max``/``rate_limit_period`` add
     pre-render filters: dropped records cost zero rendering. ``sampled`` and
     ``rate_limited`` counters are reported separately from the writer's transport
-    ``dropped`` counter (see :func:`native_metrics`). ``sample_max_level``
+    ``dropped`` counter (see :func:`writer_metrics`). ``sample_max_level``
     restricts sampling to records at or below that level (more severe records
     always pass) — the native analog of level-gated sampling.
 
@@ -496,10 +500,11 @@ def configure(
     ``sensitive_keys`` reused for locals redaction) instead of the formatted
     traceback string.
 
-    ``json=False`` selects the native console renderer (colored, human-readable
-    dev output) instead of JSON. ``colors`` defaults to ``sys.stdout.isatty()``
-    in console mode; set it explicitly to override. The console format is
-    structguru's own stable dev format, not a structlog ``ConsoleRenderer`` clone.
+    ``format`` selects the renderer: ``"json"`` (default, production-friendly
+    compact JSON) or ``"console"`` (colored, human-readable dev output in
+    structguru's own stable format — not a structlog ``ConsoleRenderer`` clone).
+    ``colors`` defaults to ``sys.stdout.isatty()`` in console mode; set it
+    explicitly to override (ignored in JSON mode).
 
     ``file_path`` enables a native rotating-file sink (append mode). Defaults
     mirror :class:`logging.handlers.RotatingFileHandler`: ``file_max_bytes=50MB``,
@@ -562,6 +567,13 @@ def configure(
         msg = f"exception_max_local_repr must be >= 0, got {exception_max_local_repr}"
         raise ValueError(msg)
 
+    # Resolve the output format. ``format=`` is the canonical selector
+    # ("json" | "console"); ``format="json"`` is the default.
+    resolved_format = format
+    if resolved_format not in _FORMATS:
+        msg = f"format must be one of {_FORMATS}, got {resolved_format!r}"
+        raise ValueError(msg)
+
     # Validate regex patterns against Rust's engine before enabling. Rust's
     # `regex` guarantees linear-time matching and therefore rejects
     # backreferences and look-around; fail loudly at setup time — redaction
@@ -625,8 +637,8 @@ def configure(
                 msg = f"callable_sinks[{i}] must be callable, got {type(fn)!r}"
                 raise TypeError(msg)
 
-    # Resolve console/colors.
-    new_console = not json
+    # Resolve console/colors from the chosen format.
+    new_console = resolved_format == "console"
     new_colors = colors if colors is not None else (sys.stdout.isatty() if new_console else False)
 
     # Construct every fallible native resource before touching the active
@@ -754,7 +766,7 @@ def _after_in_child() -> None:
     _callable_dispatcher.after_fork(enabled=True)
 
 
-def disable_native() -> None:
+def shutdown() -> None:
     """Turn native mode off and stop the background writer."""
     global _runtime, _lifecycle_generation
     with _state_lock:
@@ -856,7 +868,7 @@ def render_and_enqueue(
             else _render_json(state, fields, logger, level, message, stack)
         )
     line = rendered + "\n"
-    # Synchronous stream sink (used by configure_structlog for backward compat).
+    # Synchronous stream sink (configure(stream_sink=...)).
     if state.stream_sink is not None:
         try:
             state.stream_sink.write(line)
@@ -917,7 +929,7 @@ def drain_messages() -> list[str]:
     return state.writer.messages() if state is not None else []
 
 
-def native_metrics() -> dict[str, Any] | None:
+def writer_metrics() -> dict[str, Any] | None:
     """Return writer + filter metrics.
 
     Writer counters: ``enqueued``, ``dropped`` (queue-full), ``written``, ``depth``,

structguru-1.0.4/src/structguru/config.py

@@ -0,0 +1,27 @@
+"""Level-name helpers for structguru.
+
+Since v1.0, structguru uses the native Rust renderer as its only logging path.
+Runtime configuration lives in :func:`structguru.configure`; this module keeps
+the level-name conversion helper shared by the integrations.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+def _to_logging_level(level_name: str) -> int:
+    """Convert a human-readable level name to its :mod:`logging` constant."""
+    upper_level = level_name.upper()
+    if upper_level == "WARN":
+        return logging.WARNING
+    result: int | None = getattr(logging, upper_level, None)
+    if not isinstance(result, int):
+        import warnings
+
+        warnings.warn(
+            f"Unknown log level {level_name!r}, falling back to INFO",
+            stacklevel=2,
+        )
+        return logging.INFO
+    return result

{structguru-1.0.2 → structguru-1.0.4}/src/structguru/core.py

@@ -28,7 +28,7 @@ from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Any, TypeAlias
 
-from structguru import _native
+from structguru import _runtime
 from structguru._contextvars import bound_contextvars, get_contextvars
 from structguru.config import _to_logging_level
 from structguru.otel import add_otel_context
@@ -320,14 +320,14 @@ class Logger:
         # One coherent snapshot follows the record through every processing stage.
         # Reconfigure/disable may retire its writer, but cannot invalidate this
         # Python object or expose a partially updated configuration.
-        runtime = _native.current_runtime()
+        runtime = _runtime.current_runtime()
         if runtime is None:
             return
 
-        stack_info = bool(kwargs.get("stack_info") or self._opt_stack_info)
+        stack_info = kwargs.get("stack_info") or self._opt_stack_info
 
         # Cheap disabled path: level-filter before any formatting.
-        if _native.is_below_level(method, runtime):
+        if _runtime.is_below_level(method, runtime):
             return
 
         formatted_msg, consumed_keys = _safe_format(message, args, kwargs)
@@ -339,7 +339,7 @@ class Logger:
 
         # Pre-render filter (sampling/rate-limit): decide before building fields.
         # Keys on the formatted message, matching the rate-limiter's grouping.
-        if not _native.should_render(method, formatted_msg, runtime):
+        if not _runtime.should_render(method, formatted_msg, runtime):
             return
 
         exc_info = kwargs.get("exc_info", self._opt_exc_info)
@@ -352,17 +352,22 @@ class Logger:
         # matching structlog's merge_contextvars setdefault semantics.
         for key, value in get_contextvars().items():
             fields.setdefault(key, value)
-        if _native.otel_enabled(runtime):
+        if _runtime.otel_enabled(runtime):
             add_otel_context(None, method, fields)
         if exc_info:
-            exception = _native.build_exception_field(exc_info, runtime)
+            exception = _runtime.build_exception_field(exc_info, runtime)
             if exception:
                 fields["exception"] = exception
         # Stack capture is Python-owned (frame walking); rendering places
         # "stack" between "service" and "message" like StackInfoRenderer.
-        stack = _native.format_stack() if stack_info else None
-        _native.notify_metrics(method, formatted_msg, fields, runtime)
-        sentry_line = _native.render_and_enqueue(
+        if isinstance(stack_info, str):
+            stack = stack_info
+        elif stack_info:
+            stack = _runtime.format_stack()
+        else:
+            stack = None
+        _runtime.notify_metrics(method, formatted_msg, fields, runtime)
+        sentry_line = _runtime.render_and_enqueue(
             fields,
             name,
             method,
@@ -371,7 +376,7 @@ class Logger:
             runtime=runtime,
         )
         if sentry_line is not None:
-            _native.notify_sentry(
+            _runtime.notify_sentry(
                 method,
                 sentry_line,
                 tuple(fields),
@@ -415,7 +420,7 @@ class Logger:
             if callable(sink) and not isinstance(sink, logging.Handler)
             else functools.partial(_emit_rendered, handler)
         )
-        native_token = _native.add_callable_sink(native_callback, min_level=native_level)
+        native_token = _runtime.add_callable_sink(native_callback, min_level=native_level)
 
         root = logging.getLogger()
         root.addHandler(handler)
@@ -451,7 +456,7 @@ class Logger:
                 ]
         for handler, token in registrations:
             if token is not None:
-                _native.remove_callable_sink(token)
+                _runtime.remove_callable_sink(token)
             if handler is not None:
                 root.removeHandler(handler)
                 handler.close()

structguru-1.0.4/src/structguru/integrations/stdlib.py

@@ -0,0 +1,178 @@
+"""Route standard-library logging into structguru's native pipeline.
+
+Third-party libraries log through the stdlib :mod:`logging` module. Installing
+the bridge attaches a handler to the root logger that re-emits every such record
+through structguru's native renderer, so foreign logs share the same JSON /
+console formatting, redaction, level filtering, and output stream as
+``structguru.logger``::
+
+    from structguru.integrations.stdlib import install_stdlib_bridge
+
+    install_stdlib_bridge(level="INFO", suppress_loggers=("urllib3", "botocore"))
+
+    import logging
+    logging.getLogger("sqlalchemy.engine").info("SELECT 1")
+    # -> {"logger":"sqlalchemy.engine","level":"INFO",...,"message":"SELECT 1"}
+
+For a logger that sets ``propagate=False`` (so its records never reach the root
+logger), attach :class:`StructguruHandler` to it directly.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Iterable
+from typing import Any
+
+from structguru.config import _to_logging_level
+from structguru.core import Logger
+
+# Attributes present on a vanilla LogRecord (plus the two the Formatter adds).
+# Anything else in ``record.__dict__`` came from a user ``extra=`` mapping and is
+# forwarded as a structured field.
+_STANDARD_RECORD_ATTRS = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "levelname",
+        "levelno",
+        "pathname",
+        "filename",
+        "module",
+        "exc_info",
+        "exc_text",
+        "stack_info",
+        "lineno",
+        "funcName",
+        "created",
+        "msecs",
+        "relativeCreated",
+        "thread",
+        "threadName",
+        "processName",
+        "process",
+        "taskName",
+        "message",
+        "asctime",
+    }
+)
+
+
+def _method_for_level(levelno: int) -> str:
+    """Map a stdlib numeric level to the structguru method that emits it."""
+    if levelno >= logging.CRITICAL:
+        return "critical"
+    if levelno >= logging.ERROR:
+        return "error"
+    if levelno >= logging.WARNING:
+        return "warning"
+    if levelno >= logging.INFO:
+        return "info"
+    return "debug"
+
+
+@functools.lru_cache(maxsize=1024)
+def _logger_for(name: str) -> Logger:
+    """Return a cached structguru :class:`Logger` bound to *name*.
+
+    The base logger is immutable in practice — ``bind()``/``opt()`` return fresh
+    copies — so a shared per-name instance is safe to reuse across threads.
+    """
+    return Logger(name=name)
+
+
+def _record_extras(record: logging.LogRecord) -> dict[str, Any]:
+    """Extract user-supplied ``extra=`` fields from a record."""
+    return {
+        key: value for key, value in record.__dict__.items() if key not in _STANDARD_RECORD_ATTRS
+    }
+
+
+class StructguruHandler(logging.Handler):
+    """A :class:`logging.Handler` that re-emits stdlib records via structguru.
+
+    The record's logger name becomes the ``logger`` field, its level selects the
+    structguru method, ``extra=`` fields are forwarded as structured fields, and
+    ``exc_info`` and ``stack_info`` are carried through. The already-formatted
+    message is passed verbatim (no brace re-formatting), so literal ``{...}`` in
+    a message is never misinterpreted.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        # Never intercept structguru's own records: it keeps the bridge from
+        # looping and stops native output being wrapped a second time.
+        if record.name == "structguru" or record.name.startswith("structguru."):
+            return
+        try:
+            target = _logger_for(record.name)
+            extras = _record_extras(record)
+            if extras:
+                target = target.bind(**extras)
+            if record.exc_info:
+                target = target.opt(exception=record.exc_info)
+            emit_method = getattr(target, _method_for_level(record.levelno))
+            if record.stack_info:
+                emit_method(record.getMessage(), stack_info=record.stack_info)
+            else:
+                emit_method(record.getMessage())
+        except Exception:  # noqa: BLE001 - a logging handler must never raise
+            self.handleError(record)
+
+
+def _apply_suppression(names: Iterable[str], level: str) -> None:
+    threshold = _to_logging_level(level)
+    for name in names:
+        logging.getLogger(name).setLevel(threshold)
+
+
+def suppress_loggers(*names: str, level: str = "WARNING") -> None:
+    """Raise the level threshold of the named loggers.
+
+    Use this to quiet noisy third-party loggers (``"urllib3"``,
+    ``"botocore"``, ``"sqlalchemy.engine"``, …) regardless of whether they reach
+    structguru through the bridge or their own handlers.
+    """
+    _apply_suppression(names, level)
+
+
+def install_stdlib_bridge(
+    *,
+    level: str = "INFO",
+    suppress_loggers: Iterable[str] = (),
+    suppress_level: str = "WARNING",
+    clear_handlers: bool = True,
+) -> StructguruHandler:
+    """Route root stdlib logging through structguru and quiet noisy loggers.
+
+    Installs a :class:`StructguruHandler` on the root logger so any library
+    logging through :mod:`logging` renders through structguru's native path. The
+    returned handler can be passed to ``logging.getLogger().removeHandler(...)``
+    to uninstall.
+
+    Parameters
+    ----------
+    level:
+        Level set on the root logger — the floor for which stdlib records
+        propagate to the bridge. structguru's own native level (set via
+        :func:`structguru.configure`) still applies on top.
+    suppress_loggers:
+        Logger names to raise to ``suppress_level`` (see :func:`suppress_loggers`).
+    suppress_level:
+        Level applied to ``suppress_loggers`` (default ``"WARNING"``).
+    clear_handlers:
+        Remove existing root handlers first (default ``True``), so records are
+        not also emitted by a previously configured stdlib handler.
+    """
+    root = logging.getLogger()
+    if clear_handlers:
+        for handler in list(root.handlers):
+            root.removeHandler(handler)
+    threshold = _to_logging_level(level)
+    bridge = StructguruHandler()
+    bridge.setLevel(threshold)
+    root.addHandler(bridge)
+    root.setLevel(threshold)
+    _apply_suppression(suppress_loggers, suppress_level)
+    return bridge

structguru-1.0.2/src/structguru/config.py

@@ -1,88 +0,0 @@
-"""Logging configuration for structguru.
-
-Since v1.0, structguru uses the native Rust renderer as its only logging path.
-The remaining compatibility shim configures the native renderer to match the
-pre-1.0 observable stream contract.
-"""
-
-from __future__ import annotations
-
-import logging
-import sys
-from typing import Any
-
-from structguru._native import configure as _configure
-
-
-def _to_logging_level(level_name: str) -> int:
-    """Convert a human-readable level name to its :mod:`logging` constant."""
-    upper_level = level_name.upper()
-    if upper_level == "WARN":
-        return logging.WARNING
-    result: int | None = getattr(logging, upper_level, None)
-    if not isinstance(result, int):
-        import warnings
-
-        warnings.warn(
-            f"Unknown log level {level_name!r}, falling back to INFO",
-            stacklevel=2,
-        )
-        return logging.INFO
-    return result
-
-
-def configure_structlog(
-    *,
-    service: str = "app",
-    level: str = "INFO",
-    json_logs: bool = True,
-    stream: Any = None,
-    clear_handlers: bool = True,
-) -> None:
-    """Configure the native logger.
-
-    .. deprecated:: 1.0
-        Use :func:`structguru.configure` instead. This compatibility wrapper
-        will be removed in v2.0.
-
-    Since v1.0, this is a compatibility shim that wires the native Rust renderer
-    synchronously to the given *stream*, preserving the pre-1.0 contract
-    that ``logger`` output lands on the configured stream. The native renderer
-    handles all JSON/console formatting, redaction, and level filtering.
-
-    Parameters
-    ----------
-    service:
-        Application/service name added to every log record.
-    level:
-        Minimum log level (e.g. ``"DEBUG"``, ``"INFO"``).
-    json_logs:
-        ``True`` for JSON output, ``False`` for colored console output.
-    stream:
-        Output stream. Defaults to ``sys.stdout`` and is the sole output target.
-    clear_handlers:
-        Kept for backward compatibility; the native path does not use root
-        logger handlers.
-    """
-    import warnings
-
-    warnings.warn(
-        "configure_structlog() is deprecated; use configure() instead. "
-        "It will be removed in v2.0.",
-        DeprecationWarning,
-        stacklevel=2,
-    )
-
-    if stream is None:
-        stream = sys.stdout
-
-    # Wire the stream as a synchronous sink so logger output lands on it
-    # immediately (preserving the pre-1.0 contract that output is available
-    # right after the logger call, no flush needed).
-    _configure(
-        service=service,
-        level=level,
-        json=json_logs,
-        target="null",
-        stream_sink=stream,
-    )