# Copyright (C) 2001-2020, Python Software Foundation

# This file is distributed under the same license as the Python package.

# Maintained by the python-doc-es workteam.

# docs-es@python.org /

# https://mail.python.org/mailman3/lists/docs-es.python.org/

# Check https://github.com/python/python-docs-es/blob/3.8/TRANSLATORS to

# get the list of volunteers

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.8\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2020-05-05 12:54+0200\n"

"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

"Language-Team: python-doc-es\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=utf-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Generated-By: Babel 2.8.0\n"

#: ../Doc/howto/logging-cookbook.rst:5

msgid "Logging Cookbook"

msgstr ""

#: ../Doc/howto/logging-cookbook.rst

msgid "Author"

msgstr ""

#: ../Doc/howto/logging-cookbook.rst:7

msgid "Vinay Sajip <vinay_sajip at red-dove dot com>"

msgstr ""

#: ../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 ""

#: ../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

#, python-format

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

#, python-format

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

#, python-format

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

#, python-format

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 ""

#: ../Doc/howto/logging-cookbook.rst:1354

msgid "API reference for the logging module."

msgstr ""

#: ../Doc/howto/logging-cookbook.rst:1357

msgid "Module :mod:`logging.config`"

msgstr ""

#: ../Doc/howto/logging-cookbook.rst:1357

msgid "Configuration API for the logging module."

msgstr ""

#: ../Doc/howto/logging-cookbook.rst:1360

msgid "Module :mod:`logging.handlers`"

msgstr ""

#: ../Doc/howto/logging-cookbook.rst:1360

msgid "Useful handlers included with the logging module."

msgstr ""

#: ../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