25.1.0

Highlights

Lots of updates to exception handling that I hope will stabilize a bit now.

Full changelog below!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), Klaviyo (@klaviyo), FilePreviews (@filepreviews), Privacy Solutions GmbH (@privacy-solutions), Gedankenspieler (@Gedankenspieler), Daniel Fortunov (@asqui), Kevin P. Fleming (@kpfleming), and Polar (@polarsource).

Maintenance Sustainers

Buttondown (@buttondown), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Chris Withers (@cjw296), Mike Fiedler (@miketheman), Duncan Hill (@cricalix), Colin Marquardt (@cmarqu), Pieter Swinkels (@swinkels), Nick Libertini (@libertininick), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), The Westervelt Company (@westerveltco), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), Thomas Klinger (@thmsklngr), Andreas Poehlmann (@ap--), August Bigelow (@atbigelow), Carlton Gibson (@carltongibson), and Roboflow (@roboflow).

Not to forget 11 more amazing humans who chose to be generous but anonymous!

Full Changelog

Added

• Add structlog.stdlib.render_to_log_args_and_kwargs processor. Same as structlog.stdlib.render_to_log_kwargs, but also allows to pass positional arguments to logging. With it, you do not need to add structlog.stdlib.PositionalArgumentsFormatter processor to format positional arguments from structlog loggers. #668

• Native loggers now have is_enabled_for() and get_effective_level() methods that mirror the behavior of the standard library's logging.Logger.isEnabledFor() and logging.Logger.getEffectiveLevel(). #689

Changed

• structlog.typing.BindableLogger protocol now returns Self instead of BindableLogger. This adds a dependency on typing-extensions for Pythons older than 3.11. #642 #659

• structlog.dev.ConsoleRenderer will quote string value with special characters. #647

• structlog.stdlib.recreate_defaults() now also adds structlog.stdlib.PositionalArgumentsFormatter. In default native mode, this is done by the loggers at the edge.

• structlog.make_filtering_bound_logger() now also accepts a string for min_level.

Fixed

• Fix handling calls to {logger}.exception() outside of exception blocks. Depending on the structlog configuration, this either resulted in an event dict key exception: "MISSING" or lead to an error. Now, an invalid or missing exc_info will just be ignored. This means, that calling {logger}.exception() outside of an exception block is basically the same as calling {logger}.error(). #634 #680

• Instantiating structlog.dev.ConsoleRenderer does not mutate the passed styles dict anymore. #669

• The native FilteringBoundLogger.fatal() method now maps to the critical level, as it does in the standard library. Note that the level is discouraged to use there, so we recommend to stick to error() or critical(). #677

• structlog.tracebacks.ExceptionDictTransformer now actually accepts None for locals_max_length and locals_max_string. #675

---

This release contains contributions from @aThorp96, @brcsw, @denis-savran, @emmanuel-ferdman, @hynek, @kain88-de, @Sh4pe, @sscherfke, @Tinche, @trim21, and @yaelmi3.

Artifact Attestations

You can verify this release's artifact attestions using GitHub's CLI tool by downloading the sdist and wheel from PyPI and running:

$ gh attestation verify --owner hynek structlog-25.1.0.tar.gz

and

$ gh attestation verify --owner hynek structlog-25.1.0-py3-none-any.whl

24.4.0

Highlights

This is just a docs / PyPI README update. No code changes whatsoever.

Full changelog below!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Klaviyo (@klaviyo), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).

Maintenance Sustainers

Adam Hill (@adamghill), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), Mike Fiedler (@miketheman), Thomas Klinger (@thmsklngr), Duncan Hill (@cricalix), and Colin Marquardt (@cmarqu).

Not to forget 7 more amazing humans who chose to be generous but anonymous!

Full Changelog

Changed

No code changes since 24.3.0

Artifact Attestations

You can verify this release's artififact attestions using GitHub's CLI tool by downloading the sdist and wheel from PyPI and running:

$ gh attestation verify --owner hynek structlog-24.4.0.tar.gz

and

$ gh attestation verify --owner hynek structlog-24.4.0-py3-none-any.whl

24.3.0

Highlights

This is just a quick release so I can focus on my other projects. But do enjoy the improved traceback dict rendering and log level handling in testing!

Full changelog below!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Klaviyo (@klaviyo), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).

Maintenance Sustainers

Adam Hill (@adamghill), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), Mike Fiedler (@miketheman), Thomas Klinger (@thmsklngr), Duncan Hill (@cricalix), and Colin Marquardt (@cmarqu).

Not to forget 7 more amazing humans who chose to be generous but anonymous!

Full Changelog

Added

• Restore feature parity between structlog.traceback.ExceptionDictTransformer and Rich's traceback extractor:

  • When displaying locals, use Rich for formatting if it is available.
  • When displaying locals, call repr() on strings, too (improves handling of SecretStr implementations).
  • Add locals_max_length config option
  • Add locals_hide_sunder config option
  • Add locals_hide_dunder config option
  • Add suppress config option

  #627

Changed

• structlog.testing.capture_logs() now maps the exception log level to error (as it's elsewhere). #628

24.2.0

Highlights

Overdue, and mostly bug fixes & optimizations! See y'all after my vacation. 🌴

Full changelog below!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Klaviyo (@klaviyo), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).

Maintenance Sustainers

Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), Mike Fiedler (@miketheman), Thomas Klinger (@thmsklngr), Duncan Hill (@cricalix), and Colin Marquardt (@cmarqu).

Not to forget 7 more amazing humans who chose to be generous but anonymous!

Full Changelog

Added

• It is now possible to disable log level-padding in structlog.dev.LogLevelColumnFormatter and structlog.dev.ConsoleRenderer. #599

• The structlog.processors.CallsiteParameterAdder can now be pickled. #603

• structlog.processors.CallsiteParameterAdder now also works with structlog.stdlib.BoundLogger's non-standard async methods (ainfo(), and so forth) #618

Changed

• structlog.processors.LogfmtRenderer now escapes newlines. #592

• structlog.processors.LogfmtRenderer now escapes backslashes and double quotes. #594

• structlog.processors.CallsiteParameterAdder has been optimized to be about 2x faster. #606

Fixed

• structlog.stdlib.render_to_log_kwargs now correctly passes stacklevel as a kwarg to stdlib logging. #619

24.1.0

Highlights

This quick bugfix release fixes two regressions and the fact that RichTracebackFormatter has been ignoring its width argument the whole time.

Full changelog below!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), Kevin P. Fleming (@kpfleming), and Sören Weber (@SoerenWeber).

Maintenance Sustainers

Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), and Mike Fiedler (@miketheman).

Not to forget 6 more amazing humans who chose to be generous but anonymous!

Full Changelog

Fixed

• The lazy logger proxy returned by structlog.get_logger() now returns its initial values when asked for context. When asked for context before binding for the first time, it returned an empty dictionary in 23.3.0.

• The displayed level name when using structlog.stdlib.BoundLogger.exception() is "error" instead of "exception". Fixes regression in 23.3.0. #584

• Don't ignore the width argument of RichTracebackFormatter. #587

23.3.0

Highlights

The highlight is the configurability of structlog.dev.ConsoleRenderer's output (check out https://www.structlog.org/en/stable/console-output.html#console-output-configuration!) and structlog.processors.CallsiteParameterAdder getting asyncio support.

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).

Maintenance Sustainers

Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), Sławomir Ehlert (@slafs), Mostafa Khalil (@khadrawy), Filip Mularczyk (@mukiblejlok), and Mike Fiedler (@miketheman).

Not to forget 6 more amazing humans who chose to be generous but anonymous!

Full Changelog

Added

• The colorful development logger is now even more configurable! Choose freely your colors and the order of the key-value pairs! Implement your own formatters for certain keys!

  Implementing the output on top of the new columns API has changed the default very slightly, but shouldn't be noticeable. #577

• Async log methods (those starting with an a) now also support the collection of callsite information using structlog.processors.CallsiteParameterAdder. #565

Changed

• structlog.stdlib.recreate_defaults() now also adds structlog.stdlib.add_logger_name to the processors. Check out the updated screenshot!

Fixed

• The return value from get_logger() (a BoundLoggerLazyProxy) now passes isinstance-checks against structlog.typing.BindableLogger on Python 3.12. #561

• structlog.threadlocal.tmp_bind() now also works with BoundLoggerLazyProxy (in other words: before anything is bound to a bound logger).

• stdlib: ProcessorFormatter can now be told to not render the log record message using getMessage and just str(record.msg) instead. #550

• stdlib: structlog.stdlib.BoundLogger.exception()'s handling ofLogRecord.exc_info is now set consistent with logging. #571 #572

23.2.0

Highlights

Not a super exciting release, but it was time to deliver some fixes and quality-of-life features to the people!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), HiredScore (@HiredScore), FilePreviews (@filepreviews), Daniel Fortunov (@asqui), and Kevin P. Fleming (@kpfleming).

Maintenance Sustainers

Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Tom Ballinger (@thomasballinger), Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), Stefan Hagen (@sthagen), and Sławomir Ehlert (@slafs).

Not to forget 4 more amazing humans who chose to be generous but anonymous!

Full Changelog

Removed

• Support for Python 3.7.

Added

• Official support for Python 3.12. #515

• structlog.processors.MaybeTimeStamper that only adds a timestamp if there isn't one already. #81

• structlog.dev.ConsoleRenderer now supports renamed timestamp keys using the timestamp_key parameter. #541

• structlog.dev.RichTracebackFormatter that allows to configure the traceback formatting. #542

Fixed

• FilteringBoundLogger.exception() and FilteringBoundLogger.aexception() now support positional argument formatting like the rest of the methods. #531
• structlog.processors.format_exc_info() and structlog.dev.ConsoleRenderer do not crash anymore when told to format a non-existent exception. #533

23.1.0

Highlights

This release brings the hybrid approach to sync / async logging to structlog's standard library integration. You don't have to configure anything anymore, simply prepend the method name with an a and await it: await logger.ainfo("this is async!"). structlog.stdlib.AsyncBoundLogger will probably be deprecated in the future.

This release also brings support for FORCE_COLOR and NO_COLOR to structlog's default configuration. structlog was originally not meant to be used without configuration, but times have changed and we're breaking new ground!

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).

Maintenance Sustainers

Adam Hill (@adamghill), Dan Groshev (@si14), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Tom Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), Christopher Dignam (@chdsbd), and Stefan Hagen (@sthagen).

Not to forget 2 more amazing humans who chose to be generous but anonymous!

Full Changelog

Added

• structlog.stdlib.BoundLogger now has, analogously to our native logger, a full set of async log methods prefixed with an a: await log.ainfo("event!") #502

• The default configuration now respects the presence of FORCE_COLOR (regardless of its value, unless an empty string). This disables all heuristics whether it makes sense to use colors. #503

• The default configuration now respects the presence of NO_COLOR (regardless of its value, unless an empty string). This disables all heuristics whether it makes sense to use colors and overrides FORCE_COLOR. #504

Fixed

• ConsoleRenderer now reuses the _figure_out_exc_info to process the exc_info argument like ExceptionRenderer does. This prevents crashes if the actual Exception is passed for the exc_info argument instead of a tuple or True. #482

• FilteringBoundLogger.aexception() now extracts the exception info using sys.exc_info() before passing control to the asyncio executor (where original exception info is no longer available). #488

22.3.0

Highlights

This is bug-fix release due to overly-zealous string interpolation in the native bound logger. You can now pass anything as event again (but it really should be a string) and log % signs as long as you don't pass positional arguments.

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).

Maintenance Sustainers

@rzijp, Adam Hill (@adamghill), Dan Groshev (@si14), Tamir Bahar (@tmr232), Adi Roiban (@adiroiban), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), Iwan Aucamp (@aucampia), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Thomas Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Jannis Leidel (@jezdez), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), and Christopher Dignam (@chdsbd).

Not to forget 2 more amazing humans who chose to be generous but anonymous!

Full Changlog

Changed

• String interpolation in FilteringBoundLogger (used by default) is now only attempted if positional arguments are passed. This prevents crashes if something different than a string is passed for the event argument. #475

Fixed

• String interpolation doesn't cause crashes in filtered log call anymore. #478

22.2.0

Highlights

This is another (too) big release, but before I go into new features, allow me to beg you to check out structlog's documentation. I've spent easily half of the time on bringing is up to date, restructuring, and adding usage recipes. Not new in this release, but did you know that the standard library chapter has flowcharts that give you as visual explanations of how the various methods work? This is usually the biggest sticking point when starting to use structlog.

Feature-wise the big thing is that structlog's internal (and extremely fast) loggers (the one created using structlog.make_filtering_bound_logger() got two new features that people have asked for forever:

1. String interpolation: log.info("hello %s!", "world") works now!
2. Async! Each logging method has an async version: await log.ainfo("hello %s!", "world") is the same thing as above, but async.

Special Thanks

This release would not be possible without my generous sponsors! Thank you to all of you making sustainable maintenance possible! If you would like to join them, go to https://github.com/sponsors/hynek and check out the sweet perks!

Above and Beyond

Variomedia AG (@variomedia), Tidelift (@tidelift), Sentry (@getsentry), HiredScore (@HiredScore), FilePreviews (@filepreviews), and Daniel Fortunov (@asqui).

Maintenance Sustainers

@rzijp, Adam Hill (@adamghill), Dan Groshev (@si14), Tamir Bahar (@tmr232), Adi Roiban (@adiroiban), Magnus Watn (@magnuswatn), David Cramer (@dcramer), Moving Content AG (@moving-content), Stein Magnus Jodal (@jodal), Iwan Aucamp (@aucampia), ProteinQure (@ProteinQure), Jesse Snyder (@jessesnyder), Rivo Laks (@rivol), Thomas Ballinger (@thomasballinger), @medecau, Ionel Cristian Mărieș (@ionelmc), The Westervelt Company (@westerveltco), Philippe Galvan (@PhilippeGalvan), Birk Jernström (@birkjernstrom), Jannis Leidel (@jezdez), Tim Schilling (@tim-schilling), Chris Withers (@cjw296), and Christopher Dignam (@chdsbd).

Not to forget 2 more amazing humans who chose to be generous but anonymous!

Full Changelog

Deprecated

• Accessing package metadata as attributes on the structlog module is deprecated (e.g. structlog.__version__). Please use importlib.metadata instead (for Python 3.7: the importlib-metadata PyPI package).
• The structlog.types module is now deprecated in favor of the structlog.typing module. It seems like the Python typing community is settling on this name.

Added

• FilteringBoundLogger (used by default) now allows for string interpolation using positional arguments:

  >>> log.info("Hello %s! The answer is %d.", "World", 42, x=1)
  2022-10-07 10:04.31 [info     ] Hello World! The answer is 42. x=1

  #454

• FilteringBoundLogger now also has support for asyncio-based logging. Instead of a wrapper class like structlog.stdlib.AsyncBoundLogger, async equivalents have been added for all logging methods. So instead of log.info("hello") you can also write await log.ainfo("hello") in async functions and methods.

  This seems like the better approach and if it's liked by the community, structlog.stdlib.BoundLogger will get those methods too. #457

Changed

• The documentation has been heavily overhauled. Have a look if you haven't lately! Especially the graphs in the standard library chapter have proven valuable to many.
• The build backend has been switched to Hatch.

Fixed

• The timestamps in the default configuration now use the correct separator (:) for seconds.