python-docs-fr/howto/logging-cookbook.po at 2.7 · python/python-docs-fr

844 lines (724 loc) · 33.2 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 1990-2016, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
"Project-Id-Version: Python 2.7\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2016-10-30 10:44+0100\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
#: ../Doc/howto/logging-cookbook.rst:5
msgid "Logging Cookbook"
#: ../Doc/howto/logging-cookbook.rst:7
msgid "Vinay Sajip <vinay_sajip at red-dove dot com>"
msgstr "Vinay Sajip <vinay_sajip at red-dove dot com>"
#: ../Doc/howto/logging-cookbook.rst:9
"This page contains a number of recipes related to logging, which have been "
"found useful in the past."
#: ../Doc/howto/logging-cookbook.rst:15
msgid "Using logging in multiple modules"
#: ../Doc/howto/logging-cookbook.rst:17
"Multiple calls to ``logging.getLogger('someLogger')`` return a reference to "
"the same logger object.  This is true not only within the same module, but "
"also across modules as long as it is in the same Python interpreter "
"process.  It is true for references to the same object; additionally, "
"application code can define and configure a parent logger in one module and "
"create (but not configure) a child logger in a separate module, and all "
"logger calls to the child will pass up to the parent.  Here is a main "
#: ../Doc/howto/logging-cookbook.rst:55
msgid "Here is the auxiliary module::"
#: ../Doc/howto/logging-cookbook.rst:75
msgid "The output looks like this::"
#: ../Doc/howto/logging-cookbook.rst:99
msgid "Logging from multiple threads"
#: ../Doc/howto/logging-cookbook.rst:101
"Logging from multiple threads requires no special effort. The following "
"example shows logging from the main (initIal) thread and another thread::"
#: ../Doc/howto/logging-cookbook.rst:130
msgid "When run, the script should print something like the following::"
#: ../Doc/howto/logging-cookbook.rst:150
"This shows the logging output interspersed as one might expect. This "
"approach works for more threads than shown here, of course."
#: ../Doc/howto/logging-cookbook.rst:154
msgid "Multiple handlers and formatters"
#: ../Doc/howto/logging-cookbook.rst:156
"Loggers are plain Python objects.  The :meth:`~Logger.addHandler` method has "
"no minimum or maximum quota for the number of handlers you may add.  "
"Sometimes it will be beneficial for an application to log all messages of "
"all severities to a text file while simultaneously logging errors or above "
"to the console.  To set this up, simply configure the appropriate handlers.  "
"The logging calls in the application code will remain unchanged.  Here is a "
"slight modification to the previous simple module-based configuration "
"example::"
#: ../Doc/howto/logging-cookbook.rst:189
"Notice that the 'application' code does not care about multiple handlers.  "
"All that changed was the addition and configuration of a new handler named "
#: ../Doc/howto/logging-cookbook.rst:192
"The ability to create new handlers with higher- or lower-severity filters "
"can be very helpful when writing and testing an application.  Instead of "
"using many ``print`` statements for debugging, use ``logger.debug``: Unlike "
"the print statements, which you will have to delete or comment out later, "
"the logger.debug statements can remain intact in the source code and remain "
"dormant until you need them again.  At that time, the only change that needs "
"to happen is to modify the severity level of the logger and/or handler to "
#: ../Doc/howto/logging-cookbook.rst:203
msgid "Logging to multiple destinations"
#: ../Doc/howto/logging-cookbook.rst:205
"Let's say you want to log to console and file with different message formats "
"and in differing circumstances. Say you want to log messages with levels of "
"DEBUG and higher to file, and those messages at level INFO and higher to the "
"console. Let's also assume that the file should contain timestamps, but the "
"console messages should not. Here's how you can achieve this::"
#: ../Doc/howto/logging-cookbook.rst:243
msgid "When you run this, on the console you will see ::"
#: ../Doc/howto/logging-cookbook.rst:250
msgid "and in the file you will see something like ::"
#: ../Doc/howto/logging-cookbook.rst:258
"As you can see, the DEBUG message only shows up in the file. The other "
"messages are sent to both destinations."
#: ../Doc/howto/logging-cookbook.rst:261
"This example uses console and file handlers, but you can use any number and "
"combination of handlers you choose."
#: ../Doc/howto/logging-cookbook.rst:266
msgid "Configuration server example"
#: ../Doc/howto/logging-cookbook.rst:268
msgid "Here is an example of a module using the logging configuration server::"
#: ../Doc/howto/logging-cookbook.rst:299
"And here is a script that takes a filename and sends that file to the "
"server, properly preceded with the binary-encoded length, as the new logging "
"configuration::"
#: ../Doc/howto/logging-cookbook.rst:324
msgid "Sending and receiving logging events across a network"
#: ../Doc/howto/logging-cookbook.rst:326
"Let's say you want to send logging events across a network, and handle them "
"at the receiving end. A simple way of doing this is attaching a :class:"
"`SocketHandler` instance to the root logger at the sending end::"
#: ../Doc/howto/logging-cookbook.rst:354
"At the receiving end, you can set up a receiver using the :mod:"
"`SocketServer` module. Here is a basic working example::"
#: ../Doc/howto/logging-cookbook.rst:442
"First run the server, and then the client. On the client side, nothing is "
"printed on the console; on the server side, you should see something like::"
#: ../Doc/howto/logging-cookbook.rst:452
"Note that there are some security issues with pickle in some scenarios. If "
"these affect you, you can use an alternative serialization scheme by "
"overriding the :meth:`~handlers.SocketHandler.makePickle` method and "
"implementing your alternative there, as well as adapting the above script to "
"use your alternative serialization."
#: ../Doc/howto/logging-cookbook.rst:462
msgid "Adding contextual information to your logging output"
#: ../Doc/howto/logging-cookbook.rst:466
"Sometimes you want logging output to contain contextual information in "
"addition to the parameters passed to the logging call. For example, in a "
"networked application, it may be desirable to log client-specific "
"information in the log (e.g. remote client's username, or IP address). "
"Although you could use the *extra* parameter to achieve this, it's not "
"always convenient to pass the information in this way. While it might be "
"tempting to create :class:`Logger` instances on a per-connection basis, this "
"is not a good idea because these instances are not garbage collected. While "
"this is not a problem in practice, when the number of :class:`Logger` "
"instances is dependent on the level of granularity you want to use in "
"logging an application, it could be hard to manage if the number of :class:"
"`Logger` instances becomes effectively unbounded."
#: ../Doc/howto/logging-cookbook.rst:481
msgid "Using LoggerAdapters to impart contextual information"
#: ../Doc/howto/logging-cookbook.rst:483
"An easy way in which you can pass contextual information to be output along "
"with logging event information is to use the :class:`LoggerAdapter` class. "
"This class is designed to look like a :class:`Logger`, so that you can call :"
"meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:"
"`exception`, :meth:`critical` and :meth:`log`. These methods have the same "
"signatures as their counterparts in :class:`Logger`, so you can use the two "
"types of instances interchangeably."
#: ../Doc/howto/logging-cookbook.rst:491
"When you create an instance of :class:`LoggerAdapter`, you pass it a :class:"
"`Logger` instance and a dict-like object which contains your contextual "
"information. When you call one of the logging methods on an instance of :"
"class:`LoggerAdapter`, it delegates the call to the underlying instance of :"
"class:`Logger` passed to its constructor, and arranges to pass the "
"contextual information in the delegated call. Here's a snippet from the code "
"of :class:`LoggerAdapter`::"
#: ../Doc/howto/logging-cookbook.rst:507
"The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where "
"the contextual information is added to the logging output. It's passed the "
"message and keyword arguments of the logging call, and it passes back "
"(potentially) modified versions of these to use in the call to the "
"underlying logger. The default implementation of this method leaves the "
"message alone, but inserts an 'extra' key in the keyword argument whose "
"value is the dict-like object passed to the constructor. Of course, if you "
"had passed an 'extra' keyword argument in the call to the adapter, it will "
"be silently overwritten."
#: ../Doc/howto/logging-cookbook.rst:516
"The advantage of using 'extra' is that the values in the dict-like object "
"are merged into the :class:`LogRecord` instance's __dict__, allowing you to "
"use customized strings with your :class:`Formatter` instances which know "
"about the keys of the dict-like object. If you need a different method, e.g. "
"if you want to prepend or append the contextual information to the message "
"string, you just need to subclass :class:`LoggerAdapter` and override :meth:"
"`~LoggerAdapter.process` to do what you need. Here is a simple example::"
#: ../Doc/howto/logging-cookbook.rst:532
msgid "which you can use like this::"
#: ../Doc/howto/logging-cookbook.rst:537
"Then any events that you log to the adapter will have the value of "
"``some_conn_id`` prepended to the log messages."
#: ../Doc/howto/logging-cookbook.rst:541
msgid "Using objects other than dicts to pass contextual information"
#: ../Doc/howto/logging-cookbook.rst:543
"You don't need to pass an actual dict to a :class:`LoggerAdapter` - you "
"could pass an instance of a class which implements ``__getitem__`` and "
"``__iter__`` so that it looks like a dict to logging. This would be useful "
"if you want to generate values dynamically (whereas the values in a dict "
"would be constant)."
#: ../Doc/howto/logging-cookbook.rst:552
msgid "Using Filters to impart contextual information"
#: ../Doc/howto/logging-cookbook.rst:554
"You can also add contextual information to log output using a user-defined :"
"class:`Filter`. ``Filter`` instances are allowed to modify the "
"``LogRecords`` passed to them, including adding additional attributes which "
"can then be output using a suitable format string, or if needed a custom :"
"class:`Formatter`."
#: ../Doc/howto/logging-cookbook.rst:559
"For example in a web application, the request being processed (or at least, "
"the interesting parts of it) can be stored in a threadlocal (:class:"
"`threading.local`) variable, and then accessed from a ``Filter`` to add, "
"say, information from the request - say, the remote IP address and remote "
"user's username - to the ``LogRecord``, using the attribute names 'ip' and "
"'user' as in the ``LoggerAdapter`` example above. In that case, the same "
"format string can be used to get similar output to that shown above. Here's "
"an example script::"
#: ../Doc/howto/logging-cookbook.rst:605
msgid "which, when run, produces something like::"
#: ../Doc/howto/logging-cookbook.rst:624
msgid "Logging to a single file from multiple processes"
#: ../Doc/howto/logging-cookbook.rst:626
"Although logging is thread-safe, and logging to a single file from multiple "
"threads in a single process *is* supported, logging to a single file from "
"*multiple processes* is *not* supported, because there is no standard way to "
"serialize access to a single file across multiple processes in Python. If "
"you need to log to a single file from multiple processes, one way of doing "
"this is to have all the processes log to a :class:`~handlers.SocketHandler`, "
"and have a separate process which implements a socket server which reads "
"from the socket and logs to file. (If you prefer, you can dedicate one "
"thread in one of the existing processes to perform this function.) :ref:"
"`This section <network-logging>` documents this approach in more detail and "
"includes a working socket receiver which can be used as a starting point for "
"you to adapt in your own applications."
#: ../Doc/howto/logging-cookbook.rst:639
"If you are using a recent version of Python which includes the :mod:"
"`multiprocessing` module, you could write your own handler which uses the :"
"class:`~multiprocessing.Lock` class from this module to serialize access to "
"the file from your processes. The existing :class:`FileHandler` and "
"subclasses do not make use of :mod:`multiprocessing` at present, though they "
"may do so in the future. Note that at present, the :mod:`multiprocessing` "
"module does not provide working lock functionality on all platforms (see "
"https://bugs.python.org/issue3770)."
#: ../Doc/howto/logging-cookbook.rst:650
msgid "Using file rotation"
#: ../Doc/howto/logging-cookbook.rst:655
"Sometimes you want to let a log file grow to a certain size, then open a new "
"file and log to that. You may want to keep a certain number of these files, "
"and when that many files have been created, rotate the files so that the "
"number of files and the size of the files both remain bounded. For this "
"usage pattern, the logging package provides a :class:`~handlers."
"RotatingFileHandler`::"
#: ../Doc/howto/logging-cookbook.rst:687
"The result should be 6 separate files, each with part of the log history for "
"the application::"
#: ../Doc/howto/logging-cookbook.rst:697
"The most current file is always :file:`logging_rotatingfile_example.out`, "
"and each time it reaches the size limit it is renamed with the suffix "
"``.1``. Each of the existing backup files is renamed to increment the suffix "
"(``.1`` becomes ``.2``, etc.)  and the ``.6`` file is erased."
#: ../Doc/howto/logging-cookbook.rst:702
"Obviously this example sets the log length much too small as an extreme "
"example.  You would want to set *maxBytes* to an appropriate value."
#: ../Doc/howto/logging-cookbook.rst:706
msgid "An example dictionary-based configuration"
#: ../Doc/howto/logging-cookbook.rst:708
"Below is an example of a logging configuration dictionary - it's taken from "
"the `documentation on the Django project <https://docs.djangoproject.com/"
"en/1.9/topics/logging/#configuring-logging>`_. This dictionary is passed to :"
"func:`~config.dictConfig` to put the configuration into effect::"
#: ../Doc/howto/logging-cookbook.rst:764
"For more information about this configuration, you can see the `relevant "
"section <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-"
"logging>`_ of the Django documentation."
#: ../Doc/howto/logging-cookbook.rst:769
msgid "Inserting a BOM into messages sent to a SysLogHandler"
#: ../Doc/howto/logging-cookbook.rst:771
"`RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ requires that a Unicode "
"message be sent to a syslog daemon as a set of bytes which have the "
"following structure: an optional pure-ASCII component, followed by a UTF-8 "
"Byte Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the "
"`relevant section of the specification <https://tools.ietf.org/html/"
"rfc5424#section-6>`_.)"
#: ../Doc/howto/logging-cookbook.rst:777
"In Python 2.6 and 2.7, code was added to :class:`~logging.handlers."
"SysLogHandler` to insert a BOM into the message, but unfortunately, it was "
"implemented incorrectly, with the BOM appearing at the beginning of the "
"message and hence not allowing any pure-ASCII component to appear before it."
#: ../Doc/howto/logging-cookbook.rst:783
"As this behaviour is broken, the incorrect BOM insertion code is being "
"removed from Python 2.7.4 and later. However, it is not being replaced, and "
"if you want to produce RFC 5424-compliant messages which include a BOM, an "
"optional pure-ASCII sequence before it and arbitrary Unicode after it, "
"encoded using UTF-8, then you need to do the following:"
#: ../Doc/howto/logging-cookbook.rst:789
"Attach a :class:`~logging.Formatter` instance to your :class:`~logging."
"handlers.SysLogHandler` instance, with a format string such as::"
#: ../Doc/howto/logging-cookbook.rst:795
"The Unicode code point ``u'\\ufeff'``, when encoded using UTF-8, will be "
"encoded as a UTF-8 BOM -- the byte-string ``'\\xef\\xbb\\xbf'``."
#: ../Doc/howto/logging-cookbook.rst:798
"Replace the ASCII section with whatever placeholders you like, but make sure "
"that the data that appears in there after substitution is always ASCII (that "
"way, it will remain unchanged after UTF-8 encoding)."
#: ../Doc/howto/logging-cookbook.rst:802
"Replace the Unicode section with whatever placeholders you like; if the data "
"which appears there after substitution contains characters outside the ASCII "
"range, that's fine -- it will be encoded using UTF-8."
#: ../Doc/howto/logging-cookbook.rst:806
"If the formatted message is Unicode, it *will* be encoded using UTF-8 "
"encoding by ``SysLogHandler``. If you follow the above rules, you should be "
"able to produce RFC 5424-compliant messages. If you don't, logging may not "
"complain, but your messages will not be RFC 5424-compliant, and your syslog "
"daemon may complain."
#: ../Doc/howto/logging-cookbook.rst:814
msgid "Implementing structured logging"
#: ../Doc/howto/logging-cookbook.rst:816
"Although most logging messages are intended for reading by humans, and thus "
"not readily machine-parseable, there might be cirumstances where you want to "
"output messages in a structured format which *is* capable of being parsed by "
"a program (without needing complex regular expressions to parse the log "
"message). This is straightforward to achieve using the logging package. "
"There are a number of ways in which this could be achieved, but the "
"following is a simple approach which uses JSON to serialise the event in a "
"machine-parseable manner::"
#: ../Doc/howto/logging-cookbook.rst:840
msgid "If the above script is run, it prints::"
#: ../Doc/howto/logging-cookbook.rst:844 ../Doc/howto/logging-cookbook.rst:891
"Note that the order of items might be different according to the version of "
"Python used."
#: ../Doc/howto/logging-cookbook.rst:847
"If you need more specialised processing, you can use a custom JSON encoder, "
"as in the following complete example::"
#: ../Doc/howto/logging-cookbook.rst:887
msgid "When the above script is run, it prints::"
#: ../Doc/howto/logging-cookbook.rst:900
msgid "Customizing handlers with :func:`dictConfig`"
#: ../Doc/howto/logging-cookbook.rst:902
"There are times when you want to customize logging handlers in particular "
"ways, and if you use :func:`dictConfig` you may be able to do this without "
"subclassing. As an example, consider that you may want to set the ownership "
"of a log file. On POSIX, this is easily done using :func:`os.chown`, but the "
"file handlers in the stdlib don't offer built-in support. You can customize "
"handler creation using a plain function such as::"
#: ../Doc/howto/logging-cookbook.rst:921
"You can then specify, in a logging configuration passed to :func:"
"`dictConfig`, that a logging handler be created by calling this function::"
#: ../Doc/howto/logging-cookbook.rst:954
"In this example I am setting the ownership using the ``pulse`` user and "
"group, just for the purposes of illustration. Putting it together into a "
"working script, ``chowntest.py``::"
#: ../Doc/howto/logging-cookbook.rst:1001
msgid "To run this, you will probably need to run as ``root``:"
#: ../Doc/howto/logging-cookbook.rst:1011
"Note that this example uses Python 3.3 because that's where :func:`shutil."
"chown` makes an appearance. This approach should work with any Python "
"version that supports :func:`dictConfig` - namely, Python 2.7, 3.2 or later. "
"With pre-3.3 versions, you would need to implement the actual ownership "
"change using e.g. :func:`os.chown`."
#: ../Doc/howto/logging-cookbook.rst:1017
"In practice, the handler-creating function may be in a utility module "
"somewhere in your project. Instead of the line in the configuration::"
#: ../Doc/howto/logging-cookbook.rst:1022
msgid "you could use e.g.::"
#: ../Doc/howto/logging-cookbook.rst:1026
"where ``project.util`` can be replaced with the actual name of the package "
"where the function resides. In the above working script, using ``'ext://"
"__main__.owned_file_handler'`` should work. Here, the actual callable is "
"resolved by :func:`dictConfig` from the ``ext://`` specification."
#: ../Doc/howto/logging-cookbook.rst:1031
"This example hopefully also points the way to how you could implement other "
"types of file change - e.g. setting specific POSIX permission bits - in the "
"same way, using :func:`os.chmod`."
#: ../Doc/howto/logging-cookbook.rst:1035
"Of course, the approach could also be extended to types of handler other "
"than a :class:`~logging.FileHandler` - for example, one of the rotating file "
"handlers, or a different type of handler altogether."
#: ../Doc/howto/logging-cookbook.rst:1043
msgid "Configuring filters with :func:`dictConfig`"
#: ../Doc/howto/logging-cookbook.rst:1045
"You *can* configure filters using :func:`~logging.config.dictConfig`, though "
"it might not be obvious at first glance how to do it (hence this recipe). "
"Since :class:`~logging.Filter` is the only filter class included in the "
"standard library, and it is unlikely to cater to many requirements (it's "
"only there as a base class), you will typically need to define your own :"
"class:`~logging.Filter` subclass with an overridden :meth:`~logging.Filter."
"filter` method. To do this, specify the ``()`` key in the configuration "
"dictionary for the filter, specifying a callable which will be used to "
"create the filter (a class is the most obvious, but you can provide any "
"callable which returns a :class:`~logging.Filter` instance). Here is a "
"complete example::"
#: ../Doc/howto/logging-cookbook.rst:1098
"This example shows how you can pass configuration data to the callable which "
"constructs the instance, in the form of keyword parameters. When run, the "
"above script will print::"
#: ../Doc/howto/logging-cookbook.rst:1104
msgid "which shows that the filter is working as configured."
#: ../Doc/howto/logging-cookbook.rst:1106
msgid "A couple of extra points to note:"
#: ../Doc/howto/logging-cookbook.rst:1108
"If you can't refer to the callable directly in the configuration (e.g. if it "
"lives in a different module, and you can't import it directly where the "
"configuration dictionary is), you can use the form ``ext://...`` as "
"described in :ref:`logging-config-dict-externalobj`. For example, you could "
"have used the text ``'ext://__main__.MyFilter'`` instead of ``MyFilter`` in "
"the above example."
#: ../Doc/howto/logging-cookbook.rst:1115
"As well as for filters, this technique can also be used to configure custom "
"handlers and formatters. See :ref:`logging-config-dict-userdef` for more "
"information on how logging supports using user-defined objects in its "
"configuration, and see the other cookbook recipe :ref:`custom-handlers` "
#: ../Doc/howto/logging-cookbook.rst:1124
msgid "Customized exception formatting"
#: ../Doc/howto/logging-cookbook.rst:1126
"There might be times when you want to do customized exception formatting - "
"for argument's sake, let's say you want exactly one line per logged event, "
"even when exception information is present. You can do this with a custom "
"formatter class, as shown in the following example::"
#: ../Doc/howto/logging-cookbook.rst:1167
msgid "When run, this produces a file with exactly two lines::"
#: ../Doc/howto/logging-cookbook.rst:1172
"While the above treatment is simplistic, it points the way to how exception "
"information can be formatted to your liking. The :mod:`traceback` module may "
"be helpful for more specialized needs."
#: ../Doc/howto/logging-cookbook.rst:1179
msgid "Speaking logging messages"
#: ../Doc/howto/logging-cookbook.rst:1181
"There might be situations when it is desirable to have logging messages "
"rendered in an audible rather than a visible format. This is easy to do if "
"you have text- to-speech (TTS) functionality available in your system, even "
"if it doesn't have a Python binding. Most TTS systems have a command line "
"program you can run, and this can be invoked from a handler using :mod:"
"`subprocess`. It's assumed here that TTS command line programs won't expect "
"to interact with users or take a long time to complete, and that the "
"frequency of logged messages will be not so high as to swamp the user with "
"messages, and that it's acceptable to have the messages spoken one at a time "
"rather than concurrently, The example implementation below waits for one "
"message to be spoken before the next is processed, and this might cause "
"other handlers to be kept waiting. Here is a short example showing the "
"approach, which assumes that the ``espeak`` TTS package is available::"
#: ../Doc/howto/logging-cookbook.rst:1223
"When run, this script should say \"Hello\" and then \"Goodbye\" in a female "
#: ../Doc/howto/logging-cookbook.rst:1225
"The above approach can, of course, be adapted to other TTS systems and even "
"other systems altogether which can process messages via external programs "
"run from a command line."
#: ../Doc/howto/logging-cookbook.rst:1232
msgid "Buffering logging messages and outputting them conditionally"
#: ../Doc/howto/logging-cookbook.rst:1234
"There might be situations where you want to log messages in a temporary area "
"and only output them if a certain condition occurs. For example, you may "
"want to start logging debug events in a function, and if the function "
"completes without errors, you don't want to clutter the log with the "
"collected debug information, but if there is an error, you want all the "
"debug information to be output as well as the error."
#: ../Doc/howto/logging-cookbook.rst:1241
"Here is an example which shows how you could do this using a decorator for "
"your functions where you want logging to behave this way. It makes use of "
"the :class:`logging.handlers.MemoryHandler`, which allows buffering of "
"logged events until some condition occurs, at which point the buffered "
"events are ``flushed`` - passed to another handler (the ``target`` handler) "
"for processing. By default, the ``MemoryHandler`` flushed when its buffer "
"gets filled up or an event whose level is greater than or equal to a "
"specified threshold is seen. You can use this recipe with a more specialised "
"subclass of ``MemoryHandler`` if you want custom flushing behavior."
#: ../Doc/howto/logging-cookbook.rst:1251
"The example script has a simple function, ``foo``, which just cycles through "
"all the logging levels, writing to ``sys.stderr`` to say what level it's "
"about to log at, and then actually logging a message at that level. You can "
"pass a parameter to ``foo`` which, if true, will log at ERROR and CRITICAL "
"levels - otherwise, it only logs at DEBUG, INFO and WARNING levels."
#: ../Doc/howto/logging-cookbook.rst:1257
"The script just arranges to decorate ``foo`` with a decorator which will do "
"the conditional logging that's required. The decorator takes a logger as a "
"parameter and attaches a memory handler for the duration of the call to the "
"decorated function. The decorator can be additionally parameterised using a "
"target handler, a level at which flushing should occur, and a capacity for "
"the buffer. These default to a :class:`~logging.StreamHandler` which writes "
"to ``sys.stderr``, ``logging.ERROR`` and ``100`` respectively."
#: ../Doc/howto/logging-cookbook.rst:1265
msgid "Here's the script::"
#: ../Doc/howto/logging-cookbook.rst:1328
msgid "When this script is run, the following output should be observed::"
#: ../Doc/howto/logging-cookbook.rst:1356
"As you can see, actual logging output only occurs when an event is logged "
"whose severity is ERROR or greater, but in that case, any previous events at "
"lower severities are also logged."
#: ../Doc/howto/logging-cookbook.rst:1360
msgid "You can of course use the conventional means of decoration::"
#: ../Doc/howto/logging-cookbook.rst:1370
msgid "Formatting times using UTC (GMT) via configuration"
#: ../Doc/howto/logging-cookbook.rst:1372
"Sometimes you want to format times using UTC, which can be done using a "
"class such as `UTCFormatter`, shown below::"
#: ../Doc/howto/logging-cookbook.rst:1381
"and you can then use the ``UTCFormatter`` in your code instead of :class:"
"`~logging.Formatter`. If you want to do that via configuration, you can use "
"the :func:`~logging.config.dictConfig` API with an approach illustrated by "
"the following complete example::"
#: ../Doc/howto/logging-cookbook.rst:1424
msgid "When this script is run, it should print something like::"
#: ../Doc/howto/logging-cookbook.rst:1429
"showing how the time is formatted both as local time and UTC, one for each "
#: ../Doc/howto/logging-cookbook.rst:1436
msgid "Using a context manager for selective logging"
#: ../Doc/howto/logging-cookbook.rst:1438
"There are times when it would be useful to temporarily change the logging "
"configuration and revert it back after doing something. For this, a context "
"manager is the most obvious way of saving and restoring the logging context. "
"Here is a simple example of such a context manager, which allows you to "
"optionally change the logging level and add a logging handler purely in the "
"scope of the context manager::"
#: ../Doc/howto/logging-cookbook.rst:1471
"If you specify a level value, the logger's level is set to that value in the "
"scope of the with block covered by the context manager. If you specify a "
"handler, it is added to the logger on entry to the block and removed on exit "
"from the block. You can also ask the manager to close the handler for you on "
"block exit - you could do this if you don't need the handler any more."
#: ../Doc/howto/logging-cookbook.rst:1477
"To illustrate how it works, we can add the following block of code to the "
#: ../Doc/howto/logging-cookbook.rst:1495
"We initially set the logger's level to ``INFO``, so message #1 appears and "
"message #2 doesn't. We then change the level to ``DEBUG`` temporarily in the "
"following ``with`` block, and so message #3 appears. After the block exits, "
"the logger's level is restored to ``INFO`` and so message #4 doesn't appear. "
"In the next ``with`` block, we set the level to ``DEBUG`` again but also add "
"a handler writing to ``sys.stdout``. Thus, message #5 appears twice on the "
"console (once via ``stderr`` and once via ``stdout``). After the ``with`` "
"statement's completion, the status is as it was before so message #6 appears "
"(like message #1) whereas message #7 doesn't (just like message #2)."
#: ../Doc/howto/logging-cookbook.rst:1505
msgid "If we run the resulting script, the result is as follows:"
#: ../Doc/howto/logging-cookbook.rst:1516
"If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the "
"following, which is the only message written to ``stdout``:"
#: ../Doc/howto/logging-cookbook.rst:1524
msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:"
#: ../Doc/howto/logging-cookbook.rst:1534
"In this case, the message #5 printed to ``stdout`` doesn't appear, as "
"expected."
#: ../Doc/howto/logging-cookbook.rst:1536
"Of course, the approach described here can be generalised, for example to "
"attach logging filters temporarily. Note that the above code works in Python "
"2 as well as Python 3."
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

logging-cookbook.po

Latest commit

History

logging-cookbook.po

File metadata and controls
