mirror of
https://github.com/python/cpython.git
synced 2025-08-02 16:13:13 +00:00
gh-94700: Rewrite the logging.Formatter API ref in structured form (GH-94701)
This commit is contained in:
parent
6442a9dd21
commit
761eeb62a9
1 changed files with 40 additions and 42 deletions
|
@ -531,55 +531,53 @@ Formatter Objects
|
|||
|
||||
.. currentmodule:: logging
|
||||
|
||||
:class:`Formatter` objects have the following attributes and methods. They are
|
||||
responsible for converting a :class:`LogRecord` to (usually) a string which can
|
||||
be interpreted by either a human or an external system. The base
|
||||
:class:`Formatter` allows a formatting string to be specified. If none is
|
||||
supplied, the default value of ``'%(message)s'`` is used, which just includes
|
||||
the message in the logging call. To have additional items of information in the
|
||||
formatted output (such as a timestamp), keep reading.
|
||||
|
||||
A Formatter can be initialized with a format string which makes use of knowledge
|
||||
of the :class:`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 :class:`LogRecord`'s *message* attribute. This format string contains
|
||||
standard Python %-style mapping keys. See section :ref:`old-string-formatting`
|
||||
for more information on string formatting.
|
||||
|
||||
The useful mapping keys in a :class:`LogRecord` are given in the section on
|
||||
:ref:`logrecord-attributes`.
|
||||
|
||||
|
||||
.. class:: Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)
|
||||
|
||||
Returns a new instance of the :class:`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, a format
|
||||
is used which is described in the :meth:`formatTime` documentation.
|
||||
Responsible for converting a :class:`LogRecord` to an output string
|
||||
to be interpreted by a human or external system.
|
||||
|
||||
The *style* parameter can be one of '%', '{' or '$' and determines how
|
||||
the format string will be merged with its data: using one of %-formatting,
|
||||
:meth:`str.format` or :class:`string.Template`. This only applies to the
|
||||
format string *fmt* (e.g. ``'%(message)s'`` or ``{message}``), not to the
|
||||
actual log messages passed to ``Logger.debug`` etc; see
|
||||
:ref:`formatting-styles` for more information on using {- and $-formatting
|
||||
for log messages.
|
||||
:param fmt: A format string in the given *style* for
|
||||
the logged output as a whole.
|
||||
The possible mapping keys are drawn from the :class:`LogRecord` object's
|
||||
:ref:`logrecord-attributes`.
|
||||
If not specified, ``'%(message)s'`` is used,
|
||||
which is just the logged message.
|
||||
:type fmt: str
|
||||
|
||||
The *defaults* parameter can be a dictionary with default values to use in
|
||||
custom fields. For example:
|
||||
``logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})``
|
||||
:param datefmt: A format string in the given *style* for
|
||||
the date/time portion of the logged output.
|
||||
If not specified, the default described in :meth:`formatTime` is used.
|
||||
:type datefmt: str
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The *style* parameter was added.
|
||||
:param style: Can be one of ``'%'``, ``'{'`` or ``'$'`` and determines
|
||||
how the format string will be merged with its data: using one of
|
||||
:ref:`old-string-formatting` (``%``), :meth:`str.format` (``{``)
|
||||
or :class:`string.Template` (``$``). This only applies to
|
||||
*fmt* and *datefmt* (e.g. ``'%(message)s'`` versus ``'{message}'``),
|
||||
not to the actual log messages passed to the logging methods.
|
||||
However, there are :ref:`other ways <formatting-styles>`
|
||||
to use ``{``- and ``$``-formatting for log messages.
|
||||
:type style: str
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
The *validate* parameter was added. Incorrect or mismatched style and fmt
|
||||
will raise a ``ValueError``.
|
||||
For example: ``logging.Formatter('%(asctime)s - %(message)s', style='{')``.
|
||||
:param validate: If ``True`` (the default), incorrect or mismatched
|
||||
*fmt* and *style* will raise a :exc:`ValueError`; for example,
|
||||
``logging.Formatter('%(asctime)s - %(message)s', style='{')``.
|
||||
:type validate: bool
|
||||
|
||||
:param defaults: A dictionary with default values to use in custom fields.
|
||||
For example,
|
||||
``logging.Formatter('%(ip)s %(message)s', defaults={"ip": None})``
|
||||
:type defaults: dict[str, Any]
|
||||
|
||||
.. versionadded:: 3.2
|
||||
The *style* parameter.
|
||||
|
||||
.. versionadded:: 3.8
|
||||
The *validate* parameter.
|
||||
|
||||
.. versionadded:: 3.10
|
||||
The *defaults* parameter.
|
||||
|
||||
.. versionchanged:: 3.10
|
||||
The *defaults* parameter was added.
|
||||
|
||||
.. method:: format(record)
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue