Skip to content

Commit

Permalink
Document new string interpolation behavior
Browse files Browse the repository at this point in the history
  • Loading branch information
hynek committed Nov 24, 2022
1 parent fc60f2f commit 968523e
Show file tree
Hide file tree
Showing 2 changed files with 5 additions and 1 deletion.
3 changes: 2 additions & 1 deletion docs/bound-loggers.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ Now `log` is a *bound logger* of type {class}`~structlog.typing.FilteringBoundLo

Now if you call `log.info("Hello, %s!", "world", number=42)` the following happens:

1. `"world"` gets interpolated into `"Hello, %s!"`, making the event "Hello, world!".
1. `"world"` gets interpolated into `"Hello, %s!"`, making the event "Hello, world!"[^interpolation].
2. The *bound logger*'s context gets copied and the key-value pairs from the `info` call are added to it.
It becomes an *event dict* and is `{"foo": "bar", "number": 42}` now.
3. The event from step 1 is added too.
Expand All @@ -99,6 +99,7 @@ Now if you call `log.info("Hello, %s!", "world", number=42)` the following happe
By replacing the last processor, you decide on the **format** of your logs.
For example, if you wanted JSON logs, you just have to replace the last processor with {class}`structlog.processors.JSONRenderer`.

[^interpolation]: String interpolation only takes place if you pass positional arguments.

(filtering)=

Expand Down
3 changes: 3 additions & 0 deletions src/structlog/typing.py
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,9 @@ class FilteringBoundLogger(BindableLogger, Protocol):
String interpolation using positional arguments.
.. versionadded:: 22.2.0
Async variants ``alog()``, ``adebug()``, ``ainfo()``, and so forth.
.. versionchanged:: 22.3.0
String interpolation is only attempted if positional arguments are
passed.
"""

def bind(self, **new_values: Any) -> FilteringBoundLogger:
Expand Down

0 comments on commit 968523e

Please sign in to comment.