Skip to main content

Use brace-style string formatting in log messages

Project description

bracelogger

Status Version Python

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:

  1. Change loggers created with logging.getLogger(name) to use bracelogger.get_logger(name)
  2. 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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bracelogger-1.1.1.tar.gz (5.1 kB view details)

Uploaded Source

Built Distribution

bracelogger-1.1.1-py3-none-any.whl (3.8 kB view details)

Uploaded Python 3

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

Hashes for bracelogger-1.1.1.tar.gz
Algorithm Hash digest
SHA256 ace7d1ab1c28a21d4042fb1bc25c1442c6437768a84e42c857ae27c9a4935430
MD5 4e41c116b497079336a6379de67843e3
BLAKE2b-256 54bc8b5638a80857bd24eca79e0d66f5b6ac9eaf4df741a59da74674d8f4b9cc

See more details on using hashes here.

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

Hashes for bracelogger-1.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e77993d7576cac6951da0d5606b9bf421b0b0bedfd5c36582c3622db527b3302
MD5 8938bb0e846d933e5bd59d3dfef703f4
BLAKE2b-256 340fea62010d5a0c1ff8143b2159206bd31810ae901ca3fa7acb59a1018294cf

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page