Metadata-Version: 2.4
Name: tstringlogger
Version: 1.1.0
Summary: Add support for using t-strings for logging
Project-URL: Repository, https://github.com/pR0Ps/tstringlogger.git
Project-URL: Changelog, https://github.com/pR0Ps/tstringlogger/blob/master/CHANGELOG.md
License-Expression: LGPL-3.0-only
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.14
Description-Content-Type: text/markdown

tstringlogger
=============

Adds support for using t-strings in log messages while preserving all interpolated values.

Usage example:
```python
>>> import logging
>>> from tstringlogger import TStringLogRecord
>>> test1, test2 = "hello", "world"
>>>
>>> # Set the default log record factory to one that supports t-strings
>>> logging.setLogRecordFactory(TStringLogRecord)
>>>
>>> logging.info(t"{test1=}, {test2}")
INFO:root:test1='hello', world
>>>
>>> # Standard logging still works normally
>>> logging.info("test1=%r, %s", test1, test2)
INFO:root:test1='hello', world
```

In this example the log record that was produced by the t-string message will have the data from
the t-string available as `record.args`. In this case that would be:
`{"test1": "hello", "test2": "world"}`.

Extracting these values from the t-string allows other parts of the logging system to use the
values just as if they were provided as parameters to a normal logging call.

> [!NOTE]
> The request to add native t-string logging support to the standard library can be found here:
> https://github.com/python/cpython/issues/134394


Alternative methods
-------------------

### Using the `TStringLogRecordMixin`

If your application already uses a custom `LogRecord` class, the `TStringLogRecordMixin` can be used
to easily add t-string functionality to it.

```python
>>> import logging
>>> from tstringlogger import TStringLogRecordMixin
>>>
>>> # example custom logger that adds a tag to every message
>>> class MyCustomLogRecord(TStringLogRecordMixin, logging.LogRecord):
...     def getMessage(self):
...         msg = super().getMessage()  # get the formatting t-string
...         return f"[tag] {msg}"
>>>
>>> logging.setLogRecordFactory(MyCustomLogRecord)
>>> test1, test2 = "hello", "world"
>>> logging.info(t"{test1=}, {test2}")
INFO:root:[tag] test1='hello', world
```

### Globally enable t-string support

Support for t-string logging can be globally enabled/disabled by calling
`tstringlogger.enable()`/`tstringlogger.disable()`. This adds support for t-strings by directly
patching the `LogRecord.__init__` and `LogRecord.getMessage` functions.

```python
>>> import logging
>>> import tstringlogger
>>>
>>> tstringlogger.enable()  # apply patches
>>>
>>> test1, test2 = "hello", "world"
>>> logging.info(t"{test1=}, {test2}")
INFO:root:test1='hello', world
>>>
>>> tstringlogger.disable()  # remove patches
>>> logging.info(t"{test1=}, {test2}")
INFO:root:Template(strings=('test1=', ', ', ''), interpolations=(Interpolation...
```

Related work
------------
[bracelogger](https://github.com/pR0Ps/bracelogger) is a library that allows using new-style string
formatting in log messages instead of `%`-based formatting.
