forked from AFPy/python-docs-fr
1525 lines
60 KiB
Plaintext
1525 lines
60 KiB
Plaintext
# Copyright (C) 2001-2018, Python Software Foundation
|
||
# For licence information, see README file.
|
||
#
|
||
msgid ""
|
||
msgstr ""
|
||
"Project-Id-Version: Python 3\n"
|
||
"Report-Msgid-Bugs-To: \n"
|
||
"POT-Creation-Date: 2019-09-04 11:33+0200\n"
|
||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||
"Language-Team: FRENCH <traductions@lists.afpy.org>\n"
|
||
"Language: fr\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"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:0
|
||
msgid "Author"
|
||
msgstr "Auteur"
|
||
|
||
#: ../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
|
||
msgid ""
|
||
"This page contains a number of recipes related to logging, which have been "
|
||
"found useful in the past."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:15
|
||
msgid "Using logging in multiple modules"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:17
|
||
msgid ""
|
||
"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 "
|
||
"module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:55
|
||
msgid "Here is the auxiliary module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:75
|
||
msgid "The output looks like this:"
|
||
msgstr "La sortie ressemble à ceci ::"
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:101
|
||
msgid "Logging from multiple threads"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:103
|
||
msgid ""
|
||
"Logging from multiple threads requires no special effort. The following "
|
||
"example shows logging from the main (initial) thread and another thread::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:132
|
||
msgid "When run, the script should print something like the following:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:154
|
||
msgid ""
|
||
"This shows the logging output interspersed as one might expect. This "
|
||
"approach works for more threads than shown here, of course."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:158
|
||
msgid "Multiple handlers and formatters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:160
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:193
|
||
msgid ""
|
||
"Notice that the 'application' code does not care about multiple handlers. "
|
||
"All that changed was the addition and configuration of a new handler named "
|
||
"*fh*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:196
|
||
msgid ""
|
||
"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 "
|
||
"debug."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:207
|
||
msgid "Logging to multiple destinations"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:209
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:247
|
||
msgid "When you run this, on the console you will see"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:256
|
||
msgid "and in the file you will see something like"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:266
|
||
msgid ""
|
||
"As you can see, the DEBUG message only shows up in the file. The other "
|
||
"messages are sent to both destinations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:269
|
||
msgid ""
|
||
"This example uses console and file handlers, but you can use any number and "
|
||
"combination of handlers you choose."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:274
|
||
msgid "Configuration server example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:276
|
||
msgid "Here is an example of a module using the logging configuration server::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:307
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:330
|
||
msgid "Dealing with handlers that block"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:334
|
||
msgid ""
|
||
"Sometimes you have to get your logging handlers to do their work without "
|
||
"blocking the thread you're logging from. This is common in Web applications, "
|
||
"though of course it also occurs in other scenarios."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:338
|
||
msgid ""
|
||
"A common culprit which demonstrates sluggish behaviour is the :class:"
|
||
"`SMTPHandler`: sending emails can take a long time, for a number of reasons "
|
||
"outside the developer's control (for example, a poorly performing mail or "
|
||
"network infrastructure). But almost any network-based handler can block: "
|
||
"Even a :class:`SocketHandler` operation may do a DNS query under the hood "
|
||
"which is too slow (and this query can be deep in the socket library code, "
|
||
"below the Python layer, and outside your control)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:346
|
||
msgid ""
|
||
"One solution is to use a two-part approach. For the first part, attach only "
|
||
"a :class:`QueueHandler` to those loggers which are accessed from performance-"
|
||
"critical threads. They simply write to their queue, which can be sized to a "
|
||
"large enough capacity or initialized with no upper bound to their size. The "
|
||
"write to the queue will typically be accepted quickly, though you will "
|
||
"probably need to catch the :exc:`queue.Full` exception as a precaution in "
|
||
"your code. If you are a library developer who has performance-critical "
|
||
"threads in their code, be sure to document this (together with a suggestion "
|
||
"to attach only ``QueueHandlers`` to your loggers) for the benefit of other "
|
||
"developers who will use your code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:357
|
||
msgid ""
|
||
"The second part of the solution is :class:`QueueListener`, which has been "
|
||
"designed as the counterpart to :class:`QueueHandler`. A :class:"
|
||
"`QueueListener` is very simple: it's passed a queue and some handlers, and "
|
||
"it fires up an internal thread which listens to its queue for LogRecords "
|
||
"sent from ``QueueHandlers`` (or any other source of ``LogRecords``, for that "
|
||
"matter). The ``LogRecords`` are removed from the queue and passed to the "
|
||
"handlers for processing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:365
|
||
msgid ""
|
||
"The advantage of having a separate :class:`QueueListener` class is that you "
|
||
"can use the same instance to service multiple ``QueueHandlers``. This is "
|
||
"more resource-friendly than, say, having threaded versions of the existing "
|
||
"handler classes, which would eat up one thread per handler for no particular "
|
||
"benefit."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:370
|
||
msgid "An example of using these two classes follows (imports omitted)::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:388
|
||
msgid "which, when run, will produce:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:394
|
||
msgid ""
|
||
"Prior to Python 3.5, the :class:`QueueListener` always passed every message "
|
||
"received from the queue to every handler it was initialized with. (This was "
|
||
"because it was assumed that level filtering was all done on the other side, "
|
||
"where the queue is filled.) From 3.5 onwards, this behaviour can be changed "
|
||
"by passing a keyword argument ``respect_handler_level=True`` to the "
|
||
"listener's constructor. When this is done, the listener compares the level "
|
||
"of each message with the handler's level, and only passes a message to a "
|
||
"handler if it's appropriate to do so."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:407
|
||
msgid "Sending and receiving logging events across a network"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:409
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:437
|
||
msgid ""
|
||
"At the receiving end, you can set up a receiver using the :mod:"
|
||
"`socketserver` module. Here is a basic working example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:525
|
||
msgid ""
|
||
"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:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:537
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:547
|
||
msgid "Adding contextual information to your logging output"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:549
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:564
|
||
msgid "Using LoggerAdapters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:566
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:574
|
||
msgid ""
|
||
"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`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:590
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:599
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:615
|
||
msgid "which you can use like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:620
|
||
msgid ""
|
||
"Then any events that you log to the adapter will have the value of "
|
||
"``some_conn_id`` prepended to the log messages."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:624
|
||
msgid "Using objects other than dicts to pass contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:626
|
||
msgid ""
|
||
"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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:635
|
||
msgid "Using Filters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:637
|
||
msgid ""
|
||
"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`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:642
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:688
|
||
msgid "which, when run, produces something like:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:709
|
||
msgid "Logging to a single file from multiple processes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:711
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:724
|
||
msgid ""
|
||
"You could also write your own handler which uses the :class:"
|
||
"`~multiprocessing.Lock` class from the :mod:`multiprocessing` 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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:734
|
||
msgid ""
|
||
"Alternatively, you can use a ``Queue`` and a :class:`QueueHandler` to send "
|
||
"all logging events to one of the processes in your multi-process "
|
||
"application. The following example script demonstrates how you can do this; "
|
||
"in the example a separate listener process listens for events sent by other "
|
||
"processes and logs them according to its own logging configuration. Although "
|
||
"the example only demonstrates one way of doing it (for example, you may want "
|
||
"to use a listener thread rather than a separate listener process -- the "
|
||
"implementation would be analogous) it does allow for completely different "
|
||
"logging configurations for the listener and the other processes in your "
|
||
"application, and can be used as the basis for code meeting your own specific "
|
||
"requirements::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:850
|
||
msgid ""
|
||
"A variant of the above script keeps the logging in the main process, in a "
|
||
"separate thread::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:945
|
||
msgid ""
|
||
"This variant shows how you can e.g. apply configuration for particular "
|
||
"loggers - e.g. the ``foo`` logger has a special handler which stores all "
|
||
"events in the ``foo`` subsystem in a file ``mplog-foo.log``. This will be "
|
||
"used by the logging machinery in the main process (even though the logging "
|
||
"events are generated in the worker processes) to direct the messages to the "
|
||
"appropriate destinations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:952
|
||
msgid "Using concurrent.futures.ProcessPoolExecutor"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:954
|
||
msgid ""
|
||
"If you want to use :class:`concurrent.futures.ProcessPoolExecutor` to start "
|
||
"your worker processes, you need to create the queue slightly differently. "
|
||
"Instead of"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:962
|
||
msgid "you should use"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:968
|
||
msgid "and you can then replace the worker creation from this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:979
|
||
msgid "to this (remembering to first import :mod:`concurrent.futures`)::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:987
|
||
msgid "Using file rotation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:992
|
||
msgid ""
|
||
"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`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1024
|
||
msgid ""
|
||
"The result should be 6 separate files, each with part of the log history for "
|
||
"the application:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1036
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1041
|
||
msgid ""
|
||
"Obviously this example sets the log length much too small as an extreme "
|
||
"example. You would want to set *maxBytes* to an appropriate value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1047
|
||
msgid "Use of alternative formatting styles"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1049
|
||
msgid ""
|
||
"When logging was added to the Python standard library, the only way of "
|
||
"formatting messages with variable content was to use the %-formatting "
|
||
"method. Since then, Python has gained two new formatting approaches: :class:"
|
||
"`string.Template` (added in Python 2.4) and :meth:`str.format` (added in "
|
||
"Python 2.6)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1055
|
||
msgid ""
|
||
"Logging (as of 3.2) provides improved support for these two additional "
|
||
"formatting styles. The :class:`Formatter` class been enhanced to take an "
|
||
"additional, optional keyword parameter named ``style``. This defaults to "
|
||
"``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond "
|
||
"to the other two formatting styles. Backwards compatibility is maintained by "
|
||
"default (as you would expect), but by explicitly specifying a style "
|
||
"parameter, you get the ability to specify format strings which work with :"
|
||
"meth:`str.format` or :class:`string.Template`. Here's an example console "
|
||
"session to show the possibilities:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1089
|
||
msgid ""
|
||
"Note that the formatting of logging messages for final output to logs is "
|
||
"completely independent of how an individual logging message is constructed. "
|
||
"That can still use %-formatting, as shown here::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1097
|
||
msgid ""
|
||
"Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take "
|
||
"positional parameters for the actual logging message itself, with keyword "
|
||
"parameters used only for determining options for how to handle the actual "
|
||
"logging call (e.g. the ``exc_info`` keyword parameter to indicate that "
|
||
"traceback information should be logged, or the ``extra`` keyword parameter "
|
||
"to indicate additional contextual information to be added to the log). So "
|
||
"you cannot directly make logging calls using :meth:`str.format` or :class:"
|
||
"`string.Template` syntax, because internally the logging package uses %-"
|
||
"formatting to merge the format string and the variable arguments. There "
|
||
"would be no changing this while preserving backward compatibility, since all "
|
||
"logging calls which are out there in existing code will be using %-format "
|
||
"strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1110
|
||
msgid ""
|
||
"There is, however, a way that you can use {}- and $- formatting to construct "
|
||
"your individual log messages. Recall that for a message you can use an "
|
||
"arbitrary object as a message format string, and that the logging package "
|
||
"will call ``str()`` on that object to get the actual format string. Consider "
|
||
"the following two classes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1134
|
||
msgid ""
|
||
"Either of these can be used in place of a format string, to allow {}- or $-"
|
||
"formatting to be used to build the actual \"message\" part which appears in "
|
||
"the formatted log output in place of \"%(message)s\" or \"{message}\" or "
|
||
"\"$message\". It's a little unwieldy to use the class names whenever you "
|
||
"want to log something, but it's quite palatable if you use an alias such as "
|
||
"__ (double underscore --- not to be confused with _, the single underscore "
|
||
"used as a synonym/alias for :func:`gettext.gettext` or its brethren)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1142
|
||
msgid ""
|
||
"The above classes are not included in Python, though they're easy enough to "
|
||
"copy and paste into your own code. They can be used as follows (assuming "
|
||
"that they're declared in a module called ``wherever``):"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1164
|
||
msgid ""
|
||
"While the above examples use ``print()`` to show how the formatting works, "
|
||
"you would of course use ``logger.debug()`` or similar to actually log using "
|
||
"this approach."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1168
|
||
msgid ""
|
||
"One thing to note is that you pay no significant performance penalty with "
|
||
"this approach: the actual formatting happens not when you make the logging "
|
||
"call, but when (and if) the logged message is actually about to be output to "
|
||
"a log by a handler. So the only slightly unusual thing which might trip you "
|
||
"up is that the parentheses go around the format string and the arguments, "
|
||
"not just the format string. That's because the __ notation is just syntax "
|
||
"sugar for a constructor call to one of the XXXMessage classes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1176
|
||
msgid ""
|
||
"If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar "
|
||
"effect to the above, as in the following example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1207
|
||
msgid ""
|
||
"The above script should log the message ``Hello, world!`` when run with "
|
||
"Python 3.2 or later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1216
|
||
msgid "Customizing ``LogRecord``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1218
|
||
msgid ""
|
||
"Every logging event is represented by a :class:`LogRecord` instance. When an "
|
||
"event is logged and not filtered out by a logger's level, a :class:"
|
||
"`LogRecord` is created, populated with information about the event and then "
|
||
"passed to the handlers for that logger (and its ancestors, up to and "
|
||
"including the logger where further propagation up the hierarchy is "
|
||
"disabled). Before Python 3.2, there were only two places where this creation "
|
||
"was done:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1225
|
||
msgid ""
|
||
":meth:`Logger.makeRecord`, which is called in the normal process of logging "
|
||
"an event. This invoked :class:`LogRecord` directly to create an instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1228
|
||
msgid ""
|
||
":func:`makeLogRecord`, which is called with a dictionary containing "
|
||
"attributes to be added to the LogRecord. This is typically invoked when a "
|
||
"suitable dictionary has been received over the network (e.g. in pickle form "
|
||
"via a :class:`~handlers.SocketHandler`, or in JSON form via an :class:"
|
||
"`~handlers.HTTPHandler`)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1234
|
||
msgid ""
|
||
"This has usually meant that if you need to do anything special with a :class:"
|
||
"`LogRecord`, you've had to do one of the following."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1237
|
||
msgid ""
|
||
"Create your own :class:`Logger` subclass, which overrides :meth:`Logger."
|
||
"makeRecord`, and set it using :func:`~logging.setLoggerClass` before any "
|
||
"loggers that you care about are instantiated."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1240
|
||
msgid ""
|
||
"Add a :class:`Filter` to a logger or handler, which does the necessary "
|
||
"special manipulation you need when its :meth:`~Filter.filter` method is "
|
||
"called."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1244
|
||
msgid ""
|
||
"The first approach would be a little unwieldy in the scenario where (say) "
|
||
"several different libraries wanted to do different things. Each would "
|
||
"attempt to set its own :class:`Logger` subclass, and the one which did this "
|
||
"last would win."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1249
|
||
msgid ""
|
||
"The second approach works reasonably well for many cases, but does not allow "
|
||
"you to e.g. use a specialized subclass of :class:`LogRecord`. Library "
|
||
"developers can set a suitable filter on their loggers, but they would have "
|
||
"to remember to do this every time they introduced a new logger (which they "
|
||
"would do simply by adding new packages or modules and doing ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1257
|
||
msgid ""
|
||
"at module level). It's probably one too many things to think about. "
|
||
"Developers could also add the filter to a :class:`~logging.NullHandler` "
|
||
"attached to their top-level logger, but this would not be invoked if an "
|
||
"application developer attached a handler to a lower-level library logger --- "
|
||
"so output from that handler would not reflect the intentions of the library "
|
||
"developer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1263
|
||
msgid ""
|
||
"In Python 3.2 and later, :class:`~logging.LogRecord` creation is done "
|
||
"through a factory, which you can specify. The factory is just a callable you "
|
||
"can set with :func:`~logging.setLogRecordFactory`, and interrogate with :"
|
||
"func:`~logging.getLogRecordFactory`. The factory is invoked with the same "
|
||
"signature as the :class:`~logging.LogRecord` constructor, as :class:"
|
||
"`LogRecord` is the default setting for the factory."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1270
|
||
msgid ""
|
||
"This approach allows a custom factory to control all aspects of LogRecord "
|
||
"creation. For example, you could return a subclass, or just add some "
|
||
"additional attributes to the record once created, using a pattern similar to "
|
||
"this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1283
|
||
msgid ""
|
||
"This pattern allows different libraries to chain factories together, and as "
|
||
"long as they don't overwrite each other's attributes or unintentionally "
|
||
"overwrite the attributes provided as standard, there should be no surprises. "
|
||
"However, it should be borne in mind that each link in the chain adds run-"
|
||
"time overhead to all logging operations, and the technique should only be "
|
||
"used when the use of a :class:`Filter` does not provide the desired result."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1294
|
||
msgid "Subclassing QueueHandler - a ZeroMQ example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1296
|
||
msgid ""
|
||
"You can use a :class:`QueueHandler` subclass to send messages to other kinds "
|
||
"of queues, for example a ZeroMQ 'publish' socket. In the example below,the "
|
||
"socket is created separately and passed to the handler (as its 'queue')::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1315
|
||
msgid ""
|
||
"Of course there are other ways of organizing this, for example passing in "
|
||
"the data needed by the handler to create the socket::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1333
|
||
msgid "Subclassing QueueListener - a ZeroMQ example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1335
|
||
msgid ""
|
||
"You can also subclass :class:`QueueListener` to get messages from other "
|
||
"kinds of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1354
|
||
msgid "Module :mod:`logging`"
|
||
msgstr "Module :mod:`logging`"
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1354
|
||
msgid "API reference for the logging module."
|
||
msgstr "Référence d'API pour le module de journalisation."
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1357
|
||
msgid "Module :mod:`logging.config`"
|
||
msgstr "Module :mod:`logging.config`"
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1357
|
||
msgid "Configuration API for the logging module."
|
||
msgstr "API de configuration pour le module de journalisation."
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1360
|
||
msgid "Module :mod:`logging.handlers`"
|
||
msgstr "Module :mod:`logging.handlers`"
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1360
|
||
msgid "Useful handlers included with the logging module."
|
||
msgstr "Gestionnaires utiles inclus avec le module de journalisation."
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1362
|
||
msgid ":ref:`A basic logging tutorial <logging-basic-tutorial>`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1364
|
||
msgid ":ref:`A more advanced logging tutorial <logging-advanced-tutorial>`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1368
|
||
msgid "An example dictionary-based configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1370
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1426
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1433
|
||
msgid "Using a rotator and namer to customize log rotation processing"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1435
|
||
msgid ""
|
||
"An example of how you can define a namer and rotator is given in the "
|
||
"following snippet, which shows zlib-based compression of the log file::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1453
|
||
msgid ""
|
||
"These are not \"true\" .gz files, as they are bare compressed data, with no "
|
||
"\"container\" such as you’d find in an actual gzip file. This snippet is "
|
||
"just for illustration purposes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1458
|
||
msgid "A more elaborate multiprocessing example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1460
|
||
msgid ""
|
||
"The following working example shows how logging can be used with "
|
||
"multiprocessing using configuration files. The configurations are fairly "
|
||
"simple, but serve to illustrate how more complex ones could be implemented "
|
||
"in a real multiprocessing scenario."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1465
|
||
msgid ""
|
||
"In the example, the main process spawns a listener process and some worker "
|
||
"processes. Each of the main process, the listener and the workers have three "
|
||
"separate configurations (the workers all share the same configuration). We "
|
||
"can see logging in the main process, how the workers log to a QueueHandler "
|
||
"and how the listener implements a QueueListener and a more complex logging "
|
||
"configuration, and arranges to dispatch events received via the queue to the "
|
||
"handlers specified in the configuration. Note that these configurations are "
|
||
"purely illustrative, but you should be able to adapt this example to your "
|
||
"own scenario."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1475
|
||
msgid ""
|
||
"Here's the script - the docstrings and the comments hopefully explain how it "
|
||
"works::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1687
|
||
msgid "Inserting a BOM into messages sent to a SysLogHandler"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1689
|
||
msgid ""
|
||
":rfc:`5424` 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 :rfc:`relevant section of the specification "
|
||
"<5424#section-6>`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1695
|
||
msgid ""
|
||
"In Python 3.1, 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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1701
|
||
msgid ""
|
||
"As this behaviour is broken, the incorrect BOM insertion code is being "
|
||
"removed from Python 3.2.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:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1707
|
||
msgid ""
|
||
"Attach a :class:`~logging.Formatter` instance to your :class:`~logging."
|
||
"handlers.SysLogHandler` instance, with a format string such as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1713
|
||
msgid ""
|
||
"The Unicode code point U+FEFF, when encoded using UTF-8, will be encoded as "
|
||
"a UTF-8 BOM -- the byte-string ``b'\\xef\\xbb\\xbf'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1716
|
||
msgid ""
|
||
"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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1720
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1724
|
||
msgid ""
|
||
"The formatted message *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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1731
|
||
msgid "Implementing structured logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1733
|
||
msgid ""
|
||
"Although most logging messages are intended for reading by humans, and thus "
|
||
"not readily machine-parseable, there might be circumstances 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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1757
|
||
msgid "If the above script is run, it prints:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1763
|
||
#: ../Doc/howto/logging-cookbook.rst:1812
|
||
msgid ""
|
||
"Note that the order of items might be different according to the version of "
|
||
"Python used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1766
|
||
msgid ""
|
||
"If you need more specialised processing, you can use a custom JSON encoder, "
|
||
"as in the following complete example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1806
|
||
msgid "When the above script is run, it prints:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1821
|
||
msgid "Customizing handlers with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1823
|
||
msgid ""
|
||
"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:`shutil.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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1837
|
||
msgid ""
|
||
"You can then specify, in a logging configuration passed to :func:"
|
||
"`dictConfig`, that a logging handler be created by calling this function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1870
|
||
msgid ""
|
||
"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``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1917
|
||
msgid "To run this, you will probably need to run as ``root``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1927
|
||
msgid ""
|
||
"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`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1933
|
||
msgid ""
|
||
"In practice, the handler-creating function may be in a utility module "
|
||
"somewhere in your project. Instead of the line in the configuration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1938
|
||
msgid "you could use e.g.::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1942
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1947
|
||
msgid ""
|
||
"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`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1951
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1961
|
||
msgid "Using particular formatting styles throughout your application"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1963
|
||
msgid ""
|
||
"In Python 3.2, the :class:`~logging.Formatter` gained a ``style`` keyword "
|
||
"parameter which, while defaulting to ``%`` for backward compatibility, "
|
||
"allowed the specification of ``{`` or ``$`` to support the formatting "
|
||
"approaches supported by :meth:`str.format` and :class:`string.Template`. "
|
||
"Note that this governs the formatting of logging messages for final output "
|
||
"to logs, and is completely orthogonal to how an individual logging message "
|
||
"is constructed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1970
|
||
msgid ""
|
||
"Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take "
|
||
"positional parameters for the actual logging message itself, with keyword "
|
||
"parameters used only for determining options for how to handle the logging "
|
||
"call (e.g. the ``exc_info`` keyword parameter to indicate that traceback "
|
||
"information should be logged, or the ``extra`` keyword parameter to indicate "
|
||
"additional contextual information to be added to the log). So you cannot "
|
||
"directly make logging calls using :meth:`str.format` or :class:`string."
|
||
"Template` syntax, because internally the logging package uses %-formatting "
|
||
"to merge the format string and the variable arguments. There would no "
|
||
"changing this while preserving backward compatibility, since all logging "
|
||
"calls which are out there in existing code will be using %-format strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1982
|
||
msgid ""
|
||
"There have been suggestions to associate format styles with specific "
|
||
"loggers, but that approach also runs into backward compatibility problems "
|
||
"because any existing code could be using a given logger name and using %-"
|
||
"formatting."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1986
|
||
msgid ""
|
||
"For logging to work interoperably between any third-party libraries and your "
|
||
"code, decisions about formatting need to be made at the level of the "
|
||
"individual logging call. This opens up a couple of ways in which alternative "
|
||
"formatting styles can be accommodated."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1993
|
||
msgid "Using LogRecord factories"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1995
|
||
msgid ""
|
||
"In Python 3.2, along with the :class:`~logging.Formatter` changes mentioned "
|
||
"above, the logging package gained the ability to allow users to set their "
|
||
"own :class:`LogRecord` subclasses, using the :func:`setLogRecordFactory` "
|
||
"function. You can use this to set your own subclass of :class:`LogRecord`, "
|
||
"which does the Right Thing by overriding the :meth:`~LogRecord.getMessage` "
|
||
"method. The base class implementation of this method is where the ``msg % "
|
||
"args`` formatting happens, and where you can substitute your alternate "
|
||
"formatting; however, you should be careful to support all formatting styles "
|
||
"and allow %-formatting as the default, to ensure interoperability with other "
|
||
"code. Care should also be taken to call ``str(self.msg)``, just as the base "
|
||
"implementation does."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2006
|
||
msgid ""
|
||
"Refer to the reference documentation on :func:`setLogRecordFactory` and :"
|
||
"class:`LogRecord` for more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2011
|
||
msgid "Using custom message objects"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2013
|
||
msgid ""
|
||
"There is another, perhaps simpler way that you can use {}- and $- formatting "
|
||
"to construct your individual log messages. You may recall (from :ref:"
|
||
"`arbitrary-object-messages`) that when logging you can use an arbitrary "
|
||
"object as a message format string, and that the logging package will call :"
|
||
"func:`str` on that object to get the actual format string. Consider the "
|
||
"following two classes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2038
|
||
msgid ""
|
||
"Either of these can be used in place of a format string, to allow {}- or $-"
|
||
"formatting to be used to build the actual \"message\" part which appears in "
|
||
"the formatted log output in place of “%(message)s” or “{message}” or "
|
||
"“$message”. If you find it a little unwieldy to use the class names whenever "
|
||
"you want to log something, you can make it more palatable if you use an "
|
||
"alias such as ``M`` or ``_`` for the message (or perhaps ``__``, if you are "
|
||
"using ``_`` for localization)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2046
|
||
msgid ""
|
||
"Examples of this approach are given below. Firstly, formatting with :meth:"
|
||
"`str.format`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2060
|
||
msgid "Secondly, formatting with :class:`string.Template`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2067
|
||
msgid ""
|
||
"One thing to note is that you pay no significant performance penalty with "
|
||
"this approach: the actual formatting happens not when you make the logging "
|
||
"call, but when (and if) the logged message is actually about to be output to "
|
||
"a log by a handler. So the only slightly unusual thing which might trip you "
|
||
"up is that the parentheses go around the format string and the arguments, "
|
||
"not just the format string. That’s because the __ notation is just syntax "
|
||
"sugar for a constructor call to one of the ``XXXMessage`` classes shown "
|
||
"above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2081
|
||
msgid "Configuring filters with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2083
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2136
|
||
msgid ""
|
||
"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:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2144
|
||
msgid "which shows that the filter is working as configured."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2146
|
||
msgid "A couple of extra points to note:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2148
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2155
|
||
msgid ""
|
||
"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` "
|
||
"above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2164
|
||
msgid "Customized exception formatting"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2166
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2207
|
||
msgid "When run, this produces a file with exactly two lines:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2214
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2221
|
||
msgid "Speaking logging messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2223
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2265
|
||
msgid ""
|
||
"When run, this script should say \"Hello\" and then \"Goodbye\" in a female "
|
||
"voice."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2267
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2275
|
||
msgid "Buffering logging messages and outputting them conditionally"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2277
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2284
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2294
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2300
|
||
msgid ""
|
||
"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 (number of records buffered). These default to a :class:`~logging."
|
||
"StreamHandler` which writes to ``sys.stderr``, ``logging.ERROR`` and ``100`` "
|
||
"respectively."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2308
|
||
msgid "Here's the script::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2371
|
||
msgid "When this script is run, the following output should be observed:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2401
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2405
|
||
msgid "You can of course use the conventional means of decoration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2415
|
||
msgid "Formatting times using UTC (GMT) via configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2417
|
||
msgid ""
|
||
"Sometimes you want to format times using UTC, which can be done using a "
|
||
"class such as `UTCFormatter`, shown below::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2426
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2469
|
||
msgid "When this script is run, it should print something like:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2476
|
||
msgid ""
|
||
"showing how the time is formatted both as local time and UTC, one for each "
|
||
"handler."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2483
|
||
msgid "Using a context manager for selective logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2485
|
||
msgid ""
|
||
"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::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2518
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2524
|
||
msgid ""
|
||
"To illustrate how it works, we can add the following block of code to the "
|
||
"above::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2542
|
||
msgid ""
|
||
"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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2552
|
||
msgid "If we run the resulting script, the result is as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2563
|
||
msgid ""
|
||
"If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the "
|
||
"following, which is the only message written to ``stdout``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2571
|
||
msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2581
|
||
msgid ""
|
||
"In this case, the message #5 printed to ``stdout`` doesn't appear, as "
|
||
"expected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2583
|
||
msgid ""
|
||
"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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2591
|
||
msgid "A CLI application starter template"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2593
|
||
msgid "Here's an example which shows how you can:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2595
|
||
msgid "Use a logging level based on command-line arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2596
|
||
msgid ""
|
||
"Dispatch to multiple subcommands in separate files, all logging at the same "
|
||
"level in a consistent way"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2598
|
||
msgid "Make use of simple, minimal configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2600
|
||
msgid ""
|
||
"Suppose we have a command-line application whose job is to stop, start or "
|
||
"restart some services. This could be organised for the purposes of "
|
||
"illustration as a file ``app.py`` that is the main script for the "
|
||
"application, with individual commands implemented in ``start.py``, ``stop."
|
||
"py`` and ``restart.py``. Suppose further that we want to control the "
|
||
"verbosity of the application via a command-line argument, defaulting to "
|
||
"``logging.INFO``. Here's one way that ``app.py`` could be written::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2649
|
||
msgid ""
|
||
"And the ``start``, ``stop`` and ``restart`` commands can be implemented in "
|
||
"separate modules, like so for starting::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2662
|
||
msgid "and thus for stopping::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2683
|
||
msgid "and similarly for restarting::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2704
|
||
msgid ""
|
||
"If we run this application with the default log level, we get output like "
|
||
"this:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2717
|
||
msgid ""
|
||
"The first word is the logging level, and the second word is the module or "
|
||
"package name of the place where the event was logged."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2720
|
||
msgid ""
|
||
"If we change the logging level, then we can change the information sent to "
|
||
"the log. For example, if we want more information:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2737
|
||
msgid "And if we want less:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2745
|
||
msgid ""
|
||
"In this case, the commands don't print anything to the console, since "
|
||
"nothing at ``WARNING`` level or above is logged by them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2751
|
||
msgid "A Qt GUI for logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2753
|
||
msgid ""
|
||
"A question that comes up from time to time is about how to log to a GUI "
|
||
"application. The `Qt <https://www.qt.io/>`_ framework is a popular cross-"
|
||
"platform UI framework with Python bindings using `PySide2 <https://pypi.org/"
|
||
"project/PySide2/>`_ or `PyQt5 <https://pypi.org/project/PyQt5/>`_ libraries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2759
|
||
msgid ""
|
||
"The following example shows how to log to a Qt GUI. This introduces a simple "
|
||
"``QtHandler`` class which takes a callable, which should be a slot in the "
|
||
"main thread that does GUI updates. A worker thread is also created to show "
|
||
"how you can log to the GUI from both the UI itself (via a button for manual "
|
||
"logging) as well as a worker thread doing work in the background (here, just "
|
||
"logging messages at random levels with random short delays in between)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2766
|
||
msgid ""
|
||
"The worker thread is implemented using Qt's ``QThread`` class rather than "
|
||
"the :mod:`threading` module, as there are circumstances where one has to use "
|
||
"``QThread``, which offers better integration with other ``Qt`` components."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2770
|
||
msgid ""
|
||
"The code should work with recent releases of either ``PySide2`` or "
|
||
"``PyQt5``. You should be able to adapt the approach to earlier versions of "
|
||
"Qt. Please refer to the comments in the code snippet for more detailed "
|
||
"information."
|
||
msgstr ""
|