Description: Formatter Objects
Keywords: lib

## 6.28.3 Formatter Objects

`Formatter`s have the following attributes and methods. They are responsible for converting a `LogRecord` to (usually) a string which can be interpreted by either a human or an external system. The base `Formatter` allows a formatting string to be specified. If none is supplied, the default value of `'%(message)s'` is used.

A Formatter can be initialized with a format string which makes use of knowledge of the `LogRecord` attributes - such as the default value mentioned above making use of the fact that the user's message and arguments are pre-formatted into a LogRecord's message attribute. This format string contains standard python %-style mapping keys. See section 2.3.6, ``String Formatting Operations,'' for more information on string formatting.

Currently, the useful mapping keys in a LogRecord are:

Format | Description
--- | ---
`%(name)s` | Name of the logger (logging channel).
`%(levelno)s` | Numeric logging level for the message (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).
`%(levelname)s` | Text logging level for the message (`'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`, `'CRITICAL'`).
`%(pathname)s` | Full pathname of the source file where the logging call was issued (if available).
`%(filename)s` | Filename portion of pathname.
`%(module)s` | Module (name portion of filename).
`%(lineno)d` | Source line number where the logging call was issued (if available).
`%(created)f` | Time when the LogRecord was created (as returned by `time.time()`).
`%(asctime)s` | Human-readable time when the LogRecord was created. By default this is of the form ``2003-07-08 16:49:45,896'' (the numbers after the comma are millisecond portion of the time).
`%(msecs)d` | Millisecond portion of the time when the `LogRecord` was created.
`%(thread)d` | Thread ID (if available).
`%(process)d` | Process ID (if available).
`%(message)s` | The logged message, computed as `msg % args`.

class `Formatter`( | [fmt[, datefmt]])

  Returns a new instance of the `Formatter` class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, `'%(message)s'` is used. If no datefmt is specified, the ISO8601 date format is used.

`format`( | record)

  The record's attribute dictionary is used as the operand to a string formatting operation. Returns the resulting string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using msg % args. If the formatting string contains `'(asctime)'`, `formatTime()` is called to format the event time. If there is exception information, it is formatted using `formatException()` and appended to the message.

`formatTime`( | record[, datefmt])

  This method should be called from `format()` by a formatter which wants to make use of a formatted time. This method can be overridden in formatters to provide for any specific requirement, but the basic behavior is as follows: if datefmt (a string) is specified, it is used with `time.strftime()` to format the creation time of the record. Otherwise, the ISO8601 format is used. The resulting string is returned.

`formatException`( | exc_info)

  Formats the specified exception information (a standard exception tuple as returned by `sys.exc_info()`) as a string. This default implementation just uses `traceback.print_exception()`. The resulting string is returned.