Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 0cca762

Browse filesBrowse files
miss-islingtonmiss-islington
authored
[3.12] gh-98731: Improvements to the logging documentation (GH-101618) (GH-116734)
(cherry picked from commit 7f418fb)
1 parent 8e45f7d commit 0cca762
Copy full SHA for 0cca762

File tree

Expand file treeCollapse file tree

2 files changed

+108
-162
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+108
-162
lines changed

‎Doc/howto/logging.rst

Copy file name to clipboardExpand all lines: Doc/howto/logging.rst
+41-77Lines changed: 41 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,12 @@ or *severity*.
2525
When to use logging
2626
^^^^^^^^^^^^^^^^^^^
2727

28-
Logging provides a set of convenience functions for simple logging usage. These
29-
are :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and
30-
:func:`critical`. To determine when to use logging, see the table below, which
31-
states, for each of a set of common tasks, the best tool to use for it.
28+
You can access logging functionality by creating a logger via ``logger =
29+
getLogger(__name__)``, and then calling the logger's :meth:`~Logger.debug`,
30+
:meth:`~Logger.info`, :meth:`~Logger.warning`, :meth:`~Logger.error` and
31+
:meth:`~Logger.critical` methods. To determine when to use logging, and to see
32+
which logger methods to use when, see the table below. It states, for each of a
33+
set of common tasks, the best tool to use for that task.
3234

3335
+-------------------------------------+--------------------------------------+
3436
| Task you want to perform | The best tool for the task |
@@ -37,8 +39,8 @@ states, for each of a set of common tasks, the best tool to use for it.
3739
| usage of a command line script or | |
3840
| program | |
3941
+-------------------------------------+--------------------------------------+
40-
| Report events that occur during | :func:`logging.info` (or |
41-
| normal operation of a program (e.g. | :func:`logging.debug` for very |
42+
| Report events that occur during | A logger's :meth:`~Logger.info` (or |
43+
| normal operation of a program (e.g. | :meth:`~Logger.debug` method for very|
4244
| for status monitoring or fault | detailed output for diagnostic |
4345
| investigation) | purposes) |
4446
+-------------------------------------+--------------------------------------+
@@ -47,22 +49,23 @@ states, for each of a set of common tasks, the best tool to use for it.
4749
| | the client application should be |
4850
| | modified to eliminate the warning |
4951
| | |
50-
| | :func:`logging.warning` if there is |
51-
| | nothing the client application can do|
52-
| | about the situation, but the event |
53-
| | should still be noted |
52+
| | A logger's :meth:`~Logger.warning` |
53+
| | method if there is nothing the client|
54+
| | application can do about the |
55+
| | situation, but the event should still|
56+
| | be noted |
5457
+-------------------------------------+--------------------------------------+
5558
| Report an error regarding a | Raise an exception |
5659
| particular runtime event | |
5760
+-------------------------------------+--------------------------------------+
58-
| Report suppression of an error | :func:`logging.error`, |
59-
| without raising an exception (e.g. | :func:`logging.exception` or |
60-
| error handler in a long-running | :func:`logging.critical` as |
61+
| Report suppression of an error | A logger's :meth:`~Logger.error`, |
62+
| without raising an exception (e.g. | :meth:`~Logger.exception` or |
63+
| error handler in a long-running | :meth:`~Logger.critical` method as |
6164
| server process) | appropriate for the specific error |
6265
| | and application domain |
6366
+-------------------------------------+--------------------------------------+
6467

65-
The logging functions are named after the level or severity of the events
68+
The logger methods are named after the level or severity of the events
6669
they are used to track. The standard levels and their applicability are
6770
described below (in increasing order of severity):
6871

@@ -116,12 +119,18 @@ If you type these lines into a script and run it, you'll see:
116119
WARNING:root:Watch out!
117120
118121
printed out on the console. The ``INFO`` message doesn't appear because the
119-
default level is ``WARNING``. The printed message includes the indication of
120-
the level and the description of the event provided in the logging call, i.e.
121-
'Watch out!'. Don't worry about the 'root' part for now: it will be explained
122-
later. The actual output can be formatted quite flexibly if you need that;
123-
formatting options will also be explained later.
124-
122+
default level is ``WARNING``. The printed message includes the indication of the
123+
level and the description of the event provided in the logging call, i.e.
124+
'Watch out!'. The actual output can be formatted quite flexibly if you need
125+
that; formatting options will also be explained later.
126+
127+
Notice that in this example, we use functions directly on the ``logging``
128+
module, like ``logging.debug``, rather than creating a logger and calling
129+
functions on it. These functions operation on the root logger, but can be useful
130+
as they will call :func:`~logging.basicConfig` for you if it has not been called yet, like in
131+
this example. In larger programs you'll usually want to control the logging
132+
configuration explicitly however - so for that reason as well as others, it's
133+
better to create loggers and call their methods.
125134

126135
Logging to a file
127136
^^^^^^^^^^^^^^^^^
@@ -131,11 +140,12 @@ look at that next. Be sure to try the following in a newly started Python
131140
interpreter, and don't just continue from the session described above::
132141

133142
import logging
143+
logger = logging.getLogger(__name__)
134144
logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
135-
logging.debug('This message should go to the log file')
136-
logging.info('So should this')
137-
logging.warning('And this, too')
138-
logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
145+
logger.debug('This message should go to the log file')
146+
logger.info('So should this')
147+
logger.warning('And this, too')
148+
logger.error('And non-ASCII stuff, too, like Øresund and Malmö')
139149

140150
.. versionchanged:: 3.9
141151
The *encoding* argument was added. In earlier Python versions, or if not
@@ -149,10 +159,10 @@ messages:
149159

150160
.. code-block:: none
151161
152-
DEBUG:root:This message should go to the log file
153-
INFO:root:So should this
154-
WARNING:root:And this, too
155-
ERROR:root:And non-ASCII stuff, too, like Øresund and Malmö
162+
DEBUG:__main__:This message should go to the log file
163+
INFO:__main__:So should this
164+
WARNING:__main__:And this, too
165+
ERROR:__main__:And non-ASCII stuff, too, like Øresund and Malmö
156166
157167
This example also shows how you can set the logging level which acts as the
158168
threshold for tracking. In this case, because we set the threshold to
@@ -181,11 +191,9 @@ following example::
181191
raise ValueError('Invalid log level: %s' % loglevel)
182192
logging.basicConfig(level=numeric_level, ...)
183193

184-
The call to :func:`basicConfig` should come *before* any calls to
185-
:func:`debug`, :func:`info`, etc. Otherwise, those functions will call
186-
:func:`basicConfig` for you with the default options. As it's intended as a
187-
one-off simple configuration facility, only the first call will actually do
188-
anything: subsequent calls are effectively no-ops.
194+
The call to :func:`basicConfig` should come *before* any calls to a logger's
195+
methods such as :meth:`~Logger.debug`, :meth:`~Logger.info`, etc. Otherwise,
196+
that logging event may not be handled in the desired manner.
189197

190198
If you run the above script several times, the messages from successive runs
191199
are appended to the file *example.log*. If you want each run to start afresh,
@@ -198,50 +206,6 @@ The output will be the same as before, but the log file is no longer appended
198206
to, so the messages from earlier runs are lost.
199207

200208

201-
Logging from multiple modules
202-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203-
204-
If your program consists of multiple modules, here's an example of how you
205-
could organize logging in it::
206-
207-
# myapp.py
208-
import logging
209-
import mylib
210-
211-
def main():
212-
logging.basicConfig(filename='myapp.log', level=logging.INFO)
213-
logging.info('Started')
214-
mylib.do_something()
215-
logging.info('Finished')
216-
217-
if __name__ == '__main__':
218-
main()
219-
220-
::
221-
222-
# mylib.py
223-
import logging
224-
225-
def do_something():
226-
logging.info('Doing something')
227-
228-
If you run *myapp.py*, you should see this in *myapp.log*:
229-
230-
.. code-block:: none
231-
232-
INFO:root:Started
233-
INFO:root:Doing something
234-
INFO:root:Finished
235-
236-
which is hopefully what you were expecting to see. You can generalize this to
237-
multiple modules, using the pattern in *mylib.py*. Note that for this simple
238-
usage pattern, you won't know, by looking in the log file, *where* in your
239-
application your messages came from, apart from looking at the event
240-
description. If you want to track the location of your messages, you'll need
241-
to refer to the documentation beyond the tutorial level -- see
242-
:ref:`logging-advanced-tutorial`.
243-
244-
245209
Logging variable data
246210
^^^^^^^^^^^^^^^^^^^^^
247211

‎Doc/library/logging.rst

Copy file name to clipboardExpand all lines: Doc/library/logging.rst
+67-85Lines changed: 67 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,53 @@ is that all Python modules can participate in logging, so your application log
3030
can include your own messages integrated with messages from third-party
3131
modules.
3232

33-
The simplest example:
33+
Here's a simple example of idiomatic usage: ::
34+
35+
# myapp.py
36+
import logging
37+
import mylib
38+
logger = logging.getLogger(__name__)
39+
40+
def main():
41+
logging.basicConfig(filename='myapp.log', level=logging.INFO)
42+
logger.info('Started')
43+
mylib.do_something()
44+
logger.info('Finished')
45+
46+
if __name__ == '__main__':
47+
main()
48+
49+
::
50+
51+
# mylib.py
52+
import logging
53+
logger = logging.getLogger(__name__)
54+
55+
def do_something():
56+
logger.info('Doing something')
57+
58+
If you run *myapp.py*, you should see this in *myapp.log*:
3459

3560
.. code-block:: none
3661
37-
>>> import logging
38-
>>> logging.warning('Watch out!')
39-
WARNING:root:Watch out!
62+
INFO:__main__:Started
63+
INFO:mylib:Doing something
64+
INFO:__main__:Finished
65+
66+
The key features of this idiomatic usage is that the majority of code is simply
67+
creating a module level logger with ``getLogger(__name__)``, and using that
68+
logger to do any needed logging. This is concise while allowing downstream code
69+
fine grained control if needed. Logged messages to the module-level logger get
70+
forwarded up to handlers of loggers in higher-level modules, all the way up to
71+
the root logger; for this reason this approach is known as hierarchical logging.
72+
73+
For logging to be useful, it needs to be configured: setting the levels and
74+
destinations for each logger, potentially changing how specific modules log,
75+
often based on command-line arguments or application configuration. In most
76+
cases, like the one above, only the root logger needs to be so configured, since
77+
all the lower level loggers at module level eventually forward their messages to
78+
its handlers. :func:`~logging.basicConfig` provides a quick way to configure
79+
the root logger that handles many use cases.
4080

4181
The module provides a lot of functionality and flexibility. If you are
4282
unfamiliar with logging, the best way to get to grips with it is to view the
@@ -1138,89 +1178,31 @@ functions.
11381178

11391179
.. function:: debug(msg, *args, **kwargs)
11401180

1141-
Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the
1142-
message format string, and the *args* are the arguments which are merged into
1143-
*msg* using the string formatting operator. (Note that this means that you can
1144-
use keywords in the format string, together with a single dictionary argument.)
1145-
1146-
There are three keyword arguments in *kwargs* which are inspected: *exc_info*
1147-
which, if it does not evaluate as false, causes exception information to be
1148-
added to the logging message. If an exception tuple (in the format returned by
1149-
:func:`sys.exc_info`) or an exception instance is provided, it is used;
1150-
otherwise, :func:`sys.exc_info` is called to get the exception information.
1151-
1152-
The second optional keyword argument is *stack_info*, which defaults to
1153-
``False``. If true, stack information is added to the logging
1154-
message, including the actual logging call. Note that this is not the same
1155-
stack information as that displayed through specifying *exc_info*: The
1156-
former is stack frames from the bottom of the stack up to the logging call
1157-
in the current thread, whereas the latter is information about stack frames
1158-
which have been unwound, following an exception, while searching for
1159-
exception handlers.
1160-
1161-
You can specify *stack_info* independently of *exc_info*, e.g. to just show
1162-
how you got to a certain point in your code, even when no exceptions were
1163-
raised. The stack frames are printed following a header line which says:
1164-
1165-
.. code-block:: none
1181+
This is a convenience function that calls :meth:`Logger.debug`, on the root
1182+
logger. The handling of the arguments is in every way identical
1183+
to what is described in that method.
11661184

1167-
Stack (most recent call last):
1185+
The only difference is that if the root logger has no handlers, then
1186+
:func:`basicConfig` is called, prior to calling ``debug`` on the root logger.
11681187

1169-
This mimics the ``Traceback (most recent call last):`` which is used when
1170-
displaying exception frames.
1188+
For very short scripts or quick demonstrations of ``logging`` facilities,
1189+
``debug`` and the other module-level functions may be convenient. However,
1190+
most programs will want to carefully and explicitly control the logging
1191+
configuration, and should therefore prefer creating a module-level logger and
1192+
calling :meth:`Logger.debug` (or other level-specific methods) on it, as
1193+
described at the beginnning of this documentation.
11711194

1172-
The third optional keyword argument is *extra* which can be used to pass a
1173-
dictionary which is used to populate the __dict__ of the LogRecord created for
1174-
the logging event with user-defined attributes. These custom attributes can then
1175-
be used as you like. For example, they could be incorporated into logged
1176-
messages. For example::
1177-
1178-
FORMAT = '%(asctime)s %(clientip)-15s %(user)-8s %(message)s'
1179-
logging.basicConfig(format=FORMAT)
1180-
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
1181-
logging.warning('Protocol problem: %s', 'connection reset', extra=d)
1182-
1183-
would print something like:
1184-
1185-
.. code-block:: none
1186-
1187-
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
1188-
1189-
The keys in the dictionary passed in *extra* should not clash with the keys used
1190-
by the logging system. (See the :class:`Formatter` documentation for more
1191-
information on which keys are used by the logging system.)
1192-
1193-
If you choose to use these attributes in logged messages, you need to exercise
1194-
some care. In the above example, for instance, the :class:`Formatter` has been
1195-
set up with a format string which expects 'clientip' and 'user' in the attribute
1196-
dictionary of the LogRecord. If these are missing, the message will not be
1197-
logged because a string formatting exception will occur. So in this case, you
1198-
always need to pass the *extra* dictionary with these keys.
1199-
1200-
While this might be annoying, this feature is intended for use in specialized
1201-
circumstances, such as multi-threaded servers where the same code executes in
1202-
many contexts, and interesting conditions which arise are dependent on this
1203-
context (such as remote client IP address and authenticated user name, in the
1204-
above example). In such circumstances, it is likely that specialized
1205-
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
1206-
1207-
This function (as well as :func:`info`, :func:`warning`, :func:`error` and
1208-
:func:`critical`) will call :func:`basicConfig` if the root logger doesn't
1209-
have any handler attached.
1210-
1211-
.. versionchanged:: 3.2
1212-
The *stack_info* parameter was added.
12131195

12141196
.. function:: info(msg, *args, **kwargs)
12151197

1216-
Logs a message with level :const:`INFO` on the root logger. The arguments are
1217-
interpreted as for :func:`debug`.
1198+
Logs a message with level :const:`INFO` on the root logger. The arguments and behavior
1199+
are otherwise the same as for :func:`debug`.
12181200

12191201

12201202
.. function:: warning(msg, *args, **kwargs)
12211203

1222-
Logs a message with level :const:`WARNING` on the root logger. The arguments
1223-
are interpreted as for :func:`debug`.
1204+
Logs a message with level :const:`WARNING` on the root logger. The arguments and behavior
1205+
are otherwise the same as for :func:`debug`.
12241206

12251207
.. note:: There is an obsolete function ``warn`` which is functionally
12261208
identical to ``warning``. As ``warn`` is deprecated, please do not use
@@ -1229,26 +1211,26 @@ functions.
12291211

12301212
.. function:: error(msg, *args, **kwargs)
12311213

1232-
Logs a message with level :const:`ERROR` on the root logger. The arguments are
1233-
interpreted as for :func:`debug`.
1214+
Logs a message with level :const:`ERROR` on the root logger. The arguments and behavior
1215+
are otherwise the same as for :func:`debug`.
12341216

12351217

12361218
.. function:: critical(msg, *args, **kwargs)
12371219

1238-
Logs a message with level :const:`CRITICAL` on the root logger. The arguments
1239-
are interpreted as for :func:`debug`.
1220+
Logs a message with level :const:`CRITICAL` on the root logger. The arguments and behavior
1221+
are otherwise the same as for :func:`debug`.
12401222

12411223

12421224
.. function:: exception(msg, *args, **kwargs)
12431225

1244-
Logs a message with level :const:`ERROR` on the root logger. The arguments are
1245-
interpreted as for :func:`debug`. Exception info is added to the logging
1226+
Logs a message with level :const:`ERROR` on the root logger. The arguments and behavior
1227+
are otherwise the same as for :func:`debug`. Exception info is added to the logging
12461228
message. This function should only be called from an exception handler.
12471229

12481230
.. function:: log(level, msg, *args, **kwargs)
12491231

1250-
Logs a message with level *level* on the root logger. The other arguments are
1251-
interpreted as for :func:`debug`.
1232+
Logs a message with level *level* on the root logger. The arguments and behavior
1233+
are otherwise the same as for :func:`debug`.
12521234

12531235
.. function:: disable(level=CRITICAL)
12541236

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.