# 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: 2022-05-22 23:13+0200\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: howto/logging-cookbook.rst:5 msgid "Logging Cookbook" msgstr "" #: howto/logging-cookbook.rst:0 msgid "Author" msgstr "Auteur" #: howto/logging-cookbook.rst:7 msgid "Vinay Sajip " msgstr "Vinay Sajip " #: 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 "" #: howto/logging-cookbook.rst:15 msgid "Using logging in multiple modules" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:55 msgid "Here is the auxiliary module::" msgstr "" #: howto/logging-cookbook.rst:75 msgid "The output looks like this:" msgstr "La sortie ressemble à ceci ::" #: howto/logging-cookbook.rst:101 msgid "Logging from multiple threads" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:132 msgid "When run, the script should print something like the following:" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:158 msgid "Multiple handlers and formatters" msgstr "" #: 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 "" #: 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 "" #: 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 "" #: howto/logging-cookbook.rst:207 msgid "Logging to multiple destinations" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:247 msgid "When you run this, on the console you will see" msgstr "" #: howto/logging-cookbook.rst:256 msgid "and in the file you will see something like" msgstr "" #: 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 "" #: 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 "" #: howto/logging-cookbook.rst:274 msgid "Configuration server example" msgstr "" #: howto/logging-cookbook.rst:276 msgid "Here is an example of a module using the logging configuration server::" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:330 msgid "Dealing with handlers that block" msgstr "" #: 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 "" #: 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 "" #: 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 "" #: 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 "" #: 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 "" #: howto/logging-cookbook.rst:370 msgid "An example of using these two classes follows (imports omitted)::" msgstr "" #: howto/logging-cookbook.rst:388 msgid "which, when run, will produce:" msgstr "" #: 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 "" #: howto/logging-cookbook.rst:407 msgid "Sending and receiving logging events across a network" msgstr "" #: 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 "" #: 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 "" #: 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 "" #: 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 "" #: howto/logging-cookbook.rst:545 msgid "Running a logging socket listener in production" msgstr "" #: howto/logging-cookbook.rst:547 msgid "" "To run a logging listener in production, you may need to use a process-" "management tool such as `Supervisor `_. `Here " "`_ is a " "Gist which provides the bare-bones files to run the above functionality " "using Supervisor: you will need to change the `/path/to/` parts in the Gist " "to reflect the actual paths you want to use." msgstr "" #: howto/logging-cookbook.rst:558 msgid "Adding contextual information to your logging output" msgstr "" #: howto/logging-cookbook.rst:560 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 "" #: howto/logging-cookbook.rst:575 msgid "Using LoggerAdapters to impart contextual information" msgstr "" #: howto/logging-cookbook.rst:577 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 "" #: howto/logging-cookbook.rst:585 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 "" #: howto/logging-cookbook.rst:601 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 "" #: howto/logging-cookbook.rst:610 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 "" #: howto/logging-cookbook.rst:626 msgid "which you can use like this::" msgstr "" #: howto/logging-cookbook.rst:631 msgid "" "Then any events that you log to the adapter will have the value of " "``some_conn_id`` prepended to the log messages." msgstr "" #: howto/logging-cookbook.rst:635 msgid "Using objects other than dicts to pass contextual information" msgstr "" #: howto/logging-cookbook.rst:637 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 "" #: howto/logging-cookbook.rst:646 msgid "Using Filters to impart contextual information" msgstr "" #: howto/logging-cookbook.rst:648 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 "" #: howto/logging-cookbook.rst:653 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 "" #: howto/logging-cookbook.rst:699 msgid "which, when run, produces something like:" msgstr "" #: howto/logging-cookbook.rst:720 msgid "Logging to a single file from multiple processes" msgstr "" #: howto/logging-cookbook.rst:722 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 ` 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 "" #: howto/logging-cookbook.rst:735 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 "" #: howto/logging-cookbook.rst:745 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 "" #: howto/logging-cookbook.rst:861 msgid "" "A variant of the above script keeps the logging in the main process, in a " "separate thread::" msgstr "" #: howto/logging-cookbook.rst:956 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 "" #: howto/logging-cookbook.rst:963 msgid "Using concurrent.futures.ProcessPoolExecutor" msgstr "" #: howto/logging-cookbook.rst:965 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 "" #: howto/logging-cookbook.rst:973 msgid "you should use" msgstr "" #: howto/logging-cookbook.rst:979 msgid "and you can then replace the worker creation from this::" msgstr "" #: howto/logging-cookbook.rst:990 msgid "to this (remembering to first import :mod:`concurrent.futures`)::" msgstr "" #: howto/logging-cookbook.rst:997 msgid "Deploying Web applications using Gunicorn and uWSGI" msgstr "" #: howto/logging-cookbook.rst:999 msgid "" "When deploying Web applications using `Gunicorn `_ or " "`uWSGI `_ (or similar), " "multiple worker processes are created to handle client requests. In such " "environments, avoid creating file-based handlers directly in your web " "application. Instead, use a :class:`SocketHandler` to log from the web " "application to a listener in a separate process. This can be set up using a " "process management tool such as Supervisor - see `Running a logging socket " "listener in production`_ for more details." msgstr "" #: howto/logging-cookbook.rst:1009 msgid "Using file rotation" msgstr "" #: howto/logging-cookbook.rst:1014 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 "" #: howto/logging-cookbook.rst:1046 msgid "" "The result should be 6 separate files, each with part of the log history for " "the application:" msgstr "" #: howto/logging-cookbook.rst:1058 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 "" #: howto/logging-cookbook.rst:1063 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 "" #: howto/logging-cookbook.rst:1069 msgid "Use of alternative formatting styles" msgstr "" #: howto/logging-cookbook.rst:1071 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 "" #: howto/logging-cookbook.rst:1077 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 "" #: howto/logging-cookbook.rst:1111 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 "" #: howto/logging-cookbook.rst:1119 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 "" #: howto/logging-cookbook.rst:1132 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 "" #: howto/logging-cookbook.rst:1156 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 "" #: howto/logging-cookbook.rst:1164 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 "" #: howto/logging-cookbook.rst:1186 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 "" #: howto/logging-cookbook.rst:1190 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 "" #: howto/logging-cookbook.rst:1198 msgid "" "If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar " "effect to the above, as in the following example::" msgstr "" #: howto/logging-cookbook.rst:1229 msgid "" "The above script should log the message ``Hello, world!`` when run with " "Python 3.2 or later." msgstr "" #: howto/logging-cookbook.rst:1238 msgid "Customizing ``LogRecord``" msgstr "" #: howto/logging-cookbook.rst:1240 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 "" #: howto/logging-cookbook.rst:1247 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 "" #: howto/logging-cookbook.rst:1250 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 "" #: howto/logging-cookbook.rst:1256 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 "" #: howto/logging-cookbook.rst:1259 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 "" #: howto/logging-cookbook.rst:1262 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 "" #: howto/logging-cookbook.rst:1266 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 "" #: howto/logging-cookbook.rst:1271 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 "" #: howto/logging-cookbook.rst:1279 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 "" #: howto/logging-cookbook.rst:1285 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 "" #: howto/logging-cookbook.rst:1292 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 "" #: howto/logging-cookbook.rst:1305 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 "" #: howto/logging-cookbook.rst:1316 msgid "Subclassing QueueHandler - a ZeroMQ example" msgstr "" #: howto/logging-cookbook.rst:1318 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 "" #: howto/logging-cookbook.rst:1337 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 "" #: howto/logging-cookbook.rst:1355 msgid "Subclassing QueueListener - a ZeroMQ example" msgstr "" #: howto/logging-cookbook.rst:1357 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 "" #: howto/logging-cookbook.rst:1376 msgid "Module :mod:`logging`" msgstr "Module :mod:`logging`" #: howto/logging-cookbook.rst:1376 msgid "API reference for the logging module." msgstr "Référence d'API pour le module de journalisation." #: howto/logging-cookbook.rst:1379 msgid "Module :mod:`logging.config`" msgstr "Module :mod:`logging.config`" #: howto/logging-cookbook.rst:1379 msgid "Configuration API for the logging module." msgstr "API de configuration pour le module de journalisation." #: howto/logging-cookbook.rst:1382 msgid "Module :mod:`logging.handlers`" msgstr "Module :mod:`logging.handlers`" #: howto/logging-cookbook.rst:1382 msgid "Useful handlers included with the logging module." msgstr "Gestionnaires utiles inclus avec le module de journalisation." #: howto/logging-cookbook.rst:1384 msgid ":ref:`A basic logging tutorial `" msgstr "" #: howto/logging-cookbook.rst:1386 msgid ":ref:`A more advanced logging tutorial `" msgstr "" #: howto/logging-cookbook.rst:1390 msgid "An example dictionary-based configuration" msgstr "" #: howto/logging-cookbook.rst:1392 msgid "" "Below is an example of a logging configuration dictionary - it's taken from " "the `documentation on the Django project `_. This dictionary is passed to :" "func:`~config.dictConfig` to put the configuration into effect::" msgstr "" #: howto/logging-cookbook.rst:1448 msgid "" "For more information about this configuration, you can see the `relevant " "section `_ of the Django documentation." msgstr "" #: howto/logging-cookbook.rst:1455 msgid "Using a rotator and namer to customize log rotation processing" msgstr "" #: howto/logging-cookbook.rst:1457 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 "" #: howto/logging-cookbook.rst:1475 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 "" #: howto/logging-cookbook.rst:1480 msgid "A more elaborate multiprocessing example" msgstr "" #: howto/logging-cookbook.rst:1482 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 "" #: howto/logging-cookbook.rst:1487 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 "" #: howto/logging-cookbook.rst:1497 msgid "" "Here's the script - the docstrings and the comments hopefully explain how it " "works::" msgstr "" #: howto/logging-cookbook.rst:1709 msgid "Inserting a BOM into messages sent to a SysLogHandler" msgstr "" #: howto/logging-cookbook.rst:1711 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 "" #: howto/logging-cookbook.rst:1717 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 "" #: howto/logging-cookbook.rst:1723 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 "" #: howto/logging-cookbook.rst:1729 msgid "" "Attach a :class:`~logging.Formatter` instance to your :class:`~logging." "handlers.SysLogHandler` instance, with a format string such as::" msgstr "" #: howto/logging-cookbook.rst:1735 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 "" #: howto/logging-cookbook.rst:1738 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 "" #: howto/logging-cookbook.rst:1742 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 "" #: howto/logging-cookbook.rst:1746 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 "" #: howto/logging-cookbook.rst:1753 msgid "Implementing structured logging" msgstr "" #: howto/logging-cookbook.rst:1755 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 "" #: howto/logging-cookbook.rst:1779 msgid "If the above script is run, it prints:" msgstr "" #: howto/logging-cookbook.rst:1785 howto/logging-cookbook.rst:1827 msgid "" "Note that the order of items might be different according to the version of " "Python used." msgstr "" #: howto/logging-cookbook.rst:1788 msgid "" "If you need more specialised processing, you can use a custom JSON encoder, " "as in the following complete example::" msgstr "" #: howto/logging-cookbook.rst:1821 msgid "When the above script is run, it prints:" msgstr "" #: howto/logging-cookbook.rst:1836 msgid "Customizing handlers with :func:`dictConfig`" msgstr "" #: howto/logging-cookbook.rst:1838 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 "" #: howto/logging-cookbook.rst:1852 msgid "" "You can then specify, in a logging configuration passed to :func:" "`dictConfig`, that a logging handler be created by calling this function::" msgstr "" #: howto/logging-cookbook.rst:1885 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 "" #: howto/logging-cookbook.rst:1932 msgid "To run this, you will probably need to run as ``root``:" msgstr "" #: howto/logging-cookbook.rst:1942 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 "" #: howto/logging-cookbook.rst:1948 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 "" #: howto/logging-cookbook.rst:1953 msgid "you could use e.g.::" msgstr "" #: howto/logging-cookbook.rst:1957 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 "" #: howto/logging-cookbook.rst:1962 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 "" #: howto/logging-cookbook.rst:1966 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 "" #: howto/logging-cookbook.rst:1976 msgid "Using particular formatting styles throughout your application" msgstr "" #: howto/logging-cookbook.rst:1978 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 "" #: howto/logging-cookbook.rst:1985 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 "" #: howto/logging-cookbook.rst:1997 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 "" #: howto/logging-cookbook.rst:2001 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 "" #: howto/logging-cookbook.rst:2008 msgid "Using LogRecord factories" msgstr "" #: howto/logging-cookbook.rst:2010 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 "" #: howto/logging-cookbook.rst:2021 msgid "" "Refer to the reference documentation on :func:`setLogRecordFactory` and :" "class:`LogRecord` for more information." msgstr "" #: howto/logging-cookbook.rst:2026 msgid "Using custom message objects" msgstr "" #: howto/logging-cookbook.rst:2028 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 "" #: howto/logging-cookbook.rst:2053 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 "" #: howto/logging-cookbook.rst:2061 msgid "" "Examples of this approach are given below. Firstly, formatting with :meth:" "`str.format`::" msgstr "" #: howto/logging-cookbook.rst:2075 msgid "Secondly, formatting with :class:`string.Template`::" msgstr "" #: howto/logging-cookbook.rst:2082 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 "" #: howto/logging-cookbook.rst:2096 msgid "Configuring filters with :func:`dictConfig`" msgstr "" #: howto/logging-cookbook.rst:2098 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 "" #: howto/logging-cookbook.rst:2151 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 "" #: howto/logging-cookbook.rst:2159 msgid "which shows that the filter is working as configured." msgstr "" #: howto/logging-cookbook.rst:2161 msgid "A couple of extra points to note:" msgstr "" #: howto/logging-cookbook.rst:2163 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 "" #: howto/logging-cookbook.rst:2170 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 "" #: howto/logging-cookbook.rst:2179 msgid "Customized exception formatting" msgstr "" #: howto/logging-cookbook.rst:2181 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 "" #: howto/logging-cookbook.rst:2222 msgid "When run, this produces a file with exactly two lines:" msgstr "" #: howto/logging-cookbook.rst:2229 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 "" #: howto/logging-cookbook.rst:2236 msgid "Speaking logging messages" msgstr "" #: howto/logging-cookbook.rst:2238 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 "" #: howto/logging-cookbook.rst:2280 msgid "" "When run, this script should say \"Hello\" and then \"Goodbye\" in a female " "voice." msgstr "" #: howto/logging-cookbook.rst:2282 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 "" #: howto/logging-cookbook.rst:2290 msgid "Buffering logging messages and outputting them conditionally" msgstr "" #: howto/logging-cookbook.rst:2292 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 "" #: howto/logging-cookbook.rst:2299 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 "" #: howto/logging-cookbook.rst:2309 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 "" #: howto/logging-cookbook.rst:2315 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 "" #: howto/logging-cookbook.rst:2323 msgid "Here's the script::" msgstr "" #: howto/logging-cookbook.rst:2386 msgid "When this script is run, the following output should be observed:" msgstr "" #: howto/logging-cookbook.rst:2416 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 "" #: howto/logging-cookbook.rst:2420 msgid "You can of course use the conventional means of decoration::" msgstr "" #: howto/logging-cookbook.rst:2430 msgid "Formatting times using UTC (GMT) via configuration" msgstr "" #: howto/logging-cookbook.rst:2432 msgid "" "Sometimes you want to format times using UTC, which can be done using a " "class such as `UTCFormatter`, shown below::" msgstr "" #: howto/logging-cookbook.rst:2441 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 "" #: howto/logging-cookbook.rst:2484 msgid "When this script is run, it should print something like:" msgstr "" #: howto/logging-cookbook.rst:2491 msgid "" "showing how the time is formatted both as local time and UTC, one for each " "handler." msgstr "" #: howto/logging-cookbook.rst:2498 msgid "Using a context manager for selective logging" msgstr "" #: howto/logging-cookbook.rst:2500 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 "" #: howto/logging-cookbook.rst:2533 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 "" #: howto/logging-cookbook.rst:2539 msgid "" "To illustrate how it works, we can add the following block of code to the " "above::" msgstr "" #: howto/logging-cookbook.rst:2557 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 "" #: howto/logging-cookbook.rst:2567 msgid "If we run the resulting script, the result is as follows:" msgstr "" #: howto/logging-cookbook.rst:2578 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 "" #: howto/logging-cookbook.rst:2586 msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:" msgstr "" #: howto/logging-cookbook.rst:2596 msgid "" "In this case, the message #5 printed to ``stdout`` doesn't appear, as " "expected." msgstr "" #: howto/logging-cookbook.rst:2598 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 "" #: howto/logging-cookbook.rst:2606 msgid "A CLI application starter template" msgstr "" #: howto/logging-cookbook.rst:2608 msgid "Here's an example which shows how you can:" msgstr "" #: howto/logging-cookbook.rst:2610 msgid "Use a logging level based on command-line arguments" msgstr "" #: howto/logging-cookbook.rst:2611 msgid "" "Dispatch to multiple subcommands in separate files, all logging at the same " "level in a consistent way" msgstr "" #: howto/logging-cookbook.rst:2613 msgid "Make use of simple, minimal configuration" msgstr "" #: howto/logging-cookbook.rst:2615 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 "" #: howto/logging-cookbook.rst:2664 msgid "" "And the ``start``, ``stop`` and ``restart`` commands can be implemented in " "separate modules, like so for starting::" msgstr "" #: howto/logging-cookbook.rst:2677 msgid "and thus for stopping::" msgstr "" #: howto/logging-cookbook.rst:2698 msgid "and similarly for restarting::" msgstr "" #: howto/logging-cookbook.rst:2719 msgid "" "If we run this application with the default log level, we get output like " "this:" msgstr "" #: howto/logging-cookbook.rst:2732 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 "" #: howto/logging-cookbook.rst:2735 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 "" #: howto/logging-cookbook.rst:2752 msgid "And if we want less:" msgstr "" #: howto/logging-cookbook.rst:2760 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 "" #: howto/logging-cookbook.rst:2766 msgid "A Qt GUI for logging" msgstr "" #: howto/logging-cookbook.rst:2768 msgid "" "A question that comes up from time to time is about how to log to a GUI " "application. The `Qt `_ framework is a popular cross-" "platform UI framework with Python bindings using `PySide2 `_ or `PyQt5 `_ libraries." msgstr "" #: howto/logging-cookbook.rst:2774 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 "" #: howto/logging-cookbook.rst:2781 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 "" #: howto/logging-cookbook.rst:2785 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 "" #: howto/logging-cookbook.rst:3002 msgid "Patterns to avoid" msgstr "" #: howto/logging-cookbook.rst:3004 msgid "" "Although the preceding sections have described ways of doing things you " "might need to do or deal with, it is worth mentioning some usage patterns " "which are *unhelpful*, and which should therefore be avoided in most cases. " "The following sections are in no particular order." msgstr "" #: howto/logging-cookbook.rst:3011 msgid "Opening the same log file multiple times" msgstr "" #: howto/logging-cookbook.rst:3013 msgid "" "On Windows, you will generally not be able to open the same file multiple " "times as this will lead to a \"file is in use by another process\" error. " "However, on POSIX platforms you'll not get any errors if you open the same " "file multiple times. This could be done accidentally, for example by:" msgstr "" #: howto/logging-cookbook.rst:3018 msgid "" "Adding a file handler more than once which references the same file (e.g. by " "a copy/paste/forget-to-change error)." msgstr "" #: howto/logging-cookbook.rst:3021 msgid "" "Opening two files that look different, as they have different names, but are " "the same because one is a symbolic link to the other." msgstr "" #: howto/logging-cookbook.rst:3024 msgid "" "Forking a process, following which both parent and child have a reference to " "the same file. This might be through use of the :mod:`multiprocessing` " "module, for example." msgstr "" #: howto/logging-cookbook.rst:3028 msgid "" "Opening a file multiple times might *appear* to work most of the time, but " "can lead to a number of problems in practice:" msgstr "" #: howto/logging-cookbook.rst:3031 msgid "" "Logging output can be garbled because multiple threads or processes try to " "write to the same file. Although logging guards against concurrent use of " "the same handler instance by multiple threads, there is no such protection " "if concurrent writes are attempted by two different threads using two " "different handler instances which happen to point to the same file." msgstr "" #: howto/logging-cookbook.rst:3037 msgid "" "An attempt to delete a file (e.g. during file rotation) silently fails, " "because there is another reference pointing to it. This can lead to " "confusion and wasted debugging time - log entries end up in unexpected " "places, or are lost altogether. Or a file that was supposed to be moved " "remains in place, and grows in size unexpectedly despite size-based rotation " "being supposedly in place." msgstr "" #: howto/logging-cookbook.rst:3044 msgid "" "Use the techniques outlined in :ref:`multiple-processes` to circumvent such " "issues." msgstr "" #: howto/logging-cookbook.rst:3048 msgid "Using loggers as attributes in a class or passing them as parameters" msgstr "" #: howto/logging-cookbook.rst:3050 msgid "" "While there might be unusual cases where you'll need to do this, in general " "there is no point because loggers are singletons. Code can always access a " "given logger instance by name using ``logging.getLogger(name)``, so passing " "instances around and holding them as instance attributes is pointless. Note " "that in other languages such as Java and C#, loggers are often static class " "attributes. However, this pattern doesn't make sense in Python, where the " "module (and not the class) is the unit of software decomposition." msgstr "" #: howto/logging-cookbook.rst:3060 msgid "" "Adding handlers other than :class:`NullHandler` to a logger in a library" msgstr "" #: howto/logging-cookbook.rst:3062 msgid "" "Configuring logging by adding handlers, formatters and filters is the " "responsibility of the application developer, not the library developer. If " "you are maintaining a library, ensure that you don't add handlers to any of " "your loggers other than a :class:`~logging.NullHandler` instance." msgstr "" #: howto/logging-cookbook.rst:3069 msgid "Creating a lot of loggers" msgstr "" #: howto/logging-cookbook.rst:3071 msgid "" "Loggers are singletons that are never freed during a script execution, and " "so creating lots of loggers will use up memory which can't then be freed. " "Rather than create a logger per e.g. file processed or network connection " "made, use the :ref:`existing mechanisms ` for passing " "contextual information into your logs and restrict the loggers created to " "those describing areas within your application (generally modules, but " "occasionally slightly more fine-grained than that)." msgstr ""