Use brace-style string formatting in log messages
Project description
bracelogger
A Python library that enables using the brace-style string formatting in log messages.
Features:
- Supports a wide range of Python versions (v2.7 - v3.12)
- No dependencies
- Easy to use - no special syntax required
- Easy to transition to from stdlib logging - just change the
logging.getLogger
calls and message templates. - Only enables brace-style formatting for loggers created by the library. This allows for gradually transitioning to brace-style formatting without breaking existing loggers or third party packages.
- The formatting of the message is delayed until it is output (or not at all if the log message is filtered).
- The args passed into the log call are stored on the
logging.LogRecord
objects as usual.
Installation
pip install bracelogger
Usage example
# import the library
from bracelogger import get_logger
# set up the logger
__log__ = get_logger(__name__)
# use brace-style formatting in log messages
try:
process(some_obj)
except Exception:
__log__.warning(
"Failed to process object '{0!r}' with name '{0.name}' and path '{0.path}'",
some_obj,
exc_info=True
)
Note that the above example is very basic. The real power of this module comes from being able to use the more advanced operations that the brace-style formatting can provide. See the docs on the format string syntax for more details.
Key-based formatting
The logger from the standard library has a special case (introduced in Python 2.4) where key-based formatting can be used when a single non-empty dictionary is passed into the log message like so:
__log__.info("a:%(a)s, b:%(b)s", {"a": 1, "b": 2})
This is also supported when using brace-style formatting:
# These both produce the same log message:
__log__.info("a:{a}, b:{b}", {"a": 1, "b": 2})
__log__.info("a:{0[a]}, b:{0[b]}", {"a": 1, "b": 2})
Compatibility with existing code and loggers
This library will only enable brace-style formatting for loggers created by this module's
get_logger()
function. Loggers created via the stdlib logging.getLogger()
function will still
use the normal %-based formatting.
This opt-in style means that codebases can gradually transition to brace-style logging without having to convert everything over all at once. It also means that the logs from any third-party code like libraries will continue to work as normal.
In addition to being compatible with existing code, it should also be compatible with most other stdlib-compatible logging packages and modifications. As when using the stdlib logger, the message arguments are still stored on the log record and the message is only formatted when it is handled (and not at all if the message is filtered).
Converting existing code
Because there is no special syntax required, migrating existing logs to brace-style formatting is easy:
- Change loggers created with
logging.getLogger(name)
to usebracelogger.get_logger(name)
- Change the log messages for the loggers to use brace-style formatting (ex: change
%s
to{}
)
Tests
This package contains basic tests. To run them, install pytest
(pip install pytest
) and run
py.test
in the project directory.
License
Licensed under the GNU LGPLv3.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file bracelogger-1.1.1.tar.gz
.
File metadata
- Download URL: bracelogger-1.1.1.tar.gz
- Upload date:
- Size: 5.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.0 CPython/3.12.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ace7d1ab1c28a21d4042fb1bc25c1442c6437768a84e42c857ae27c9a4935430 |
|
MD5 | 4e41c116b497079336a6379de67843e3 |
|
BLAKE2b-256 | 54bc8b5638a80857bd24eca79e0d66f5b6ac9eaf4df741a59da74674d8f4b9cc |
File details
Details for the file bracelogger-1.1.1-py3-none-any.whl
.
File metadata
- Download URL: bracelogger-1.1.1-py3-none-any.whl
- Upload date:
- Size: 3.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.0 CPython/3.12.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | e77993d7576cac6951da0d5606b9bf421b0b0bedfd5c36582c3622db527b3302 |
|
MD5 | 8938bb0e846d933e5bd59d3dfef703f4 |
|
BLAKE2b-256 | 340fea62010d5a0c1ff8143b2159206bd31810ae901ca3fa7acb59a1018294cf |