diff --git a/howto/logging-cookbook.po b/howto/logging-cookbook.po index 76d730ddb7..f7a0a30bcf 100644 --- a/howto/logging-cookbook.po +++ b/howto/logging-cookbook.po @@ -7,7 +7,7 @@ msgid "" msgstr "" "Project-Id-Version: Python 3.10\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2022-10-13 00:23+0000\n" +"POT-Creation-Date: 2022-10-16 00:24+0000\n" "PO-Revision-Date: 2018-05-23 14:36+0000\n" "Last-Translator: Adrian Liaw \n" "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" @@ -158,33 +158,103 @@ msgid "" "files in it." msgstr "" -#: ../../howto/logging-cookbook.rst:280 +#: ../../howto/logging-cookbook.rst:282 +msgid "Custom handling of levels" +msgstr "" + +#: ../../howto/logging-cookbook.rst:284 +msgid "" +"Sometimes, you might want to do something slightly different from the " +"standard handling of levels in handlers, where all levels above a threshold " +"get processed by a handler. To do this, you need to use filters. Let's look " +"at a scenario where you want to arrange things as follows:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:289 +msgid "Send messages of severity ``INFO`` and ``WARNING`` to ``sys.stdout``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:290 +msgid "Send messages of severity ``ERROR`` and above to ``sys.stderr``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:291 +msgid "Send messages of severity ``DEBUG`` and above to file ``app.log``" +msgstr "" + +#: ../../howto/logging-cookbook.rst:293 +msgid "Suppose you configure logging with the following JSON:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:335 +msgid "" +"This configuration does *almost* what we want, except that ``sys.stdout`` " +"would show messages of severity ``ERROR`` and above as well as ``INFO`` and " +"``WARNING`` messages. To prevent this, we can set up a filter which excludes " +"those messages and add it to the relevant handler. This can be configured by " +"adding a ``filters`` section parallel to ``formatters`` and ``handlers``:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:350 +msgid "and changing the section on the ``stdout`` handler to add it:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:362 +msgid "" +"A filter is just a function, so we can define the ``filter_maker`` (a " +"factory function) as follows:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:375 +msgid "" +"This converts the string argument passed in to a numeric level, and returns " +"a function which only returns ``True`` if the level of the passed in record " +"is at or below the specified level. Note that in this example I have defined " +"the ``filter_maker`` in a test script ``main.py`` that I run from the " +"command line, so its module will be ``__main__`` - hence the ``__main__." +"filter_maker`` in the filter configuration. You will need to change that if " +"you define it in a different module." +msgstr "" + +#: ../../howto/logging-cookbook.rst:383 +msgid "With the filter added, we can run ``main.py``, which in full is:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:453 +msgid "And after running it like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:459 +msgid "We can see the results are as expected:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:485 msgid "Configuration server example" msgstr "" -#: ../../howto/logging-cookbook.rst:282 +#: ../../howto/logging-cookbook.rst:487 msgid "Here is an example of a module using the logging configuration server::" msgstr "" -#: ../../howto/logging-cookbook.rst:313 +#: ../../howto/logging-cookbook.rst:518 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:338 +#: ../../howto/logging-cookbook.rst:543 msgid "Dealing with handlers that block" msgstr "" -#: ../../howto/logging-cookbook.rst:342 +#: ../../howto/logging-cookbook.rst:547 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:346 +#: ../../howto/logging-cookbook.rst:551 msgid "" "A common culprit which demonstrates sluggish behaviour is the :class:" "`SMTPHandler`: sending emails can take a long time, for a number of reasons " @@ -195,7 +265,7 @@ msgid "" "below the Python layer, and outside your control)." msgstr "" -#: ../../howto/logging-cookbook.rst:354 +#: ../../howto/logging-cookbook.rst:559 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-" @@ -209,7 +279,7 @@ msgid "" "developers who will use your code." msgstr "" -#: ../../howto/logging-cookbook.rst:365 +#: ../../howto/logging-cookbook.rst:570 msgid "" "The second part of the solution is :class:`QueueListener`, which has been " "designed as the counterpart to :class:`QueueHandler`. A :class:" @@ -220,7 +290,7 @@ msgid "" "handlers for processing." msgstr "" -#: ../../howto/logging-cookbook.rst:373 +#: ../../howto/logging-cookbook.rst:578 msgid "" "The advantage of having a separate :class:`QueueListener` class is that you " "can use the same instance to service multiple ``QueueHandlers``. This is " @@ -229,15 +299,15 @@ msgid "" "benefit." msgstr "" -#: ../../howto/logging-cookbook.rst:378 +#: ../../howto/logging-cookbook.rst:583 msgid "An example of using these two classes follows (imports omitted)::" msgstr "" -#: ../../howto/logging-cookbook.rst:396 +#: ../../howto/logging-cookbook.rst:601 msgid "which, when run, will produce:" msgstr "" -#: ../../howto/logging-cookbook.rst:402 +#: ../../howto/logging-cookbook.rst:607 msgid "" "Although the earlier discussion wasn't specifically talking about async " "code, but rather about slow logging handlers, it should be noted that when " @@ -248,7 +318,7 @@ msgid "" "code runs only in the ``QueueListener`` thread." msgstr "" -#: ../../howto/logging-cookbook.rst:410 +#: ../../howto/logging-cookbook.rst:615 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 " @@ -260,30 +330,30 @@ msgid "" "handler if it's appropriate to do so." msgstr "" -#: ../../howto/logging-cookbook.rst:423 +#: ../../howto/logging-cookbook.rst:628 msgid "Sending and receiving logging events across a network" msgstr "" -#: ../../howto/logging-cookbook.rst:425 +#: ../../howto/logging-cookbook.rst:630 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:453 +#: ../../howto/logging-cookbook.rst:658 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:541 +#: ../../howto/logging-cookbook.rst:746 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:553 +#: ../../howto/logging-cookbook.rst:758 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 " @@ -292,25 +362,25 @@ msgid "" "use your alternative serialization." msgstr "" -#: ../../howto/logging-cookbook.rst:561 +#: ../../howto/logging-cookbook.rst:766 msgid "Running a logging socket listener in production" msgstr "" -#: ../../howto/logging-cookbook.rst:563 +#: ../../howto/logging-cookbook.rst:768 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." +"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:574 +#: ../../howto/logging-cookbook.rst:779 msgid "Adding contextual information to your logging output" msgstr "" -#: ../../howto/logging-cookbook.rst:576 +#: ../../howto/logging-cookbook.rst:781 msgid "" "Sometimes you want logging output to contain contextual information in " "addition to the parameters passed to the logging call. For example, in a " @@ -326,11 +396,11 @@ msgid "" "`Logger` instances becomes effectively unbounded." msgstr "" -#: ../../howto/logging-cookbook.rst:591 +#: ../../howto/logging-cookbook.rst:796 msgid "Using LoggerAdapters to impart contextual information" msgstr "" -#: ../../howto/logging-cookbook.rst:593 +#: ../../howto/logging-cookbook.rst:798 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. " @@ -341,7 +411,7 @@ msgid "" "types of instances interchangeably." msgstr "" -#: ../../howto/logging-cookbook.rst:601 +#: ../../howto/logging-cookbook.rst:806 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 " @@ -352,7 +422,7 @@ msgid "" "of :class:`LoggerAdapter`::" msgstr "" -#: ../../howto/logging-cookbook.rst:617 +#: ../../howto/logging-cookbook.rst:822 msgid "" "The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where " "the contextual information is added to the logging output. It's passed the " @@ -365,7 +435,7 @@ msgid "" "be silently overwritten." msgstr "" -#: ../../howto/logging-cookbook.rst:626 +#: ../../howto/logging-cookbook.rst:831 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 " @@ -376,21 +446,21 @@ msgid "" "`~LoggerAdapter.process` to do what you need. Here is a simple example::" msgstr "" -#: ../../howto/logging-cookbook.rst:642 +#: ../../howto/logging-cookbook.rst:847 msgid "which you can use like this::" msgstr "" -#: ../../howto/logging-cookbook.rst:647 +#: ../../howto/logging-cookbook.rst:852 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:651 +#: ../../howto/logging-cookbook.rst:856 msgid "Using objects other than dicts to pass contextual information" msgstr "" -#: ../../howto/logging-cookbook.rst:653 +#: ../../howto/logging-cookbook.rst:858 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 " @@ -399,11 +469,11 @@ msgid "" "would be constant)." msgstr "" -#: ../../howto/logging-cookbook.rst:662 +#: ../../howto/logging-cookbook.rst:867 msgid "Using Filters to impart contextual information" msgstr "" -#: ../../howto/logging-cookbook.rst:664 +#: ../../howto/logging-cookbook.rst:869 msgid "" "You can also add contextual information to log output using a user-defined :" "class:`Filter`. ``Filter`` instances are allowed to modify the " @@ -412,7 +482,7 @@ msgid "" "class:`Formatter`." msgstr "" -#: ../../howto/logging-cookbook.rst:669 +#: ../../howto/logging-cookbook.rst:874 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:" @@ -424,15 +494,15 @@ msgid "" "an example script::" msgstr "" -#: ../../howto/logging-cookbook.rst:715 +#: ../../howto/logging-cookbook.rst:920 msgid "which, when run, produces something like:" msgstr "" -#: ../../howto/logging-cookbook.rst:733 +#: ../../howto/logging-cookbook.rst:938 msgid "Use of ``contextvars``" msgstr "" -#: ../../howto/logging-cookbook.rst:735 +#: ../../howto/logging-cookbook.rst:940 msgid "" "Since Python 3.7, the :mod:`contextvars` module has provided context-local " "storage which works for both :mod:`threading` and :mod:`asyncio` processing " @@ -442,7 +512,7 @@ msgid "" "attributes handled by web applications." msgstr "" -#: ../../howto/logging-cookbook.rst:741 +#: ../../howto/logging-cookbook.rst:946 msgid "" "For the purposes of illustration, say that you have different web " "applications, each independent of the other but running in the same Python " @@ -453,18 +523,18 @@ msgid "" "information such as client IP, HTTP request method and client username?" msgstr "" -#: ../../howto/logging-cookbook.rst:748 +#: ../../howto/logging-cookbook.rst:953 msgid "Let's assume that the library can be simulated by the following code:" msgstr "" -#: ../../howto/logging-cookbook.rst:764 +#: ../../howto/logging-cookbook.rst:969 msgid "" "We can simulate the multiple web applications by means of two simple " "classes, ``Request`` and ``WebApp``. These simulate how real threaded web " "applications work - each request is handled by a thread:" msgstr "" -#: ../../howto/logging-cookbook.rst:908 +#: ../../howto/logging-cookbook.rst:1113 msgid "" "If you run the above, you should find that roughly half the requests go " "into :file:`app1.log` and the rest into :file:`app2.log`, and the all the " @@ -475,11 +545,11 @@ msgid "" "illustrated by the following shell output:" msgstr "" -#: ../../howto/logging-cookbook.rst:955 +#: ../../howto/logging-cookbook.rst:1160 msgid "Imparting contextual information in handlers" msgstr "" -#: ../../howto/logging-cookbook.rst:957 +#: ../../howto/logging-cookbook.rst:1162 msgid "" "Each :class:`~Handler` has its own chain of filters. If you want to add " "contextual information to a :class:`LogRecord` without leaking it to other " @@ -487,11 +557,11 @@ msgid "" "instead of modifying it in-place, as shown in the following script::" msgstr "" -#: ../../howto/logging-cookbook.rst:984 +#: ../../howto/logging-cookbook.rst:1189 msgid "Logging to a single file from multiple processes" msgstr "" -#: ../../howto/logging-cookbook.rst:986 +#: ../../howto/logging-cookbook.rst:1191 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 " @@ -507,7 +577,7 @@ msgid "" "you to adapt in your own applications." msgstr "" -#: ../../howto/logging-cookbook.rst:999 +#: ../../howto/logging-cookbook.rst:1204 msgid "" "You could also write your own handler which uses the :class:" "`~multiprocessing.Lock` class from the :mod:`multiprocessing` module to " @@ -518,7 +588,7 @@ msgid "" "platforms (see https://bugs.python.org/issue3770)." msgstr "" -#: ../../howto/logging-cookbook.rst:1009 +#: ../../howto/logging-cookbook.rst:1214 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 " @@ -533,13 +603,13 @@ msgid "" "requirements::" msgstr "" -#: ../../howto/logging-cookbook.rst:1125 +#: ../../howto/logging-cookbook.rst:1330 msgid "" "A variant of the above script keeps the logging in the main process, in a " "separate thread::" msgstr "" -#: ../../howto/logging-cookbook.rst:1220 +#: ../../howto/logging-cookbook.rst:1425 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 " @@ -549,34 +619,34 @@ msgid "" "appropriate destinations." msgstr "" -#: ../../howto/logging-cookbook.rst:1227 +#: ../../howto/logging-cookbook.rst:1432 msgid "Using concurrent.futures.ProcessPoolExecutor" msgstr "" -#: ../../howto/logging-cookbook.rst:1229 +#: ../../howto/logging-cookbook.rst:1434 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:1237 +#: ../../howto/logging-cookbook.rst:1442 msgid "you should use" msgstr "" -#: ../../howto/logging-cookbook.rst:1243 +#: ../../howto/logging-cookbook.rst:1448 msgid "and you can then replace the worker creation from this::" msgstr "" -#: ../../howto/logging-cookbook.rst:1254 +#: ../../howto/logging-cookbook.rst:1459 msgid "to this (remembering to first import :mod:`concurrent.futures`)::" msgstr "" -#: ../../howto/logging-cookbook.rst:1261 +#: ../../howto/logging-cookbook.rst:1466 msgid "Deploying Web applications using Gunicorn and uWSGI" msgstr "" -#: ../../howto/logging-cookbook.rst:1263 +#: ../../howto/logging-cookbook.rst:1468 msgid "" "When deploying Web applications using `Gunicorn `_ or " "`uWSGI `_ (or similar), " @@ -588,11 +658,11 @@ msgid "" "listener in production`_ for more details." msgstr "" -#: ../../howto/logging-cookbook.rst:1273 +#: ../../howto/logging-cookbook.rst:1478 msgid "Using file rotation" msgstr "" -#: ../../howto/logging-cookbook.rst:1278 +#: ../../howto/logging-cookbook.rst:1483 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, " @@ -602,13 +672,13 @@ msgid "" "RotatingFileHandler`::" msgstr "" -#: ../../howto/logging-cookbook.rst:1310 +#: ../../howto/logging-cookbook.rst:1515 msgid "" "The result should be 6 separate files, each with part of the log history for " "the application:" msgstr "" -#: ../../howto/logging-cookbook.rst:1322 +#: ../../howto/logging-cookbook.rst:1527 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 " @@ -616,17 +686,17 @@ msgid "" "(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased." msgstr "" -#: ../../howto/logging-cookbook.rst:1327 +#: ../../howto/logging-cookbook.rst:1532 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:1333 +#: ../../howto/logging-cookbook.rst:1538 msgid "Use of alternative formatting styles" msgstr "" -#: ../../howto/logging-cookbook.rst:1335 +#: ../../howto/logging-cookbook.rst:1540 msgid "" "When logging was added to the Python standard library, the only way of " "formatting messages with variable content was to use the %-formatting " @@ -635,7 +705,7 @@ msgid "" "Python 2.6)." msgstr "" -#: ../../howto/logging-cookbook.rst:1341 +#: ../../howto/logging-cookbook.rst:1546 msgid "" "Logging (as of 3.2) provides improved support for these two additional " "formatting styles. The :class:`Formatter` class been enhanced to take an " @@ -648,14 +718,14 @@ msgid "" "session to show the possibilities:" msgstr "" -#: ../../howto/logging-cookbook.rst:1375 +#: ../../howto/logging-cookbook.rst:1580 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:1383 +#: ../../howto/logging-cookbook.rst:1588 msgid "" "Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take " "positional parameters for the actual logging message itself, with keyword " @@ -671,7 +741,7 @@ msgid "" "strings." msgstr "" -#: ../../howto/logging-cookbook.rst:1396 +#: ../../howto/logging-cookbook.rst:1601 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 " @@ -680,7 +750,7 @@ msgid "" "the following two classes::" msgstr "" -#: ../../howto/logging-cookbook.rst:1420 +#: ../../howto/logging-cookbook.rst:1625 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 " @@ -691,21 +761,21 @@ msgid "" "used as a synonym/alias for :func:`gettext.gettext` or its brethren)." msgstr "" -#: ../../howto/logging-cookbook.rst:1428 +#: ../../howto/logging-cookbook.rst:1633 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:1450 +#: ../../howto/logging-cookbook.rst:1655 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:1454 +#: ../../howto/logging-cookbook.rst:1659 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 " @@ -716,23 +786,23 @@ msgid "" "sugar for a constructor call to one of the XXXMessage classes." msgstr "" -#: ../../howto/logging-cookbook.rst:1462 +#: ../../howto/logging-cookbook.rst:1667 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:1493 +#: ../../howto/logging-cookbook.rst:1698 msgid "" "The above script should log the message ``Hello, world!`` when run with " "Python 3.2 or later." msgstr "" -#: ../../howto/logging-cookbook.rst:1502 +#: ../../howto/logging-cookbook.rst:1707 msgid "Customizing ``LogRecord``" msgstr "" -#: ../../howto/logging-cookbook.rst:1504 +#: ../../howto/logging-cookbook.rst:1709 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:" @@ -743,13 +813,13 @@ msgid "" "was done:" msgstr "" -#: ../../howto/logging-cookbook.rst:1511 +#: ../../howto/logging-cookbook.rst:1716 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:1514 +#: ../../howto/logging-cookbook.rst:1719 msgid "" ":func:`makeLogRecord`, which is called with a dictionary containing " "attributes to be added to the LogRecord. This is typically invoked when a " @@ -758,27 +828,27 @@ msgid "" "`~handlers.HTTPHandler`)." msgstr "" -#: ../../howto/logging-cookbook.rst:1520 +#: ../../howto/logging-cookbook.rst:1725 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:1523 +#: ../../howto/logging-cookbook.rst:1728 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:1526 +#: ../../howto/logging-cookbook.rst:1731 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:1530 +#: ../../howto/logging-cookbook.rst:1735 msgid "" "The first approach would be a little unwieldy in the scenario where (say) " "several different libraries wanted to do different things. Each would " @@ -786,7 +856,7 @@ msgid "" "last would win." msgstr "" -#: ../../howto/logging-cookbook.rst:1535 +#: ../../howto/logging-cookbook.rst:1740 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 " @@ -795,7 +865,7 @@ msgid "" "would do simply by adding new packages or modules and doing ::" msgstr "" -#: ../../howto/logging-cookbook.rst:1543 +#: ../../howto/logging-cookbook.rst:1748 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` " @@ -805,7 +875,7 @@ msgid "" "developer." msgstr "" -#: ../../howto/logging-cookbook.rst:1549 +#: ../../howto/logging-cookbook.rst:1754 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 " @@ -815,7 +885,7 @@ msgid "" "`LogRecord` is the default setting for the factory." msgstr "" -#: ../../howto/logging-cookbook.rst:1556 +#: ../../howto/logging-cookbook.rst:1761 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 " @@ -823,7 +893,7 @@ msgid "" "this::" msgstr "" -#: ../../howto/logging-cookbook.rst:1569 +#: ../../howto/logging-cookbook.rst:1774 msgid "" "This pattern allows different libraries to chain factories together, and as " "long as they don't overwrite each other's attributes or unintentionally " @@ -833,70 +903,70 @@ msgid "" "used when the use of a :class:`Filter` does not provide the desired result." msgstr "" -#: ../../howto/logging-cookbook.rst:1580 +#: ../../howto/logging-cookbook.rst:1785 msgid "Subclassing QueueHandler - a ZeroMQ example" msgstr "" -#: ../../howto/logging-cookbook.rst:1582 +#: ../../howto/logging-cookbook.rst:1787 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:1601 +#: ../../howto/logging-cookbook.rst:1806 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:1619 +#: ../../howto/logging-cookbook.rst:1824 msgid "Subclassing QueueListener - a ZeroMQ example" msgstr "" -#: ../../howto/logging-cookbook.rst:1621 +#: ../../howto/logging-cookbook.rst:1826 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:1640 ../../howto/logging-cookbook.rst:3522 +#: ../../howto/logging-cookbook.rst:1845 ../../howto/logging-cookbook.rst:3803 msgid "Module :mod:`logging`" msgstr ":mod:`logging` 模組" -#: ../../howto/logging-cookbook.rst:1640 ../../howto/logging-cookbook.rst:3522 +#: ../../howto/logging-cookbook.rst:1845 ../../howto/logging-cookbook.rst:3803 msgid "API reference for the logging module." msgstr "" -#: ../../howto/logging-cookbook.rst:1643 ../../howto/logging-cookbook.rst:3525 +#: ../../howto/logging-cookbook.rst:1848 ../../howto/logging-cookbook.rst:3806 msgid "Module :mod:`logging.config`" msgstr ":mod:`logging.config` 模組" -#: ../../howto/logging-cookbook.rst:1643 ../../howto/logging-cookbook.rst:3525 +#: ../../howto/logging-cookbook.rst:1848 ../../howto/logging-cookbook.rst:3806 msgid "Configuration API for the logging module." msgstr "" -#: ../../howto/logging-cookbook.rst:1646 ../../howto/logging-cookbook.rst:3528 +#: ../../howto/logging-cookbook.rst:1851 ../../howto/logging-cookbook.rst:3809 msgid "Module :mod:`logging.handlers`" msgstr ":mod:`logging.handlers` 模組" -#: ../../howto/logging-cookbook.rst:1646 ../../howto/logging-cookbook.rst:3528 +#: ../../howto/logging-cookbook.rst:1851 ../../howto/logging-cookbook.rst:3809 msgid "Useful handlers included with the logging module." msgstr "" -#: ../../howto/logging-cookbook.rst:1648 +#: ../../howto/logging-cookbook.rst:1853 msgid ":ref:`A basic logging tutorial `" msgstr "" -#: ../../howto/logging-cookbook.rst:1650 +#: ../../howto/logging-cookbook.rst:1855 msgid ":ref:`A more advanced logging tutorial `" msgstr "" -#: ../../howto/logging-cookbook.rst:1654 +#: ../../howto/logging-cookbook.rst:1859 msgid "An example dictionary-based configuration" msgstr "" -#: ../../howto/logging-cookbook.rst:1656 +#: ../../howto/logging-cookbook.rst:1861 msgid "" "Below is an example of a logging configuration dictionary - it's taken from " "the `documentation on the Django project `_ of the Django documentation." msgstr "" -#: ../../howto/logging-cookbook.rst:1719 +#: ../../howto/logging-cookbook.rst:1924 msgid "Using a rotator and namer to customize log rotation processing" msgstr "" -#: ../../howto/logging-cookbook.rst:1721 +#: ../../howto/logging-cookbook.rst:1926 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:1739 +#: ../../howto/logging-cookbook.rst:1944 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:1744 +#: ../../howto/logging-cookbook.rst:1949 msgid "A more elaborate multiprocessing example" msgstr "" -#: ../../howto/logging-cookbook.rst:1746 +#: ../../howto/logging-cookbook.rst:1951 msgid "" "The following working example shows how logging can be used with " "multiprocessing using configuration files. The configurations are fairly " @@ -940,7 +1010,7 @@ msgid "" "in a real multiprocessing scenario." msgstr "" -#: ../../howto/logging-cookbook.rst:1751 +#: ../../howto/logging-cookbook.rst:1956 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 " @@ -953,17 +1023,17 @@ msgid "" "own scenario." msgstr "" -#: ../../howto/logging-cookbook.rst:1761 +#: ../../howto/logging-cookbook.rst:1966 msgid "" "Here's the script - the docstrings and the comments hopefully explain how it " "works::" msgstr "" -#: ../../howto/logging-cookbook.rst:1973 +#: ../../howto/logging-cookbook.rst:2178 msgid "Inserting a BOM into messages sent to a SysLogHandler" msgstr "" -#: ../../howto/logging-cookbook.rst:1975 +#: ../../howto/logging-cookbook.rst:2180 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 " @@ -972,7 +1042,7 @@ msgid "" "<5424#section-6>`.)" msgstr "" -#: ../../howto/logging-cookbook.rst:1981 +#: ../../howto/logging-cookbook.rst:2186 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 " @@ -980,7 +1050,7 @@ msgid "" "hence not allowing any pure-ASCII component to appear before it." msgstr "" -#: ../../howto/logging-cookbook.rst:1987 +#: ../../howto/logging-cookbook.rst:2192 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 " @@ -989,33 +1059,33 @@ msgid "" "encoded using UTF-8, then you need to do the following:" msgstr "" -#: ../../howto/logging-cookbook.rst:1993 +#: ../../howto/logging-cookbook.rst:2198 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:1999 +#: ../../howto/logging-cookbook.rst:2204 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:2002 +#: ../../howto/logging-cookbook.rst:2207 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:2006 +#: ../../howto/logging-cookbook.rst:2211 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:2010 +#: ../../howto/logging-cookbook.rst:2215 msgid "" "The formatted message *will* be encoded using UTF-8 encoding by " "``SysLogHandler``. If you follow the above rules, you should be able to " @@ -1024,11 +1094,11 @@ msgid "" "daemon may complain." msgstr "" -#: ../../howto/logging-cookbook.rst:2017 +#: ../../howto/logging-cookbook.rst:2222 msgid "Implementing structured logging" msgstr "" -#: ../../howto/logging-cookbook.rst:2019 +#: ../../howto/logging-cookbook.rst:2224 msgid "" "Although most logging messages are intended for reading by humans, and thus " "not readily machine-parseable, there might be circumstances where you want " @@ -1040,31 +1110,31 @@ msgid "" "machine-parseable manner::" msgstr "" -#: ../../howto/logging-cookbook.rst:2043 +#: ../../howto/logging-cookbook.rst:2248 msgid "If the above script is run, it prints:" msgstr "" -#: ../../howto/logging-cookbook.rst:2049 ../../howto/logging-cookbook.rst:2091 +#: ../../howto/logging-cookbook.rst:2254 ../../howto/logging-cookbook.rst:2296 msgid "" "Note that the order of items might be different according to the version of " "Python used." msgstr "" -#: ../../howto/logging-cookbook.rst:2052 +#: ../../howto/logging-cookbook.rst:2257 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:2085 +#: ../../howto/logging-cookbook.rst:2290 msgid "When the above script is run, it prints:" msgstr "" -#: ../../howto/logging-cookbook.rst:2100 +#: ../../howto/logging-cookbook.rst:2305 msgid "Customizing handlers with :func:`dictConfig`" msgstr "" -#: ../../howto/logging-cookbook.rst:2102 +#: ../../howto/logging-cookbook.rst:2307 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 " @@ -1074,24 +1144,24 @@ msgid "" "customize handler creation using a plain function such as::" msgstr "" -#: ../../howto/logging-cookbook.rst:2116 +#: ../../howto/logging-cookbook.rst:2321 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:2149 +#: ../../howto/logging-cookbook.rst:2354 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:2196 +#: ../../howto/logging-cookbook.rst:2401 msgid "To run this, you will probably need to run as ``root``:" msgstr "" -#: ../../howto/logging-cookbook.rst:2206 +#: ../../howto/logging-cookbook.rst:2411 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 " @@ -1100,17 +1170,17 @@ msgid "" "change using e.g. :func:`os.chown`." msgstr "" -#: ../../howto/logging-cookbook.rst:2212 +#: ../../howto/logging-cookbook.rst:2417 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:2217 +#: ../../howto/logging-cookbook.rst:2422 msgid "you could use e.g.::" msgstr "" -#: ../../howto/logging-cookbook.rst:2221 +#: ../../howto/logging-cookbook.rst:2426 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://" @@ -1118,25 +1188,25 @@ msgid "" "resolved by :func:`dictConfig` from the ``ext://`` specification." msgstr "" -#: ../../howto/logging-cookbook.rst:2226 +#: ../../howto/logging-cookbook.rst:2431 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:2230 +#: ../../howto/logging-cookbook.rst:2435 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:2240 +#: ../../howto/logging-cookbook.rst:2445 msgid "Using particular formatting styles throughout your application" msgstr "" -#: ../../howto/logging-cookbook.rst:2242 +#: ../../howto/logging-cookbook.rst:2447 msgid "" "In Python 3.2, the :class:`~logging.Formatter` gained a ``style`` keyword " "parameter which, while defaulting to ``%`` for backward compatibility, " @@ -1147,7 +1217,7 @@ msgid "" "is constructed." msgstr "" -#: ../../howto/logging-cookbook.rst:2249 +#: ../../howto/logging-cookbook.rst:2454 msgid "" "Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take " "positional parameters for the actual logging message itself, with keyword " @@ -1162,7 +1232,7 @@ msgid "" "calls which are out there in existing code will be using %-format strings." msgstr "" -#: ../../howto/logging-cookbook.rst:2261 +#: ../../howto/logging-cookbook.rst:2466 msgid "" "There have been suggestions to associate format styles with specific " "loggers, but that approach also runs into backward compatibility problems " @@ -1170,7 +1240,7 @@ msgid "" "formatting." msgstr "" -#: ../../howto/logging-cookbook.rst:2265 +#: ../../howto/logging-cookbook.rst:2470 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 " @@ -1178,11 +1248,11 @@ msgid "" "formatting styles can be accommodated." msgstr "" -#: ../../howto/logging-cookbook.rst:2272 +#: ../../howto/logging-cookbook.rst:2477 msgid "Using LogRecord factories" msgstr "" -#: ../../howto/logging-cookbook.rst:2274 +#: ../../howto/logging-cookbook.rst:2479 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 " @@ -1197,17 +1267,17 @@ msgid "" "implementation does." msgstr "" -#: ../../howto/logging-cookbook.rst:2285 +#: ../../howto/logging-cookbook.rst:2490 msgid "" "Refer to the reference documentation on :func:`setLogRecordFactory` and :" "class:`LogRecord` for more information." msgstr "" -#: ../../howto/logging-cookbook.rst:2290 +#: ../../howto/logging-cookbook.rst:2495 msgid "Using custom message objects" msgstr "" -#: ../../howto/logging-cookbook.rst:2292 +#: ../../howto/logging-cookbook.rst:2497 msgid "" "There is another, perhaps simpler way that you can use {}- and $- formatting " "to construct your individual log messages. You may recall (from :ref:" @@ -1217,7 +1287,7 @@ msgid "" "following two classes::" msgstr "" -#: ../../howto/logging-cookbook.rst:2317 +#: ../../howto/logging-cookbook.rst:2522 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 " @@ -1228,17 +1298,17 @@ msgid "" "using ``_`` for localization)." msgstr "" -#: ../../howto/logging-cookbook.rst:2325 +#: ../../howto/logging-cookbook.rst:2530 msgid "" "Examples of this approach are given below. Firstly, formatting with :meth:" "`str.format`::" msgstr "" -#: ../../howto/logging-cookbook.rst:2339 +#: ../../howto/logging-cookbook.rst:2544 msgid "Secondly, formatting with :class:`string.Template`::" msgstr "" -#: ../../howto/logging-cookbook.rst:2346 +#: ../../howto/logging-cookbook.rst:2551 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 " @@ -1250,11 +1320,11 @@ msgid "" "above." msgstr "" -#: ../../howto/logging-cookbook.rst:2360 +#: ../../howto/logging-cookbook.rst:2565 msgid "Configuring filters with :func:`dictConfig`" msgstr "" -#: ../../howto/logging-cookbook.rst:2362 +#: ../../howto/logging-cookbook.rst:2567 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). " @@ -1269,22 +1339,22 @@ msgid "" "complete example::" msgstr "" -#: ../../howto/logging-cookbook.rst:2415 +#: ../../howto/logging-cookbook.rst:2620 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:2423 +#: ../../howto/logging-cookbook.rst:2628 msgid "which shows that the filter is working as configured." msgstr "" -#: ../../howto/logging-cookbook.rst:2425 +#: ../../howto/logging-cookbook.rst:2630 msgid "A couple of extra points to note:" msgstr "" -#: ../../howto/logging-cookbook.rst:2427 +#: ../../howto/logging-cookbook.rst:2632 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 " @@ -1294,7 +1364,7 @@ msgid "" "the above example." msgstr "" -#: ../../howto/logging-cookbook.rst:2434 +#: ../../howto/logging-cookbook.rst:2639 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 " @@ -1303,11 +1373,11 @@ msgid "" "above." msgstr "" -#: ../../howto/logging-cookbook.rst:2443 +#: ../../howto/logging-cookbook.rst:2648 msgid "Customized exception formatting" msgstr "" -#: ../../howto/logging-cookbook.rst:2445 +#: ../../howto/logging-cookbook.rst:2650 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, " @@ -1315,22 +1385,22 @@ msgid "" "formatter class, as shown in the following example::" msgstr "" -#: ../../howto/logging-cookbook.rst:2486 +#: ../../howto/logging-cookbook.rst:2691 msgid "When run, this produces a file with exactly two lines:" msgstr "" -#: ../../howto/logging-cookbook.rst:2493 +#: ../../howto/logging-cookbook.rst:2698 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:2500 +#: ../../howto/logging-cookbook.rst:2705 msgid "Speaking logging messages" msgstr "" -#: ../../howto/logging-cookbook.rst:2502 +#: ../../howto/logging-cookbook.rst:2707 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 " @@ -1347,24 +1417,24 @@ msgid "" "approach, which assumes that the ``espeak`` TTS package is available::" msgstr "" -#: ../../howto/logging-cookbook.rst:2544 +#: ../../howto/logging-cookbook.rst:2749 msgid "" "When run, this script should say \"Hello\" and then \"Goodbye\" in a female " "voice." msgstr "" -#: ../../howto/logging-cookbook.rst:2546 +#: ../../howto/logging-cookbook.rst:2751 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:2554 +#: ../../howto/logging-cookbook.rst:2759 msgid "Buffering logging messages and outputting them conditionally" msgstr "" -#: ../../howto/logging-cookbook.rst:2556 +#: ../../howto/logging-cookbook.rst:2761 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 " @@ -1374,7 +1444,7 @@ msgid "" "debug information to be output as well as the error." msgstr "" -#: ../../howto/logging-cookbook.rst:2563 +#: ../../howto/logging-cookbook.rst:2768 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 " @@ -1387,7 +1457,7 @@ msgid "" "subclass of ``MemoryHandler`` if you want custom flushing behavior." msgstr "" -#: ../../howto/logging-cookbook.rst:2573 +#: ../../howto/logging-cookbook.rst:2778 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 " @@ -1396,7 +1466,7 @@ msgid "" "levels - otherwise, it only logs at DEBUG, INFO and WARNING levels." msgstr "" -#: ../../howto/logging-cookbook.rst:2579 +#: ../../howto/logging-cookbook.rst:2784 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 " @@ -1408,30 +1478,30 @@ msgid "" "respectively." msgstr "" -#: ../../howto/logging-cookbook.rst:2587 +#: ../../howto/logging-cookbook.rst:2792 msgid "Here's the script::" msgstr "" -#: ../../howto/logging-cookbook.rst:2650 +#: ../../howto/logging-cookbook.rst:2855 msgid "When this script is run, the following output should be observed:" msgstr "" -#: ../../howto/logging-cookbook.rst:2680 +#: ../../howto/logging-cookbook.rst:2885 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:2684 +#: ../../howto/logging-cookbook.rst:2889 msgid "You can of course use the conventional means of decoration::" msgstr "" -#: ../../howto/logging-cookbook.rst:2694 +#: ../../howto/logging-cookbook.rst:2899 msgid "Sending logging messages to email, with buffering" msgstr "" -#: ../../howto/logging-cookbook.rst:2696 +#: ../../howto/logging-cookbook.rst:2901 msgid "" "To illustrate how you can send log messages via email, so that a set number " "of messages are sent per email, you can subclass :class:`~logging.handlers." @@ -1442,7 +1512,7 @@ msgid "" "argument to see the required and optional arguments.)" msgstr "" -#: ../../howto/logging-cookbook.rst:2768 +#: ../../howto/logging-cookbook.rst:2973 msgid "" "If you run this script and your SMTP server is correctly set up, you should " "find that it sends eleven emails to the addressee you specify. The first ten " @@ -1450,17 +1520,17 @@ msgid "" "messages. That makes up 102 messages as specified in the script." msgstr "" -#: ../../howto/logging-cookbook.rst:2776 +#: ../../howto/logging-cookbook.rst:2981 msgid "Formatting times using UTC (GMT) via configuration" msgstr "" -#: ../../howto/logging-cookbook.rst:2778 +#: ../../howto/logging-cookbook.rst:2983 msgid "" "Sometimes you want to format times using UTC, which can be done using a " -"class such as `UTCFormatter`, shown below::" +"class such as ``UTCFormatter``, shown below::" msgstr "" -#: ../../howto/logging-cookbook.rst:2787 +#: ../../howto/logging-cookbook.rst:2992 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 " @@ -1468,21 +1538,21 @@ msgid "" "the following complete example::" msgstr "" -#: ../../howto/logging-cookbook.rst:2830 +#: ../../howto/logging-cookbook.rst:3035 msgid "When this script is run, it should print something like:" msgstr "" -#: ../../howto/logging-cookbook.rst:2837 +#: ../../howto/logging-cookbook.rst:3042 msgid "" "showing how the time is formatted both as local time and UTC, one for each " "handler." msgstr "" -#: ../../howto/logging-cookbook.rst:2844 +#: ../../howto/logging-cookbook.rst:3049 msgid "Using a context manager for selective logging" msgstr "" -#: ../../howto/logging-cookbook.rst:2846 +#: ../../howto/logging-cookbook.rst:3051 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 " @@ -1492,7 +1562,7 @@ msgid "" "scope of the context manager::" msgstr "" -#: ../../howto/logging-cookbook.rst:2879 +#: ../../howto/logging-cookbook.rst:3084 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 " @@ -1501,13 +1571,13 @@ msgid "" "block exit - you could do this if you don't need the handler any more." msgstr "" -#: ../../howto/logging-cookbook.rst:2885 +#: ../../howto/logging-cookbook.rst:3090 msgid "" "To illustrate how it works, we can add the following block of code to the " "above::" msgstr "" -#: ../../howto/logging-cookbook.rst:2903 +#: ../../howto/logging-cookbook.rst:3108 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 " @@ -1520,56 +1590,56 @@ msgid "" "(like message #1) whereas message #7 doesn't (just like message #2)." msgstr "" -#: ../../howto/logging-cookbook.rst:2913 +#: ../../howto/logging-cookbook.rst:3118 msgid "If we run the resulting script, the result is as follows:" msgstr "" -#: ../../howto/logging-cookbook.rst:2924 +#: ../../howto/logging-cookbook.rst:3129 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:2932 +#: ../../howto/logging-cookbook.rst:3137 msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:" msgstr "" -#: ../../howto/logging-cookbook.rst:2942 +#: ../../howto/logging-cookbook.rst:3147 msgid "" "In this case, the message #5 printed to ``stdout`` doesn't appear, as " "expected." msgstr "" -#: ../../howto/logging-cookbook.rst:2944 +#: ../../howto/logging-cookbook.rst:3149 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:2952 +#: ../../howto/logging-cookbook.rst:3157 msgid "A CLI application starter template" msgstr "" -#: ../../howto/logging-cookbook.rst:2954 +#: ../../howto/logging-cookbook.rst:3159 msgid "Here's an example which shows how you can:" msgstr "" -#: ../../howto/logging-cookbook.rst:2956 +#: ../../howto/logging-cookbook.rst:3161 msgid "Use a logging level based on command-line arguments" msgstr "" -#: ../../howto/logging-cookbook.rst:2957 +#: ../../howto/logging-cookbook.rst:3162 msgid "" "Dispatch to multiple subcommands in separate files, all logging at the same " "level in a consistent way" msgstr "" -#: ../../howto/logging-cookbook.rst:2959 +#: ../../howto/logging-cookbook.rst:3164 msgid "Make use of simple, minimal configuration" msgstr "" -#: ../../howto/logging-cookbook.rst:2961 +#: ../../howto/logging-cookbook.rst:3166 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 " @@ -1580,53 +1650,53 @@ msgid "" "``logging.INFO``. Here's one way that ``app.py`` could be written::" msgstr "" -#: ../../howto/logging-cookbook.rst:3010 +#: ../../howto/logging-cookbook.rst:3215 msgid "" "And the ``start``, ``stop`` and ``restart`` commands can be implemented in " "separate modules, like so for starting::" msgstr "" -#: ../../howto/logging-cookbook.rst:3023 +#: ../../howto/logging-cookbook.rst:3228 msgid "and thus for stopping::" msgstr "" -#: ../../howto/logging-cookbook.rst:3044 +#: ../../howto/logging-cookbook.rst:3249 msgid "and similarly for restarting::" msgstr "" -#: ../../howto/logging-cookbook.rst:3065 +#: ../../howto/logging-cookbook.rst:3270 msgid "" "If we run this application with the default log level, we get output like " "this:" msgstr "" -#: ../../howto/logging-cookbook.rst:3078 +#: ../../howto/logging-cookbook.rst:3283 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:3081 +#: ../../howto/logging-cookbook.rst:3286 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:3098 +#: ../../howto/logging-cookbook.rst:3303 msgid "And if we want less:" msgstr "" -#: ../../howto/logging-cookbook.rst:3106 +#: ../../howto/logging-cookbook.rst:3311 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:3112 +#: ../../howto/logging-cookbook.rst:3317 msgid "A Qt GUI for logging" msgstr "" -#: ../../howto/logging-cookbook.rst:3114 +#: ../../howto/logging-cookbook.rst:3319 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-" @@ -1634,7 +1704,7 @@ msgid "" "project/PySide2/>`_ or `PyQt5 `_ libraries." msgstr "" -#: ../../howto/logging-cookbook.rst:3120 +#: ../../howto/logging-cookbook.rst:3325 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 " @@ -1644,14 +1714,14 @@ msgid "" "logging messages at random levels with random short delays in between)." msgstr "" -#: ../../howto/logging-cookbook.rst:3127 +#: ../../howto/logging-cookbook.rst:3332 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:3131 +#: ../../howto/logging-cookbook.rst:3336 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 " @@ -1659,11 +1729,11 @@ msgid "" "information." msgstr "" -#: ../../howto/logging-cookbook.rst:3345 +#: ../../howto/logging-cookbook.rst:3550 msgid "Logging to syslog with RFC5424 support" msgstr "" -#: ../../howto/logging-cookbook.rst:3347 +#: ../../howto/logging-cookbook.rst:3552 msgid "" "Although :rfc:`5424` dates from 2009, most syslog servers are configured by " "detault to use the older :rfc:`3164`, which hails from 2001. When " @@ -1673,14 +1743,14 @@ msgid "" "handlers.SysLogHandler` functionality has not been updated." msgstr "" -#: ../../howto/logging-cookbook.rst:3354 +#: ../../howto/logging-cookbook.rst:3559 msgid "" "RFC 5424 contains some useful features such as support for structured data, " "and if you need to be able to log to a syslog server with support for it, " "you can do so with a subclassed handler which looks something like this::" msgstr "" -#: ../../howto/logging-cookbook.rst:3420 +#: ../../howto/logging-cookbook.rst:3625 msgid "" "You'll need to be familiar with RFC 5424 to fully understand the above code, " "and it may be that you have slightly different needs (e.g. for how you pass " @@ -1689,11 +1759,48 @@ msgid "" "using something like this::" msgstr "" -#: ../../howto/logging-cookbook.rst:3437 +#: ../../howto/logging-cookbook.rst:3639 +msgid "How to treat a logger like an output stream" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3641 +msgid "" +"Sometimes, you need to interface to a third-party API which expects a file-" +"like object to write to, but you want to direct the API's output to a " +"logger. You can do this using a class which wraps a logger with a file-like " +"API. Here's a short script illustrating such a class:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3681 +msgid "When this script is run, it prints" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3688 +msgid "" +"You could also use ``LoggerWriter`` to redirect ``sys.stdout`` and ``sys." +"stderr`` by doing something like this:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3698 +msgid "" +"You should do this *after* configuring logging for your needs. In the above " +"example, the :func:`~logging.basicConfig` call does this (using the ``sys." +"stderr`` value *before* it is overwritten by a ``LoggerWriter`` instance). " +"Then, you'd get this kind of result:" +msgstr "" + +#: ../../howto/logging-cookbook.rst:3711 +msgid "" +"Of course, these above examples show output according to the format used by :" +"func:`~logging.basicConfig`, but you can use a different formatter when you " +"configure logging." +msgstr "" + +#: ../../howto/logging-cookbook.rst:3718 msgid "Patterns to avoid" msgstr "" -#: ../../howto/logging-cookbook.rst:3439 +#: ../../howto/logging-cookbook.rst:3720 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 " @@ -1701,11 +1808,11 @@ msgid "" "The following sections are in no particular order." msgstr "" -#: ../../howto/logging-cookbook.rst:3446 +#: ../../howto/logging-cookbook.rst:3727 msgid "Opening the same log file multiple times" msgstr "" -#: ../../howto/logging-cookbook.rst:3448 +#: ../../howto/logging-cookbook.rst:3729 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. " @@ -1713,32 +1820,32 @@ msgid "" "file multiple times. This could be done accidentally, for example by:" msgstr "" -#: ../../howto/logging-cookbook.rst:3453 +#: ../../howto/logging-cookbook.rst:3734 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:3456 +#: ../../howto/logging-cookbook.rst:3737 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:3459 +#: ../../howto/logging-cookbook.rst:3740 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:3463 +#: ../../howto/logging-cookbook.rst:3744 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:3466 +#: ../../howto/logging-cookbook.rst:3747 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 " @@ -1747,7 +1854,7 @@ msgid "" "different handler instances which happen to point to the same file." msgstr "" -#: ../../howto/logging-cookbook.rst:3472 +#: ../../howto/logging-cookbook.rst:3753 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 " @@ -1757,17 +1864,17 @@ msgid "" "being supposedly in place." msgstr "" -#: ../../howto/logging-cookbook.rst:3479 +#: ../../howto/logging-cookbook.rst:3760 msgid "" "Use the techniques outlined in :ref:`multiple-processes` to circumvent such " "issues." msgstr "" -#: ../../howto/logging-cookbook.rst:3483 +#: ../../howto/logging-cookbook.rst:3764 msgid "Using loggers as attributes in a class or passing them as parameters" msgstr "" -#: ../../howto/logging-cookbook.rst:3485 +#: ../../howto/logging-cookbook.rst:3766 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 " @@ -1778,12 +1885,12 @@ msgid "" "module (and not the class) is the unit of software decomposition." msgstr "" -#: ../../howto/logging-cookbook.rst:3495 +#: ../../howto/logging-cookbook.rst:3776 msgid "" "Adding handlers other than :class:`NullHandler` to a logger in a library" msgstr "" -#: ../../howto/logging-cookbook.rst:3497 +#: ../../howto/logging-cookbook.rst:3778 msgid "" "Configuring logging by adding handlers, formatters and filters is the " "responsibility of the application developer, not the library developer. If " @@ -1791,11 +1898,11 @@ msgid "" "your loggers other than a :class:`~logging.NullHandler` instance." msgstr "" -#: ../../howto/logging-cookbook.rst:3504 +#: ../../howto/logging-cookbook.rst:3785 msgid "Creating a lot of loggers" msgstr "" -#: ../../howto/logging-cookbook.rst:3506 +#: ../../howto/logging-cookbook.rst:3787 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. " @@ -1806,14 +1913,14 @@ msgid "" "occasionally slightly more fine-grained than that)." msgstr "" -#: ../../howto/logging-cookbook.rst:3517 +#: ../../howto/logging-cookbook.rst:3798 msgid "Other resources" msgstr "" -#: ../../howto/logging-cookbook.rst:3530 +#: ../../howto/logging-cookbook.rst:3811 msgid ":ref:`Basic Tutorial `" msgstr "" -#: ../../howto/logging-cookbook.rst:3532 +#: ../../howto/logging-cookbook.rst:3813 msgid ":ref:`Advanced Tutorial `" msgstr ""