Migrating to structlog 25.1.0
Version 25.1.0 introduces 2 breaking changes. This guide details how to update your code.
Released: 1/16/2025
⚠️ Check Your Code
If you use any of these symbols, you need to read this guide:
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.devBreaking Changes
●Issue #1
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.
●Issue #2
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
- 1Install the `typing-extensions` package if you support Python versions older than 3.11.
- 2Update any code that relied on the old return type of `structlog.typing.BindableLogger` to accept the new `Self` return.
- 3Replace uses of `FilteringBoundLogger.fatal()` with `error()` or `critical()` if you need explicit level handling.
- 4If you were manually adding `PositionalArgumentsFormatter`, you can now rely on `recreate_defaults()` to add it automatically.
Release 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.
Need More Details?
View the full release notes and all changes for structlog 25.1.0.
View Full Changelog