Lines Matching +full:format +full:- +full:extra +full:- +full:args
1 :mod:`logging` --- Logging facility for Python
7 .. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
8 .. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
19 * :ref:`Basic Tutorial <logging-basic-tutorial>`
20 * :ref:`Advanced Tutorial <logging-advanced-tutorial>`
21 * :ref:`Logging Cookbook <logging-cookbook>`
23 --------------
30 can include your own messages integrated with messages from third-party
35 .. code-block:: none
59 --------------
62 *NEVER* be instantiated directly, but always through the module-level function
66 The ``name`` is potentially a period-separated hierarchical value, like
73 per-module basis using the recommended construction
85 ancestor loggers' handlers - neither the level nor filters of the ancestor
104 should not need to attach a handler to more than one logger - if you just
120 to the parent when the logger is a non-root logger). Note that the root logger
147 This method checks first the module-level level set by
173 .. method:: Logger.debug(msg, *args, **kwargs)
176 message format string, and the *args* are the arguments which are merged into
178 use keywords in the format string, together with a single dictionary argument.)
179 No % formatting operation is performed on *msg* when no *args* are supplied.
182 *exc_info*, *stack_info*, *stacklevel* and *extra*.
185 added to the logging message. If an exception tuple (in the format returned by
202 .. code-block:: none
217 The fourth keyword argument is *extra* which can be used to pass a
219 created for the logging event with user-defined attributes. These custom
223 FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
224 logging.basicConfig(format=FORMAT)
227 logger.warning('Protocol problem: %s', 'connection reset', extra=d)
231 .. code-block:: none
233 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
235 The keys in the dictionary passed in *extra* should not clash with the keys used
236 by the logging system. (See the section on :ref:`logrecord-attributes` for more
241 set up with a format string which expects 'clientip' and 'user' in the attribute
244 you always need to pass the *extra* dictionary with these keys.
247 circumstances, such as multi-threaded servers where the same code executes in
267 .. method:: Logger.info(msg, *args, **kwargs)
273 .. method:: Logger.warning(msg, *args, **kwargs)
280 it - use ``warning`` instead.
282 .. method:: Logger.error(msg, *args, **kwargs)
288 .. method:: Logger.critical(msg, *args, **kwargs)
294 .. method:: Logger.log(level, msg, *args, **kwargs)
300 .. method:: Logger.exception(msg, *args, **kwargs)
339 number, function name and stack information as a 4-element tuple. The stack
355 Logger-level filtering is applied using :meth:`~Logger.filter`.
358 ….. method:: Logger.makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, si…
369 false is found - that will be the last logger which is checked for the
380 --------------
388 +--------------+---------------+
392 +--------------+---------------+
394 +--------------+---------------+
396 +--------------+---------------+
398 +--------------+---------------+
400 +--------------+---------------+
402 +--------------+---------------+
408 ---------------
503 during an :meth:`emit` call. If the module-level attribute
505 what is mostly wanted for a logging system - most users will not care about
513 .. method:: Handler.format(record)
515 Do formatting for a record - if a formatter is set, use it. Otherwise, use the
525 .. warning:: This method is called after a handler-level lock is acquired, which
531 * Logging configuration APIs acquire the module-level lock, and then
532 individual handler-level locks as those handlers are configured.
534 * Many logging APIs lock the module-level lock. If such an API is called
537 module-level lock *before* the handler-level lock, whereas this thread
538 tries to acquire the module-level lock *after* the handler-level lock
539 (because in this method, the handler-level lock has already been acquired).
543 .. _formatter-objects:
546 -----------------
558 A Formatter can be initialized with a format string which makes use of knowledge
559 of the :class:`LogRecord` attributes - such as the default value mentioned above
560 making use of the fact that the user's message and arguments are pre-formatted
561 into a :class:`LogRecord`'s *message* attribute. This format string contains
562 standard Python %-style mapping keys. See section :ref:`old-string-formatting`
566 :ref:`logrecord-attributes`.
572 initialized with a format string for the message as a whole, as well as a
573 format string for the date/time portion of a message. If no *fmt* is
574 specified, ``'%(message)s'`` is used. If no *datefmt* is specified, a format
578 the format string will be merged with its data: using one of %-formatting,
579 :meth:`str.format` or :class:`string.Template`. This only applies to the
580 format string *fmt* (e.g. ``'%(message)s'`` or ``{message}``), not to the
582 :ref:`formatting-styles` for more information on using {- and $-formatting
595 For example: ``logging.Formatter('%(asctime)s - %(message)s', style='{')``.
600 .. method:: format(record)
605 attribute of the record is computed using *msg* % *args*. If the
607 to format the event time. If there is exception information, it is
624 This method should be called from :meth:`format` by a formatter which
628 :func:`time.strftime` to format the creation time of the
629 record. Otherwise, the format '%Y-%m-%d %H:%M:%S,uuu' is used, where the
631 :func:`time.strftime` documentation. An example time in this format is
632 ``2003-01-23 00:29:50,411``. The resulting string is returned.
634 This function uses a user-configurable function to convert the creation
643 Previously, the default format was hard-coded as in this example:
644 ``2010-09-06 22:38:15,292`` where the part before the comma is
645 handled by a strptime format string (``'%Y-%m-%d %H:%M:%S'``), and the
647 have a format placeholder for milliseconds, the millisecond value is
648 appended using another format string, ``'%s,%03d'`` --- and both of these
649 format strings have been hardcoded into this method. With the change,
650 these strings are defined as class-level attributes which can be
652 attributes are ``default_time_format`` (for the strptime format string)
673 A base formatter class suitable for subclassing when you want to format a
675 to use to format each line (that corresponds to a single record). If not
693 .. method:: format(records)
703 --------------
723 yes. If deemed appropriate, the record may be modified in-place by this
753 information into logs (see :ref:`filters-contextual`).
756 .. _log-record:
759 -----------------
767 .. class:: LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None, sinfo=None)
771 The primary information is passed in *msg* and *args*,
772 which are combined using ``msg % args`` to create
799 which can be a %-format string with placeholders for variable data,
800 or an arbitrary object (see :ref:`arbitrary-object-messages`).
803 :param args: Variable data to merge into the *msg* argument
805 :type args: tuple | dict[str, typing.Any]
824 user-supplied arguments with the message. If the user-supplied message
826 convert it to a string. This allows use of user-defined classes as
827 messages, whose ``__str__`` method can return the actual format string to
841 def record_factory(*args, **kwargs):
842 record = old_factory(*args, **kwargs)
854 .. _logrecord-attributes:
857 --------------------
863 the format string. The following table lists (in alphabetical order) the
864 attribute names, their meanings and the corresponding placeholder in a %-style
865 format string.
867 If you are using {}-formatting (:func:`str.format`), you can use
868 ``{attrname}`` as the placeholder in the format string. If you are using
869 $-formatting (:class:`string.Template`), use the form ``${attrname}``. In
873 In the case of {}-formatting, you can specify formatting flags by placing them
875 placeholder of ``{msecs:03d}`` would format a millisecond value of ``4`` as
876 ``004``. Refer to the :meth:`str.format` documentation for full details on
879 +----------------+-------------------------+-----------------------------------------------+
880 | Attribute name | Format | Description |
882 | args | You shouldn't need to | The tuple of arguments merged into ``msg`` to |
883 | | format this yourself. | produce ``message``, or a dict whose values |
886 +----------------+-------------------------+-----------------------------------------------+
887 | asctime | ``%(asctime)s`` | Human-readable time when the |
889 | | | this is of the form '2003-07-08 16:49:45,896' |
892 +----------------+-------------------------+-----------------------------------------------+
895 +----------------+-------------------------+-----------------------------------------------+
897 | | format this yourself. | if no exception has occurred, ``None``. |
898 +----------------+-------------------------+-----------------------------------------------+
900 +----------------+-------------------------+-----------------------------------------------+
902 +----------------+-------------------------+-----------------------------------------------+
906 +----------------+-------------------------+-----------------------------------------------+
911 +----------------+-------------------------+-----------------------------------------------+
914 +----------------+-------------------------+-----------------------------------------------+
916 | | | args``. This is set when |
917 | | | :meth:`Formatter.format` is invoked. |
918 +----------------+-------------------------+-----------------------------------------------+
920 +----------------+-------------------------+-----------------------------------------------+
923 +----------------+-------------------------+-----------------------------------------------+
924 | msg | You shouldn't need to | The format string passed in the original |
925 | | format this yourself. | logging call. Merged with ``args`` to |
927 | | | (see :ref:`arbitrary-object-messages`). |
928 +----------------+-------------------------+-----------------------------------------------+
930 +----------------+-------------------------+-----------------------------------------------+
933 +----------------+-------------------------+-----------------------------------------------+
935 +----------------+-------------------------+-----------------------------------------------+
937 +----------------+-------------------------+-----------------------------------------------+
941 +----------------+-------------------------+-----------------------------------------------+
943 | | format this yourself. | from the bottom of the stack in the current |
947 +----------------+-------------------------+-----------------------------------------------+
949 +----------------+-------------------------+-----------------------------------------------+
951 +----------------+-------------------------+-----------------------------------------------+
957 .. _logger-adapter:
960 ---------------------
964 :ref:`adding contextual information to your logging output <context-info>`.
966 .. class:: LoggerAdapter(logger, extra)
969 underlying :class:`Logger` instance and a dict-like object.
975 passed as *extra* to the constructor and adds it to *kwargs* using key
976 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
999 -------------
1001 The logging module is intended to be thread-safe without any special work
1009 re-entrant, and so cannot be invoked from such signal handlers.
1012 Module-Level Functions
1013 ----------------------
1015 In addition to the classes described above, there are a number of module-level
1023 typically a dot-separated hierarchical name like *'a'*, *'a.b'* or *'a.b.c.d'*.
1054 .. function:: debug(msg, *args, **kwargs)
1057 message format string, and the *args* are the arguments which are merged into
1059 use keywords in the format string, together with a single dictionary argument.)
1063 added to the logging message. If an exception tuple (in the format returned by
1080 .. code-block:: none
1087 The third optional keyword argument is *extra* which can be used to pass a
1089 the logging event with user-defined attributes. These custom attributes can then
1093 FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
1094 logging.basicConfig(format=FORMAT)
1096 logging.warning('Protocol problem: %s', 'connection reset', extra=d)
1100 .. code-block:: none
1102 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
1104 The keys in the dictionary passed in *extra* should not clash with the keys used
1110 set up with a format string which expects 'clientip' and 'user' in the attribute
1113 always need to pass the *extra* dictionary with these keys.
1116 circumstances, such as multi-threaded servers where the same code executes in
1129 .. function:: info(msg, *args, **kwargs)
1135 .. function:: warning(msg, *args, **kwargs)
1142 it - use ``warning`` instead.
1145 .. function:: error(msg, *args, **kwargs)
1151 .. function:: critical(msg, *args, **kwargs)
1157 .. function:: exception(msg, *args, **kwargs)
1163 .. function:: log(level, msg, *args, **kwargs)
1200 section on :ref:`custom-levels`.
1231 ``%(levelname)s`` format specifier (see :ref:`logrecord-attributes`), and
1270 +--------------+---------------------------------------------+
1271 | Format | Description |
1276 +--------------+---------------------------------------------+
1280 +--------------+---------------------------------------------+
1281 | *format* | Use the specified format string for the |
1285 +--------------+---------------------------------------------+
1286 | *datefmt* | Use the specified date/time format, as |
1288 +--------------+---------------------------------------------+
1289 | *style* | If *format* is specified, use this style |
1290 | | for the format string. One of ``'%'``, |
1291 | | ``'{'`` or ``'$'`` for :ref:`printf-style |
1292 | | <old-string-formatting>`, |
1293 | | :meth:`str.format` or |
1296 +--------------+---------------------------------------------+
1299 +--------------+---------------------------------------------+
1302 | | argument is incompatible with *filename* - |
1305 +--------------+---------------------------------------------+
1312 | | with *filename* or *stream* - if both |
1314 +--------------+---------------------------------------------+
1320 +--------------+---------------------------------------------+
1325 +--------------+---------------------------------------------+
1335 +--------------+---------------------------------------------+
1387 ``factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, **kwargs)``
1394 :args: The arguments for the logging message.
1403 Module-Level Attributes
1404 -----------------------
1419 ------------------------------------
1447 :pep:`282` - A Logging System
1451 `Original Python logging package <https://old.red-dove.com/python_logging.html>`_