Formatters
The purpose of a formatter is to convert a BurinLogRecord
into
(typically) a textual representation of the logging event according to a
specified format.
A BurinFormatter
should be set on every handler, but if a handler
doesn’t have one then a very simple formatter will be used instead.
If multiple logs need to be formatted in a batch for a custom handler then a
BurinBufferingFormatter
can be used or a subclass of it can be created
to meet those needs.
BurinFormatter
The BurinFormatter
is derived from logging.Formatter
and
should function identically in almost all use cases.
Note
All methods of the BurinFormatter
with an underscore_separated
name also have a camelCase alias name which matches the names used in the
standard logging
library.
- class burin.BurinFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)
Formatter for converting a log record for output.
Note
This is a subclass of
logging.Formatter
but has some minor changes (such as raisingFormatError
instead ofValueError
).These changes shouldn’t impact normal usage when compared with the standard
logging
library.Formatters are responsible for converting a log record into (usually) a string which can then be output by a handler.
Below is the attributes of a log record that could be useful to log. Any of these can be added to the format string in whatever formatting style that is selected.
- asctime
Time the log record was created in a human readable format.
- created
Time the log record was created as returned by
time.time()
- filename
Filename from where the logging call was issued.
Note
This is only the filename part; for the whole path see pathname
- funcName
Name of the function where the logging call was issued.
- levelname
Text name for the logging level of the record.
- levelno
Numeric value for logging level of the record.
- lineno
Line number where the logging call was issued.
- message
Log message as processed by
BurinLogRecord.get_message()
method.This is set on the record when
BurinFormatter.format()
is called.- module
Module name where the logging call was issued.
- msecs
Millisecond portion of the time when the log record was created.
- name
Name of the logger that was called.
- pathname
Full pathname of the source file where the logging call was issued.
- process
Process Id
- processName
Process name
- relativeCreated
Time in milliseconds from when the log record was created since the Burin package was loaded.
- taskName
Asyncio task name.
Note
In Python 3.12 this was added to the standard library; it is supported here for all versions of Python compatible with Burin (including versions below 3.12).
However; this will always be None in Python 3.7 as Task names were added in Python 3.8.
- thread
Thread Id
- threadName
Thread name
Note
Some of the attributes may not have values depending on the Python implementation used or the values of
logMultiprocessing
,logProcesses
, andlogThreads
.Note
There are other attributes of log records which are part of its operation and should not need to be formatted. It is recommended to stick to the list above.
The formatter will use the format string and specified style.
You can use datefmt to change how the time and date are formatted, otherwise the default is an ISO8601-like format.
If no format string is provided a simple style-dependent default is used which just includes the message from the log record.
Note
In Python 3.8 validate was added to the standard
logging.Formatter
; it is supported here for all versions of Python compatible with Burin (including versions below 3.8).In Python 3.10 defaults was added to the standard
logging.Formatter
; it is supported here for all versions of Python compatible with Burin (including versions below 3.10).- Parameters:
fmt (str) – The format string to use when formatting a log record. If this is None then a default style-specific format string will be used that has just the log message.
datefmt (str) – The date/time format to use (as accepted by
time.strftime()
). If this is None then a default format similar to the ISO8601 standard is used.style (str) – The type of formatting to use for the format string. Possible values are ‘%’ for %-formatting, ‘{’ for
str.format()
formatting, and ‘$’ forstring.Template
formatting. (Default = ‘%’)validate (bool) – Whether the format should be validated against the style to protect again misconfiguration. (Default = True)
defaults (dict{str: Any}) – A dictionary that provides default values for custom fields. This is a keyword only argument and cannot be passed as a positional argument.
- Raises:
FormatError – If there are errors with the format or style, or if validate is True and validation fails.
- format(record)
Format the record as text.
The record’s attribute dictionary is used for the string formatting operation.
Before the formatting occurs some other steps are taken such as calling
BurinLogRecord.get_message()
to get the complete log message, any time formatting that may be needed, and exception formatting if necessary.- Parameters:
record (BurinLogRecord) – The log record to format.
- Returns:
The log record formatted to text.
- Return type:
- format_time(record, datefmt=None)
Gets the creation time of the specified log record as formatted text.
This should be called by the formatter itself within
BurinFormatter.format()
; it is separated here to simplify overriding how the time is formatted.Note
In Python 3.9 this method was changed on the standard
logging.Formatter
so that the class attribute default_msec_format is optional. This is supported here for all versions of Python compatible with Burin (including versions below 3.9).- Parameters:
record (BurinLogRecord) – The log record to get the time from.
datefmt (str) – The date/time format to use (as accepted by
time.strftime()
). If None then the datefmt passed in during initialization of theBurinFormatter
instance is used.
- Returns:
The formatted date and time of the log record.
- Return type:
BurinBufferingFormatter
This cannot be used by any built-in handlers but provides a class that can be used for formatting a batch of log records at once if needed by a custom handler.
- class burin.BurinBufferingFormatter(linefmt=None)
A formatter that can be used for formatting multiple records in a batch.
Note
This is a subclass of logging.BufferingFormatter and functions identically to it in normal use cases.
This will set a formatter to use for every record.
If no formatter is set then a default formatter is used.
- Parameters:
linefmt (BurinFormatter) – The formatter to use. If this is None then a default formatter will be used. (Default = None)