●Change8

25.1.0

Breaking Changes
📦 structlogView on GitHub →
⚠ 2 breaking✨ 2 features🐛 7 fixes🔧 10 symbols

Summary

This release adds a new processor for positional log arguments, native logger helpers, and several bug fixes, while introducing breaking changes to the BindableLogger protocol and fatal logging behavior.

⚠️ Breaking Changes

  • structlog.typing.BindableLogger protocol now returns Self instead of BindableLogger, which may break code expecting the old return type; install typing-extensions for Python <3.11 and update type hints accordingly.
  • structlog.native.FilteringBoundLogger.fatal() now maps to the critical level (mirroring the standard library); code that relied on its previous mapping should switch to using error() or critical().

Migration Steps

  1. Install the `typing-extensions` package if you support Python versions older than 3.11.
  2. Update any code that relied on the old return type of `structlog.typing.BindableLogger` to accept the new `Self` return.
  3. Replace uses of `FilteringBoundLogger.fatal()` with `error()` or `critical()` if you need explicit level handling.
  4. If you were manually adding `PositionalArgumentsFormatter`, you can now rely on `recreate_defaults()` to add it automatically.

✨ New Features

  • Added `structlog.stdlib.render_to_log_args_and_kwargs` processor, allowing positional arguments to be passed to the standard library logging without needing the `structlog.stdlib.PositionalArgumentsFormatter` processor.
  • Native loggers now expose `is_enabled_for()` and `get_effective_level()` methods, mirroring `logging.Logger.isEnabledFor()` and `logging.Logger.getEffectiveLevel()`.

🐛 Bug Fixes

  • Fixed handling of `{logger}.exception()` calls outside of exception blocks: missing or invalid `exc_info` is now ignored, making the call behave like `{logger}.error()`.
  • Instantiating `structlog.dev.ConsoleRenderer` no longer mutates the provided `styles` dictionary.
  • Native `FilteringBoundLogger.fatal()` now correctly maps to the critical level, aligning with the standard library behavior.
  • `structlog.tracebacks.ExceptionDictTransformer` now accepts `None` for `locals_max_length` and `locals_max_string`.
  • `structlog.stdlib.recreate_defaults()` now also adds `structlog.stdlib.PositionalArgumentsFormatter`.
  • `structlog.dev.ConsoleRenderer` now quotes string values containing special characters.
  • `structlog.make_filtering_bound_logger()` now accepts a string for `min_level`.

Affected Symbols

structlog.stdlib.render_to_log_args_and_kwargsstructlog.stdlib.PositionalArgumentsFormatterstructlog.typing.BindableLoggerstructlog.dev.ConsoleRendererstructlog.stdlib.recreate_defaultsstructlog.make_filtering_bound_loggerstructlog.native.FilteringBoundLogger.fatalstructlog.tracebacks.ExceptionDictTransformerstructlog.native.FilteringBoundLoggerstructlog.dev