From d3f32e7ec405086d4f2b32843efe49f3e37a2177 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 16 Oct 2022 00:26:18 +0000 Subject: [PATCH] sync with cpython 7b604d83 --- howto/logging-cookbook.po | 583 ++++++++++++++++++++++---------------- 1 file changed, 345 insertions(+), 238 deletions(-) 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 "" pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy