Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liblogging.tex @ 28646:193b8aec00ce legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.
author Guido van Rossum <guido@python.org>
date Thu, 17 Apr 2003 14:55:42 +0000
parents ac683ac6759a
children a464020f15d6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1 \section{\module{logging} ---
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
2 Logging facility for Python}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
3
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
4 \declaremodule{standard}{logging} % standard library, in Python
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
5
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
6 % These apply to all modules, and may be given more than once:
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
7
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
8 \moduleauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
9 \sectionauthor{Vinay Sajip}{vinay_sajip@red-dove.com}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
10
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
11 \modulesynopsis{Logging module for Python based on \pep{282}.}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
12
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
13 \indexii{Errors}{logging}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
14
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
15 \versionadded{2.3}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
16 This module defines functions and classes which implement a flexible
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
17 error logging system for applications.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
18
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
19 Logging is performed by calling methods on instances of the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
20 \class{Logger} class (hereafter called \dfn{loggers}). Each instance has a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
21 name, and they are conceptually arranged in a name space hierarchy
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
22 using dots (periods) as separators. For example, a logger named
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
23 "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
24 Logger names can be anything you want, and indicate the area of an
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
25 application in which a logged message originates.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
26
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
27 Logged messages also have levels of importance associated with them.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
28 The default levels provided are \constant{DEBUG}, \constant{INFO},
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
29 \constant{WARNING}, \constant{ERROR} and \constant{CRITICAL}. As a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
30 convenience, you indicate the importance of a logged message by calling
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
31 an appropriate method of \class{Logger}. The methods are
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
32 \method{debug()}, \method{info()}, \method{warning()}, \method{error()} and
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
33 \method{critical()}, which mirror the default levels. You are not
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
34 constrained to use these levels: you can specify your own and use a
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
35 more general \class{Logger} method, \method{log()}, which takes an
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
36 explicit level argument.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
37
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
38 Levels can also be associated with loggers, being set either by the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
39 developer or through loading a saved logging configuration. When a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
40 logging method is called on a logger, the logger compares its own
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
41 level with the level associated with the method call. If the logger's
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
42 level is higher than the method call's, no logging message is actually
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
43 generated. This is the basic mechanism controlling the verbosity of
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
44 logging output.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
45
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
46 Logging messages are encoded as instances of the \class{LogRecord} class.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
47 When a logger decides to actually log an event, an \class{LogRecord}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
48 instance is created from the logging message.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
49
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
50 Logging messages are subjected to a dispatch mechanism through the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
51 use of \dfn{handlers}, which are instances of subclasses of the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
52 \class{Handler} class. Handlers are responsible for ensuring that a logged
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
53 message (in the form of a \class{LogRecord}) ends up in a particular
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
54 location (or set of locations) which is useful for the target audience for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
55 that message (e.g. end users, support desk staff, system administrators,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
56 developers). Handlers are passed \class{LogRecord} instances intended for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
57 particular destinations. Each logger can have zero, one or more handlers
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
58 associated with it (via the \method{addHandler} method of \class{Logger}).
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
59 In addition to any handlers directly associated with a logger,
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
60 \emph{all handlers associated with all ancestors of the logger} are
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
61 called to dispatch the message.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
62
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
63 Just as for loggers, handlers can have levels associated with them.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
64 A handler's level acts as a filter in the same way as a logger's level does.
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
65 If a handler decides to actually dispatch an event, the \method{emit()} method
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
66 is used to send the message to its destination. Most user-defined subclasses
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
67 of \class{Handler} will need to override this \method{emit()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
68
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
69 In addition to the base \class{Handler} class, many useful subclasses
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
70 are provided:
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
71
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
72 \begin{enumerate}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
73
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
74 \item \class{StreamHandler} instances send error messages to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
75 streams (file-like objects).
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
76
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
77 \item \class{FileHandler} instances send error messages to disk
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
78 files.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
79
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
80 \item \class{RotatingFileHandler} instances send error messages to disk
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
81 files, with support for maximum log file sizes and log file rotation.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
82
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
83 \item \class{SocketHandler} instances send error messages to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
84 TCP/IP sockets.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
85
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
86 \item \class{DatagramHandler} instances send error messages to UDP
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
87 sockets.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
88
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
89 \item \class{SMTPHandler} instances send error messages to a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
90 designated email address.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
91
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
92 \item \class{SysLogHandler} instances send error messages to a
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
93 \UNIX{} syslog daemon, possibly on a remote machine.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
94
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
95 \item \class{NTEventLogHandler} instances send error messages to a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
96 Windows NT/2000/XP event log.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
97
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
98 \item \class{MemoryHandler} instances send error messages to a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
99 buffer in memory, which is flushed whenever specific criteria are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
100 met.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
101
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
102 \item \class{HTTPHandler} instances send error messages to an
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
103 HTTP server using either \samp{GET} or \samp{POST} semantics.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
104
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
105 \end{enumerate}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
106
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
107 The \class{StreamHandler} and \class{FileHandler} classes are defined
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
108 in the core logging package. The other handlers are defined in a sub-
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
109 module, \module{logging.handlers}. (There is also another sub-module,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
110 \module{logging.config}, for configuration functionality.)
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
111
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
112 Logged messages are formatted for presentation through instances of the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
113 \class{Formatter} class. They are initialized with a format string
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
114 suitable for use with the \% operator and a dictionary.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
115
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
116 For formatting multiple messages in a batch, instances of
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
117 \class{BufferingFormatter} can be used. In addition to the format string
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
118 (which is applied to each message in the batch), there is provision for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
119 header and trailer format strings.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
120
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
121 When filtering based on logger level and/or handler level is not enough,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
122 instances of \class{Filter} can be added to both \class{Logger} and
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
123 \class{Handler} instances (through their \method{addFilter()} method).
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
124 Before deciding to process a message further, both loggers and handlers
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
125 consult all their filters for permission. If any filter returns a false
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
126 value, the message is not processed further.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
127
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
128 The basic \class{Filter} functionality allows filtering by specific logger
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
129 name. If this feature is used, messages sent to the named logger and its
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
130 children are allowed through the filter, and all others dropped.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
131
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
132 In addition to the classes described above, there are a number of module-
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
133 level functions.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
134
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
135 \begin{funcdesc}{getLogger}{\optional{name}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
136 Return a logger with the specified name or, if no name is specified, return
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
137 a logger which is the root logger of the hierarchy.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
138
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
139 All calls to this function with a given name return the same logger instance.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
140 This means that logger instances never need to be passed between different
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
141 parts of an application.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
142 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
143
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
144 \begin{funcdesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
145 Logs a message with level \constant{DEBUG} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
146 The \var{msg} is the message format string, and the \var{args} are the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
147 arguments which are merged into \var{msg}. The only keyword argument in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
148 \var{kwargs} which is inspected is \var{exc_info} which, if it does not
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
149 evaluate as false, causes exception information (via a call to
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
150 \function{sys.exc_info()}) to be added to the logging message.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
151 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
152
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
153 \begin{funcdesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
154 Logs a message with level \constant{INFO} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
155 The arguments are interpreted as for \function{debug()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
156 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
157
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
158 \begin{funcdesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
159 Logs a message with level \constant{WARNING} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
160 The arguments are interpreted as for \function{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
161 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
162
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
163 \begin{funcdesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
164 Logs a message with level \constant{ERROR} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
165 The arguments are interpreted as for \function{debug()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
166 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
167
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
168 \begin{funcdesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
169 Logs a message with level \constant{CRITICAL} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
170 The arguments are interpreted as for \function{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
171 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
172
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
173 \begin{funcdesc}{exception}{msg\optional{, *args}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
174 Logs a message with level \constant{ERROR} on the root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
175 The arguments are interpreted as for \function{debug()}. Exception info
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
176 is added to the logging message. This function should only be called
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
177 from an exception handler.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
178 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
179
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
180 \begin{funcdesc}{disable}{lvl}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
181 Provides an overriding level \var{lvl} for all loggers which takes
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
182 precedence over the logger's own level. When the need arises to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
183 temporarily throttle logging output down across the whole application,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
184 this function can be useful.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
185 \end{funcdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
186
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
187 \begin{funcdesc}{addLevelName}{lvl, levelName}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
188 Associates level \var{lvl} with text \var{levelName} in an internal
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
189 dictionary, which is used to map numeric levels to a textual
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
190 representation, for example when a \class{Formatter} formats a message.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
191 This function can also be used to define your own levels. The only
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
192 constraints are that all levels used must be registered using this
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
193 function, levels should be positive integers and they should increase
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
194 in increasing order of severity.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
195 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
196
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
197 \begin{funcdesc}{getLevelName}{lvl}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
198 Returns the textual representation of logging level \var{lvl}. If the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
199 level is one of the predefined levels \constant{CRITICAL},
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
200 \constant{ERROR}, \constant{WARNING}, \constant{INFO} or \constant{DEBUG}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
201 then you get the corresponding string. If you have associated levels
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
202 with names using \function{addLevelName()} then the name you have associated
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
203 with \var{lvl} is returned. Otherwise, the string "Level \%s" \% lvl is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
204 returned.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
205 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
206
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
207 \begin{funcdesc}{basicConfig}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
208 Does basic configuration for the logging system by creating a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
209 \class{StreamHandler} with a default \class{Formatter} and adding it to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
210 the root logger. The functions \function{debug()}, \function{info()},
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
211 \function{warning()}, \function{error()} and \function{critical()} will call
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
212 \function{basicConfig()} automatically if no handlers are defined for the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
213 root logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
214 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
215
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
216 \begin{funcdesc}{shutdown}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
217 Informs the logging system to perform an orderly shutdown by flushing and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
218 closing all handlers.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
219 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
220
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
221 \begin{funcdesc}{setLoggerClass}{klass}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
222 Tells the logging system to use the class \var{klass} when instantiating a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
223 logger. The class should define \method{__init__()} such that only a name
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
224 argument is required, and the \method{__init__()} should call
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
225 \method{Logger.__init__()}. This function is typically called before any
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
226 loggers are instantiated by applications which need to use custom logger
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
227 behavior.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
228 \end{funcdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
229
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
230
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
231 \begin{seealso}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
232 \seepep{282}{A Logging System}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
233 {The proposal which described this feature for inclusion in
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
234 the Python standard library.}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
235 \end{seealso}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
236
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
237
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
238 \subsection{Logger Objects}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
239
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
240 Loggers have the following attributes and methods. Note that Loggers are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
241 never instantiated directly, but always through the module-level function
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
242 \function{logging.getLogger(name)}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
243
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
244 \begin{datadesc}{propagate}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
245 If this evaluates to false, logging messages are not passed by this
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
246 logger or by child loggers to higher level (ancestor) loggers. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
247 constructor sets this attribute to 1.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
248 \end{datadesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
249
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
250 \begin{methoddesc}{setLevel}{lvl}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
251 Sets the threshold for this logger to \var{lvl}. Logging messages
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
252 which are less severe than \var{lvl} will be ignored. When a logger is
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
253 created, the level is set to \constant{NOTSET} (which causes all messages
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
254 to be processed in the root logger, or delegation to the parent in non-root
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
255 loggers).
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
256 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
257
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
258 \begin{methoddesc}{isEnabledFor}{lvl}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
259 Indicates if a message of severity \var{lvl} would be processed by
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
260 this logger. This method checks first the module-level level set by
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
261 \function{logging.disable(lvl)} and then the logger's effective level as
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
262 determined by \method{getEffectiveLevel()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
263 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
264
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
265 \begin{methoddesc}{getEffectiveLevel}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
266 Indicates the effective level for this logger. If a value other than
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
267 \constant{NOTSET} has been set using \method{setLevel()}, it is returned.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
268 Otherwise, the hierarchy is traversed towards the root until a value
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
269 other than \constant{NOTSET} is found,and that value is returned.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
270 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
271
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
272 \begin{methoddesc}{debug}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
273 Logs a message with level \constant{DEBUG} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
274 The \var{msg} is the message format string, and the \var{args} are the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
275 arguments which are merged into \var{msg}. The only keyword argument in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
276 \var{kwargs} which is inspected is \var{exc_info} which, if it does not
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
277 evaluate as false, causes exception information (via a call to
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
278 \function{sys.exc_info()}) to be added to the logging message.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
279 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
280
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
281 \begin{methoddesc}{info}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
282 Logs a message with level \constant{INFO} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
283 The arguments are interpreted as for \method{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
284 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
285
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
286 \begin{methoddesc}{warning}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
287 Logs a message with level \constant{WARNING} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
288 The arguments are interpreted as for \method{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
289 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
290
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
291 \begin{methoddesc}{error}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
292 Logs a message with level \constant{ERROR} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
293 The arguments are interpreted as for \method{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
294 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
295
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
296 \begin{methoddesc}{critical}{msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
297 Logs a message with level \constant{CRITICAL} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
298 The arguments are interpreted as for \method{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
299 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
300
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
301 \begin{methoddesc}{log}{lvl, msg\optional{, *args\optional{, **kwargs}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
302 Logs a message with level \var{lvl} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
303 The other arguments are interpreted as for \method{debug()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
304 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
305
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
306 \begin{methoddesc}{exception}{msg\optional{, *args}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
307 Logs a message with level \constant{ERROR} on this logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
308 The arguments are interpreted as for \method{debug()}. Exception info
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
309 is added to the logging message. This method should only be called
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
310 from an exception handler.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
311 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
312
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
313 \begin{methoddesc}{addFilter}{filt}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
314 Adds the specified filter \var{filt} to this logger.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
315 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
316
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
317 \begin{methoddesc}{removeFilter}{filt}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
318 Removes the specified filter \var{filt} from this logger.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
319 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
320
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
321 \begin{methoddesc}{filter}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
322 Applies this logger's filters to the record and returns a true value if
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
323 the record is to be processed.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
324 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
325
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
326 \begin{methoddesc}{addHandler}{hdlr}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
327 Adds the specified handler \var{hdlr} to this logger.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
328 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
329
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
330 \begin{methoddesc}{removeHandler}{hdlr}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
331 Removes the specified handler \var{hdlr} from this logger.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
332 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
333
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
334 \begin{methoddesc}{findCaller}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
335 Finds the caller's source filename and line number. Returns the filename
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
336 and line number as a 2-element tuple.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
337 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
338
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
339 \begin{methoddesc}{handle}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
340 Handles a record by passing it to all handlers associated with this logger
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
341 and its ancestors (until a false value of \var{propagate} is found).
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
342 This method is used for unpickled records received from a socket, as well
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
343 as those created locally. Logger-level filtering is applied using
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
344 \method{filter()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
345 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
346
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
347 \begin{methoddesc}{makeRecord}{name, lvl, fn, lno, msg, args, exc_info}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
348 This is a factory method which can be overridden in subclasses to create
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
349 specialized \class{LogRecord} instances.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
350 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
351
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
352 \subsection{Handler Objects}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
353
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
354 Handlers have the following attributes and methods. Note that
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
355 \class{Handler} is never instantiated directly; this class acts as a
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
356 base for more useful subclasses. However, the \method{__init__()}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
357 method in subclasses needs to call \method{Handler.__init__()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
358
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
359 \begin{methoddesc}{__init__}{level=\constant{NOTSET}}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
360 Initializes the \class{Handler} instance by setting its level, setting
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
361 the list of filters to the empty list and creating a lock (using
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
362 \method{getLock()}) for serializing access to an I/O mechanism.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
363 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
364
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
365 \begin{methoddesc}{createLock}{}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
366 Initializes a thread lock which can be used to serialize access to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
367 underlying I/O functionality which may not be threadsafe.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
368 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
369
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
370 \begin{methoddesc}{acquire}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
371 Acquires the thread lock created with \method{createLock()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
372 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
373
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
374 \begin{methoddesc}{release}{}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
375 Releases the thread lock acquired with \method{acquire()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
376 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
377
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
378 \begin{methoddesc}{setLevel}{lvl}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
379 Sets the threshold for this handler to \var{lvl}. Logging messages which are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
380 less severe than \var{lvl} will be ignored. When a handler is created, the
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
381 level is set to \constant{NOTSET} (which causes all messages to be processed).
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
382 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
383
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
384 \begin{methoddesc}{setFormatter}{form}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
385 Sets the \class{Formatter} for this handler to \var{form}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
386 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
387
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
388 \begin{methoddesc}{addFilter}{filt}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
389 Adds the specified filter \var{filt} to this handler.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
390 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
391
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
392 \begin{methoddesc}{removeFilter}{filt}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
393 Removes the specified filter \var{filt} from this handler.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
394 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
395
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
396 \begin{methoddesc}{filter}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
397 Applies this handler's filters to the record and returns a true value if
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
398 the record is to be processed.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
399 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
400
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
401 \begin{methoddesc}{flush}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
402 Ensure all logging output has been flushed. This version does
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
403 nothing and is intended to be implemented by subclasses.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
404 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
405
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
406 \begin{methoddesc}{close}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
407 Tidy up any resources used by the handler. This version does
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
408 nothing and is intended to be implemented by subclasses.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
409 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
410
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
411 \begin{methoddesc}{handle}{record}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
412 Conditionally emits the specified logging record, depending on
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
413 filters which may have been added to the handler. Wraps the actual
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
414 emission of the record with acquisition/release of the I/O thread
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
415 lock.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
416 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
417
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
418 \begin{methoddesc}{handleError}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
419 This method should be called from handlers when an exception is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
420 encountered during an emit() call. By default it does nothing,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
421 which means that exceptions get silently ignored. This is what is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
422 mostly wanted for a logging system - most users will not care
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
423 about errors in the logging system, they are more interested in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
424 application errors. You could, however, replace this with a custom
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
425 handler if you wish.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
426 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
427
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
428 \begin{methoddesc}{format}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
429 Do formatting for a record - if a formatter is set, use it.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
430 Otherwise, use the default formatter for the module.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
431 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
432
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
433 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
434 Do whatever it takes to actually log the specified logging record.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
435 This version is intended to be implemented by subclasses and so
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
436 raises a \exception{NotImplementedError}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
437 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
438
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
439 \subsubsection{StreamHandler}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
440
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
441 The \class{StreamHandler} class sends logging output to streams such as
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
442 \var{sys.stdout}, \var{sys.stderr} or any file-like object (or, more
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
443 precisely, any object which supports \method{write()} and \method{flush()}
27381
8d869f921f22 Fix minor typos.
Raymond Hettinger <python@rcn.com>
parents: 27378
diff changeset
444 methods).
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
445
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
446 \begin{classdesc}{StreamHandler}{\optional{strm}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
447 Returns a new instance of the \class{StreamHandler} class. If \var{strm} is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
448 specified, the instance will use it for logging output; otherwise,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
449 \var{sys.stderr} will be used.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
450 \end{classdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
451
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
452 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
453 If a formatter is specified, it is used to format the record.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
454 The record is then written to the stream with a trailing newline.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
455 If exception information is present, it is formatted using
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
456 \function{traceback.print_exception()} and appended to the stream.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
457 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
458
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
459 \begin{methoddesc}{flush}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
460 Flushes the stream by calling its \method{flush()} method. Note that
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
461 the \method{close()} method is inherited from \class{Handler} and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
462 so does nothing, so an explicit \method{flush()} call may be needed
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
463 at times.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
464 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
465
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
466 \subsubsection{FileHandler}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
467
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
468 The \class{FileHandler} class sends logging output to a disk file.
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
469 It inherits the output functionality from \class{StreamHandler}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
470
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
471 \begin{classdesc}{FileHandler}{filename\optional{, mode}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
472 Returns a new instance of the \class{FileHandler} class. The specified
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
473 file is opened and used as the stream for logging. If \var{mode} is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
474 not specified, \constant{"a"} is used. By default, the file grows
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
475 indefinitely.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
476 \end{classdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
477
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
478 \begin{methoddesc}{close}{}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
479 Closes the file.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
480 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
481
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
482 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
483 Outputs the record to the file.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
484 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
485
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
486 \subsubsection{RotatingFileHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
487
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
488 The \class{RotatingFileHandler} class supports rotation of disk log files.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
489
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
490 \begin{classdesc}{RotatingFileHandler}{filename\optional{, mode, maxBytes,
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
491 backupCount}}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
492 Returns a new instance of the \class{RotatingFileHandler} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
493 specified file is opened and used as the stream for logging. If
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
494 \var{mode} is not specified, \code{'a'} is used. By default, the
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
495 file grows indefinitely. You can use the \var{maxBytes} and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
496 \var{backupCount} values to allow the file to \dfn{rollover} at a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
497 predetermined size. When the size is about to be exceeded, the file is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
498 closed and a new file opened for output, transparently to the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
499 caller. Rollover occurs whenever the current log file is nearly
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
500 \var{maxBytes} in length. If \var{backupCount} is >= 1, the system
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
501 will successively create new files with the same pathname as the base
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
502 file, but with extensions ".1", ".2" etc. appended to it. For example,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
503 with a backupCount of 5 and a base file name of "app.log", you would
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
504 get "app.log", "app.log.1", "app.log.2", ... through to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
505 "app.log.5". When the last file reaches its size limit, the logging
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
506 reverts to "app.log" which is truncated to zero length. If
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
507 \var{maxBytes} is zero, rollover never occurs.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
508 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
509
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
510 \begin{methoddesc}{doRollover}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
511 Does a rollover, as described above.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
512 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
513
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
514 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
515 Outputs the record to the file, catering for rollover as described
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
516 in \method{setRollover()}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
517 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
518
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
519 \subsubsection{SocketHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
520
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
521 The \class{SocketHandler} class sends logging output to a network
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
522 socket. The base class uses a TCP socket.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
523
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
524 \begin{classdesc}{SocketHandler}{host, port}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
525 Returns a new instance of the \class{SocketHandler} class intended to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
526 communicate with a remote machine whose address is given by \var{host}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
527 and \var{port}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
528 \end{classdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
529
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
530 \begin{methoddesc}{close}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
531 Closes the socket.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
532 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
533
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
534 \begin{methoddesc}{handleError}{}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
535 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
536
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
537 \begin{methoddesc}{emit}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
538 Pickles the record and writes it to the socket in binary format.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
539 If there is an error with the socket, silently drops the packet.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
540 If the connection was previously lost, re-establishes the connection.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
541 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
542
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
543 \begin{methoddesc}{handleError}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
544 Handles an error which has occurred during \method{emit()}. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
545 most likely cause is a lost connection. Closes the socket so that
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
546 we can retry on the next event.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
547 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
548
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
549 \begin{methoddesc}{makeSocket}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
550 This is a factory method which allows subclasses to define the precise
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
551 type of socket they want. The default implementation creates a TCP
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
552 socket (\constant{socket.SOCK_STREAM}).
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
553 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
554
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
555 \begin{methoddesc}{makePickle}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
556 Pickles the record in binary format with a length prefix, and returns
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
557 it ready for transmission across the socket.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
558 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
559
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
560 \begin{methoddesc}{send}{packet}
27381
8d869f921f22 Fix minor typos.
Raymond Hettinger <python@rcn.com>
parents: 27378
diff changeset
561 Send a pickled string \var{packet} to the socket. This function allows
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
562 for partial sends which can happen when the network is busy.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
563 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
564
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
565 \subsubsection{DatagramHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
566
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
567 The \class{DatagramHandler} class inherits from \class{SocketHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
568 to support sending logging messages over UDP sockets.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
569
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
570 \begin{classdesc}{DatagramHandler}{host, port}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
571 Returns a new instance of the \class{DatagramHandler} class intended to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
572 communicate with a remote machine whose address is given by \var{host}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
573 and \var{port}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
574 \end{classdesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
575
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
576 \begin{methoddesc}{emit}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
577 Pickles the record and writes it to the socket in binary format.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
578 If there is an error with the socket, silently drops the packet.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
579 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
580
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
581 \begin{methoddesc}{makeSocket}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
582 The factory method of \class{SocketHandler} is here overridden to create
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
583 a UDP socket (\constant{socket.SOCK_DGRAM}).
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
584 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
585
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
586 \begin{methoddesc}{send}{s}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
587 Send a pickled string to a socket. This function allows for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
588 partial sends which can happen when the network is busy.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
589 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
590
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
591 \subsubsection{SysLogHandler}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
592
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
593 The \class{SysLogHandler} class supports sending logging messages to a
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
594 remote or local \UNIX{} syslog.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
595
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
596 \begin{classdesc}{SysLogHandler}{\optional{address\optional{, facility}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
597 Returns a new instance of the \class{SysLogHandler} class intended to
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
598 communicate with a remote \UNIX{} machine whose address is given by
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
599 \var{address} in the form of a \code{(\var{host}, \var{port})}
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
600 tuple. If \var{address} is not specified, \code{('localhost', 514)} is
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
601 used. The address is used to open a UDP socket. If \var{facility} is
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
602 not specified, \constant{LOG_USER} is used.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
603 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
604
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
605 \begin{methoddesc}{close}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
606 Closes the socket to the remote host.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
607 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
608
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
609 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
610 The record is formatted, and then sent to the syslog server. If
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
611 exception information is present, it is \emph{not} sent to the server.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
612 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
613
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
614 \begin{methoddesc}{encodePriority}{facility, priority}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
615 Encodes the facility and priority into an integer. You can pass in strings
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
616 or integers - if strings are passed, internal mapping dictionaries are used
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
617 to convert them to integers.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
618 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
619
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
620 \subsubsection{NTEventLogHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
621
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
622 The \class{NTEventLogHandler} class supports sending logging messages
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
623 to a local Windows NT, Windows 2000 or Windows XP event log. Before
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
624 you can use it, you need Mark Hammond's Win32 extensions for Python
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
625 installed.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
626
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
627 \begin{classdesc}{NTEventLogHandler}{appname
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
628 \optional{, dllname\optional{, logtype}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
629 Returns a new instance of the \class{NTEventLogHandler} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
630 \var{appname} is used to define the application name as it appears in the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
631 event log. An appropriate registry entry is created using this name.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
632 The \var{dllname} should give the fully qualified pathname of a .dll or .exe
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
633 which contains message definitions to hold in the log (if not specified,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
634 \constant{"win32service.pyd"} is used - this is installed with the Win32
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
635 extensions and contains some basic placeholder message definitions.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
636 Note that use of these placeholders will make your event logs big, as the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
637 entire message source is held in the log. If you want slimmer logs, you have
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
638 to pass in the name of your own .dll or .exe which contains the message
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
639 definitions you want to use in the event log). The \var{logtype} is one of
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
640 \constant{"Application"}, \constant{"System"} or \constant{"Security"}, and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
641 defaults to \constant{"Application"}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
642 \end{classdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
643
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
644 \begin{methoddesc}{close}{}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
645 At this point, you can remove the application name from the registry as a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
646 source of event log entries. However, if you do this, you will not be able
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
647 to see the events as you intended in the Event Log Viewer - it needs to be
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
648 able to access the registry to get the .dll name. The current version does
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
649 not do this (in fact it doesn't do anything).
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
650 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
651
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
652 \begin{methoddesc}{emit}{record}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
653 Determines the message ID, event category and event type, and then logs the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
654 message in the NT event log.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
655 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
656
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
657 \begin{methoddesc}{getEventCategory}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
658 Returns the event category for the record. Override this if you
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
659 want to specify your own categories. This version returns 0.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
660 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
661
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
662 \begin{methoddesc}{getEventType}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
663 Returns the event type for the record. Override this if you want
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
664 to specify your own types. This version does a mapping using the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
665 handler's typemap attribute, which is set up in \method{__init__()}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
666 to a dictionary which contains mappings for \constant{DEBUG},
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
667 \constant{INFO}, \constant{WARNING}, \constant{ERROR} and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
668 \constant{CRITICAL}. If you are using your own levels, you will either need
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
669 to override this method or place a suitable dictionary in the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
670 handler's \var{typemap} attribute.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
671 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
672
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
673 \begin{methoddesc}{getMessageID}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
674 Returns the message ID for the record. If you are using your
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
675 own messages, you could do this by having the \var{msg} passed to the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
676 logger being an ID rather than a format string. Then, in here,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
677 you could use a dictionary lookup to get the message ID. This
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
678 version returns 1, which is the base message ID in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
679 \constant{win32service.pyd}.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
680 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
681
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
682 \subsubsection{SMTPHandler}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
683
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
684 The \class{SMTPHandler} class supports sending logging messages to an email
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
685 address via SMTP.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
686
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
687 \begin{classdesc}{SMTPHandler}{mailhost, fromaddr, toaddrs, subject}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
688 Returns a new instance of the \class{SMTPHandler} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
689 instance is initialized with the from and to addresses and subject
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
690 line of the email. The \var{toaddrs} should be a list of strings without
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
691 domain names (That's what the \var{mailhost} is for). To specify a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
692 non-standard SMTP port, use the (host, port) tuple format for the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
693 \var{mailhost} argument. If you use a string, the standard SMTP port
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
694 is used.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
695 \end{classdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
696
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
697 \begin{methoddesc}{emit}{record}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
698 Formats the record and sends it to the specified addressees.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
699 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
700
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
701 \begin{methoddesc}{getSubject}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
702 If you want to specify a subject line which is record-dependent,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
703 override this method.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
704 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
705
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
706 \subsubsection{MemoryHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
707
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
708 The \class{MemoryHandler} supports buffering of logging records in memory,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
709 periodically flushing them to a \dfn{target} handler. Flushing occurs
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
710 whenever the buffer is full, or when an event of a certain severity or
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
711 greater is seen.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
712
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
713 \class{MemoryHandler} is a subclass of the more general
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
714 \class{BufferingHandler}, which is an abstract class. This buffers logging
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
715 records in memory. Whenever each record is added to the buffer, a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
716 check is made by calling \method{shouldFlush()} to see if the buffer
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
717 should be flushed. If it should, then \method{flush()} is expected to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
718 do the needful.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
719
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
720 \begin{classdesc}{BufferingHandler}{capacity}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
721 Initializes the handler with a buffer of the specified capacity.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
722 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
723
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
724 \begin{methoddesc}{emit}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
725 Appends the record to the buffer. If \method{shouldFlush()} returns true,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
726 calls \method{flush()} to process the buffer.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
727 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
728
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
729 \begin{methoddesc}{flush}{}
27381
8d869f921f22 Fix minor typos.
Raymond Hettinger <python@rcn.com>
parents: 27378
diff changeset
730 You can override this to implement custom flushing behavior. This version
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
731 just zaps the buffer to empty.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
732 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
733
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
734 \begin{methoddesc}{shouldFlush}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
735 Returns true if the buffer is up to capacity. This method can be
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
736 overridden to implement custom flushing strategies.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
737 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
738
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
739 \begin{classdesc}{MemoryHandler}{capacity\optional{, flushLevel
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
740 \optional{, target}}}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
741 Returns a new instance of the \class{MemoryHandler} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
742 instance is initialized with a buffer size of \var{capacity}. If
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
743 \var{flushLevel} is not specified, \constant{ERROR} is used. If no
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
744 \var{target} is specified, the target will need to be set using
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
745 \method{setTarget()} before this handler does anything useful.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
746 \end{classdesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
747
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
748 \begin{methoddesc}{close}{}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
749 Calls \method{flush()}, sets the target to \constant{None} and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
750 clears the buffer.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
751 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
752
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
753 \begin{methoddesc}{flush}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
754 For a \class{MemoryHandler}, flushing means just sending the buffered
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
755 records to the target, if there is one. Override if you want
27381
8d869f921f22 Fix minor typos.
Raymond Hettinger <python@rcn.com>
parents: 27378
diff changeset
756 different behavior.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
757 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
758
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
759 \begin{methoddesc}{setTarget}{target}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
760 Sets the target handler for this handler.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
761 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
762
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
763 \begin{methoddesc}{shouldFlush}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
764 Checks for buffer full or a record at the \var{flushLevel} or higher.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
765 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
766
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
767 \subsubsection{HTTPHandler}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
768
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
769 The \class{HTTPHandler} class supports sending logging messages to a
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
770 Web server, using either \samp{GET} or \samp{POST} semantics.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
771
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
772 \begin{classdesc}{HTTPHandler}{host, url\optional{, method}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
773 Returns a new instance of the \class{HTTPHandler} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
774 instance is initialized with a host address, url and HTTP method.
27495
adbc3fe8c81c Various minor markup adjustments.
Fred Drake <fdrake@acm.org>
parents: 27381
diff changeset
775 If no \var{method} is specified, \samp{GET} is used.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
776 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
777
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
778 \begin{methoddesc}{emit}{record}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
779 Sends the record to the Web server as an URL-encoded dictionary.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
780 \end{methoddesc}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
781
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
782 \subsection{Formatter Objects}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
783
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
784 \class{Formatter}s have the following attributes and methods. They are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
785 responsible for converting a \class{LogRecord} to (usually) a string
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
786 which can be interpreted by either a human or an external system. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
787 base
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
788 \class{Formatter} allows a formatting string to be specified. If none is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
789 supplied, the default value of "\%s(message)\\n" is used.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
790
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
791 A Formatter can be initialized with a format string which makes use of
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
792 knowledge of the \class{LogRecord} attributes - e.g. the default value
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
793 mentioned above makes use of the fact that the user's message and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
794 arguments are pre- formatted into a LogRecord's \var{message}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
795 attribute. Currently, the useful attributes in a LogRecord are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
796 described by:
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
797
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
798 \%(name)s Name of the logger (logging channel)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
799 \%(levelno)s Numeric logging level for the message (DEBUG, INFO,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
800 WARNING, ERROR, CRITICAL)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
801 \%(levelname)s Text logging level for the message ("DEBUG", "INFO",
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
802 "WARNING", "ERROR", "CRITICAL")
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
803 \%(pathname)s Full pathname of the source file where the logging
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
804 call was issued (if available)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
805 \%(filename)s Filename portion of pathname
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
806 \%(module)s Module (name portion of filename)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
807 \%(lineno)d Source line number where the logging call was issued
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
808 (if available)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
809 \%(created)f Time when the LogRecord was created (time.time()
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
810 return value)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
811 \%(asctime)s Textual time when the LogRecord was created
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
812 \%(msecs)d Millisecond portion of the creation time
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
813 \%(relativeCreated)d Time in milliseconds when the LogRecord was created,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
814 relative to the time the logging module was loaded
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
815 (typically at application startup time)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
816 \%(thread)d Thread ID (if available)
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
817 \%(process)d Process ID (if available)
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
818 \%(message)s The result of msg \% args, computed just as the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
819 record is emitted
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
820
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
821 \begin{classdesc}{Formatter}{\optional{fmt\optional{, datefmt}}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
822 Returns a new instance of the \class{Formatter} class. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
823 instance is initialized with a format string for the message as a whole,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
824 as well as a format string for the date/time portion of a message. If
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
825 no \var{fmt} is specified, "\%(message)s" is used. If no \var{datefmt}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
826 is specified, the ISO8601 date format is used.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
827 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
828
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
829 \begin{methoddesc}{format}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
830 The record's attribute dictionary is used as the operand to a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
831 string formatting operation. Returns the resulting string.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
832 Before formatting the dictionary, a couple of preparatory steps
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
833 are carried out. The \var{message} attribute of the record is computed
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
834 using \var{msg} \% \var{args}. If the formatting string contains
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
835 \constant{"(asctime)"}, \method{formatTime()} is called to format the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
836 event time. If there is exception information, it is formatted using
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
837 \method{formatException()} and appended to the message.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
838 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
839
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
840 \begin{methoddesc}{formatTime}{record\optional{, datefmt}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
841 This method should be called from \method{format()} by a formatter which
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
842 wants to make use of a formatted time. This method can be overridden
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
843 in formatters to provide for any specific requirement, but the
27381
8d869f921f22 Fix minor typos.
Raymond Hettinger <python@rcn.com>
parents: 27378
diff changeset
844 basic behavior is as follows: if \var{datefmt} (a string) is specified,
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
845 it is used with \function{time.strftime()} to format the creation time of the
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
846 record. Otherwise, the ISO8601 format is used. The resulting
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
847 string is returned.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
848 \end{methoddesc}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
849
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
850 \begin{methoddesc}{formatException}{exc_info}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
851 Formats the specified exception information (a standard exception tuple
27496
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
852 as returned by \function{sys.exc_info()}) as a string. This default
5e4355d80dd1 More markup changes for consistency.
Fred Drake <fdrake@acm.org>
parents: 27495
diff changeset
853 implementation just uses \function{traceback.print_exception()}.
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
854 The resulting string is returned.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
855 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
856
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
857 \subsection{Filter Objects}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
858
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
859 \class{Filter}s can be used by \class{Handler}s and \class{Logger}s for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
860 more sophisticated filtering than is provided by levels. The base filter
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
861 class only allows events which are below a certain point in the logger
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
862 hierarchy. For example, a filter initialized with "A.B" will allow events
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
863 logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
864 "B.A.B" etc. If initialized with the empty string, all events are passed.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
865
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
866 \begin{classdesc}{Filter}{\optional{name}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
867 Returns an instance of the \class{Filter} class. If \var{name} is specified,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
868 it names a logger which, together with its children, will have its events
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
869 allowed through the filter. If no name is specified, allows every event.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
870 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
871
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
872 \begin{methoddesc}{filter}{record}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
873 Is the specified record to be logged? Returns zero for no, nonzero for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
874 yes. If deemed appropriate, the record may be modified in-place by this
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
875 method.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
876 \end{methoddesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
877
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
878 \subsection{LogRecord Objects}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
879
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
880 LogRecord instances are created every time something is logged. They
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
881 contain all the information pertinent to the event being logged. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
882 main information passed in is in msg and args, which are combined
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
883 using msg \% args to create the message field of the record. The record
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
884 also includes information such as when the record was created, the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
885 source line where the logging call was made, and any exception
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
886 information to be logged.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
887
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
888 LogRecord has no methods; it's just a repository for information about the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
889 logging event. The only reason it's a class rather than a dictionary is to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
890 facilitate extension.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
891
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
892 \begin{classdesc}{LogRecord}{name, lvl, pathname, lineno, msg, args,
27932
ac683ac6759a SF patch #687683, Patches to logging (updates from Vinay)
Neal Norwitz <nnorwitz@gmail.com>
parents: 27496
diff changeset
893 exc_info}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
894 Returns an instance of \class{LogRecord} initialized with interesting
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
895 information. The \var{name} is the logger name; \var{lvl} is the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
896 numeric level; \var{pathname} is the absolute pathname of the source
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
897 file in which the logging call was made; \var{lineno} is the line
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
898 number in that file where the logging call is found; \var{msg} is the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
899 user-supplied message (a format string); \var{args} is the tuple
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
900 which, together with \var{msg}, makes up the user message; and
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
901 \var{exc_info} is the exception tuple obtained by calling
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
902 \function{sys.exc_info() }(or \constant{None}, if no exception information
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
903 is available).
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
904 \end{classdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
905
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
906 \subsection{Thread Safety}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
907
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
908 The logging module is intended to be thread-safe without any special work
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
909 needing to be done by its clients. It achieves this though using threading
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
910 locks; there is one lock to serialize access to the module's shared data,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
911 and each handler also creates a lock to serialize access to its underlying
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
912 I/O.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
913
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
914 \subsection{Configuration}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
915
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
916
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
917 \subsubsection{Configuration functions}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
918
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
919 The following functions allow the logging module to be configured.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
920
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
921 \begin{funcdesc}{fileConfig}{fname\optional{, defaults}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
922 Reads the logging configuration from a ConfigParser-format file named
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
923 \var{fname}. This function can be called several times from an application,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
924 allowing an end user the ability to select from various pre-canned
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
925 configurations (if the developer provides a mechanism to present the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
926 choices and load the chosen configuration). Defaults to be passed to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
927 ConfigParser can be specified in the \var{defaults} argument.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
928 \end{funcdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
929
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
930 \begin{funcdesc}{listen}{\optional{port}}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
931 Starts up a socket server on the specified port, and listens for new
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
932 configurations. If no port is specified, the module's default
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
933 \constant{DEFAULT_LOGGING_CONFIG_PORT} is used. Logging configurations
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
934 will be sent as a file suitable for processing by \function{fileConfig()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
935 Returns a \class{Thread} instance on which you can call \method{start()}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
936 to start the server, and which you can \method{join()} when appropriate.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
937 To stop the server, call \function{stopListening()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
938 \end{funcdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
939
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
940 \begin{funcdesc}{stopListening}{}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
941 Stops the listening server which was created with a call to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
942 \function{listen()}. This is typically called before calling \method{join()}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
943 on the return value from \function{listen()}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
944 \end{funcdesc}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
945
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
946 \subsubsection{Configuration file format}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
947
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
948 The configuration file format understood by \function{fileConfig} is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
949 based on ConfigParser functionality. The file must contain sections
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
950 called \code{[loggers]}, \code{[handlers]} and \code{[formatters]}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
951 which identify by name the entities of each type which are defined in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
952 the file. For each such entity, there is a separate section which
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
953 identified how that entity is configured. Thus, for a logger named
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
954 \code{log01} in the \code{[loggers]} section, the relevant
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
955 configuration details are held in a section
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
956 \code{[logger_log01]}. Similarly, a handler called \code{hand01} in
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
957 the \code{[handlers]} section will have its configuration held in a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
958 section called \code{[handler_hand01]}, while a formatter called
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
959 \code{form01} in the \code{[formatters]} section will have its
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
960 configuration specified in a section called
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
961 \code{[formatter_form01]}. The root logger configuration must be
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
962 specified in a section called \code{[logger_root]}.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
963
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
964 Examples of these sections in the file are given below.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
965
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
966 \begin{verbatim}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
967 [loggers]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
968 keys=root,log02,log03,log04,log05,log06,log07
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
969
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
970 [handlers]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
971 keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
972
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
973 [formatters]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
974 keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
975 \end{verbatim}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
976
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
977 The root logger must specify a level and a list of handlers. An
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
978 example of a root logger section is given below.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
979
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
980 \begin{verbatim}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
981 [logger_root]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
982 level=NOTSET
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
983 handlers=hand01
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
984 \end{verbatim}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
985
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
986 The \code{level} entry can be one of \code{DEBUG, INFO, WARNING,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
987 ERROR, CRITICAL} or \code{NOTSET}. For the root logger only,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
988 \code{NOTSET} means that all messages will be logged. Level values are
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
989 \function{eval()}uated in the context of the \code{logging} package's
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
990 namespace.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
991
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
992 The \code{handlers} entry is a comma-separated list of handler names,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
993 which must appear in the \code{[handlers]} section. These names must
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
994 appear in the \code{[handlers]} section and have corresponding
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
995 sections in the configuration file.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
996
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
997 For loggers other than the root logger, some additional information is
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
998 required. This is illustrated by the following example.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
999
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1000 \begin{verbatim}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1001 [logger_parser]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1002 level=DEBUG
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1003 handlers=hand01
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1004 propagate=1
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1005 qualname=compiler.parser
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1006 \end{verbatim}
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1007
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1008 The \code{level} and \code{handlers} entries are interpreted as for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1009 the root logger, except that if a non-root logger's level is specified
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1010 as \code{NOTSET}, the system consults loggers higher up the hierarchy
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1011 to determine the effective level of the logger. The \code{propagate}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1012 entry is set to 1 to indicate that messages must propagate to handlers
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1013 higher up the logger hierarchy from this logger, or 0 to indicate that
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1014 messages are \strong{not} propagated to handlers up the hierarchy. The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1015 \code{qualname} entry is the hierarchical channel name of the logger,
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1016 i.e. the name used by the application to get the logger.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1017
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1018 Sections which specify handler configuration are exemplified by the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1019 following.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1020
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1021 \begin{verbatim}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1022 [handler_hand01]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1023 class=StreamHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1024 level=NOTSET
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1025 formatter=form01
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1026 args=(sys.stdout,)
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1027 \end{verbatim}
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1028
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1029 The \code{class} entry indicates the handler's class (as determined by
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1030 \function{eval()} in the \code{logging} package's namespace). The
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1031 \code{level} is interpreted as for loggers, and \code{NOTSET} is taken
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1032 to mean "log everything".
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1033
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1034 The \code{formatter} entry indicates the key name of the formatter for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1035 this handler. If blank, a default formatter
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1036 (\code{logging._defaultFormatter}) is used. If a name is specified, it
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1037 must appear in the \code{[formatters]} section and have a
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1038 corresponding section in the configuration file.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1039
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1040 The \code{args} entry, when \function{eval()}uated in the context of
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1041 the \code{logging} package's namespace, is the list of arguments to
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1042 the constructor for the handler class. Refer to the constructors for
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1043 the relevant handlers, or to the examples below, to see how typical
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1044 entries are constructed.
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1045
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1046 \begin{verbatim}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1047 [handler_hand02]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1048 class=FileHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1049 level=DEBUG
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1050 formatter=form02
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1051 args=('python.log', 'w')
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1052
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1053 [handler_hand03]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1054 class=handlers.SocketHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1055 level=INFO
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1056 formatter=form03
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1057 args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1058
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1059 [handler_hand04]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1060 class=handlers.DatagramHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1061 level=WARN
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1062 formatter=form04
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1063 args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1064
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1065 [handler_hand05]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1066 class=handlers.SysLogHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1067 level=ERROR
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1068 formatter=form05
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1069 args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1070
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1071 [handler_hand06]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1072 class=NTEventLogHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1073 level=CRITICAL
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1074 formatter=form06
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1075 args=('Python Application', '', 'Application')
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1076
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1077 [handler_hand07]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1078 class=SMTPHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1079 level=WARN
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1080 formatter=form07
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1081 args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1082
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1083 [handler_hand08]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1084 class=MemoryHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1085 level=NOTSET
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1086 formatter=form08
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1087 target=
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1088 args=(10, ERROR)
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1089
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1090 [handler_hand09]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1091 class=HTTPHandler
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1092 level=NOTSET
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1093 formatter=form09
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1094 args=('localhost:9022', '/log', 'GET')
26215
7cfb52f98139 initial rough cut at documentation of logging module. This is basically
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
1095 \end{verbatim}
27378
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1096
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1097 Sections which specify formatter configuration are typified by the following.
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1098
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1099 \begin{verbatim}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1100 [formatter_form01]
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1101 format=F1 %(asctime)s %(levelname)s %(message)s
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1102 datefmt=
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1103 \end{verbatim}
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1104
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1105 The \code{format} entry is the overall format string, and the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1106 \code{datefmt} entry is the \function{strftime()}-compatible date/time format
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1107 string. If empty, the package substitutes ISO8601 format date/times, which
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1108 is almost equivalent to specifying the date format string "%Y-%m-%d %H:%M:%S".
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1109 The ISO8601 format also specifies milliseconds, which are appended to the
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1110 result of using the above format string, with a comma separator. An example
81569ccde5bd SF #638299, LaTeX documentation for logging package
Neal Norwitz <nnorwitz@gmail.com>
parents: 26401
diff changeset
1111 time in ISO8601 format is \code{2003-01-23 00:29:50,411}.