Skip to content

Commit 95f18f9

Browse files
miss-islingtonsobolevnhugovk
authored
[3.11] gh-101100: Fix sphinx warnings in howto/logging.rst (GH-114846) (#114872)
gh-101100: Fix sphinx warnings in `howto/logging.rst` (GH-114846) (cherry picked from commit dc01b91) Co-authored-by: Nikita Sobolev <[email protected]> Co-authored-by: Hugo van Kemenade <[email protected]>
1 parent a46fddf commit 95f18f9

File tree

3 files changed

+36
-24
lines changed

3 files changed

+36
-24
lines changed

Doc/howto/logging.rst

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ custom handlers) are the following configuration methods:
518518

519519
* The :meth:`~Handler.setLevel` method, just as in logger objects, specifies the
520520
lowest severity that will be dispatched to the appropriate destination. Why
521-
are there two :func:`setLevel` methods? The level set in the logger
521+
are there two :meth:`~Handler.setLevel` methods? The level set in the logger
522522
determines which severity of messages it will pass to its handlers. The level
523523
set in each handler determines which messages that handler will send on.
524524

@@ -772,29 +772,29 @@ What happens if no configuration is provided
772772

773773
If no logging configuration is provided, it is possible to have a situation
774774
where a logging event needs to be output, but no handlers can be found to
775-
output the event. The behaviour of the logging package in these
776-
circumstances is dependent on the Python version.
775+
output the event.
777776

778-
For versions of Python prior to 3.2, the behaviour is as follows:
777+
The event is output using a 'handler of last resort', stored in
778+
:data:`lastResort`. This internal handler is not associated with any
779+
logger, and acts like a :class:`~logging.StreamHandler` which writes the
780+
event description message to the current value of ``sys.stderr`` (therefore
781+
respecting any redirections which may be in effect). No formatting is
782+
done on the message - just the bare event description message is printed.
783+
The handler's level is set to ``WARNING``, so all events at this and
784+
greater severities will be output.
779785

780-
* If *logging.raiseExceptions* is ``False`` (production mode), the event is
781-
silently dropped.
786+
.. versionchanged:: 3.2
782787

783-
* If *logging.raiseExceptions* is ``True`` (development mode), a message
784-
'No handlers could be found for logger X.Y.Z' is printed once.
788+
For versions of Python prior to 3.2, the behaviour is as follows:
785789

786-
In Python 3.2 and later, the behaviour is as follows:
790+
* If :data:`raiseExceptions` is ``False`` (production mode), the event is
791+
silently dropped.
787792

788-
* The event is output using a 'handler of last resort', stored in
789-
``logging.lastResort``. This internal handler is not associated with any
790-
logger, and acts like a :class:`~logging.StreamHandler` which writes the
791-
event description message to the current value of ``sys.stderr`` (therefore
792-
respecting any redirections which may be in effect). No formatting is
793-
done on the message - just the bare event description message is printed.
794-
The handler's level is set to ``WARNING``, so all events at this and
795-
greater severities will be output.
793+
* If :data:`raiseExceptions` is ``True`` (development mode), a message
794+
'No handlers could be found for logger X.Y.Z' is printed once.
796795

797-
To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to ``None``.
796+
To obtain the pre-3.2 behaviour,
797+
:data:`lastResort` can be set to ``None``.
798798

799799
.. _library-config:
800800

@@ -996,7 +996,7 @@ Logged messages are formatted for presentation through instances of the
996996
use with the % operator and a dictionary.
997997

998998
For formatting multiple messages in a batch, instances of
999-
:class:`~handlers.BufferingFormatter` can be used. In addition to the format
999+
:class:`BufferingFormatter` can be used. In addition to the format
10001000
string (which is applied to each message in the batch), there is provision for
10011001
header and trailer format strings.
10021002

@@ -1032,7 +1032,8 @@ checks to see if a module-level variable, :data:`raiseExceptions`, is set. If
10321032
set, a traceback is printed to :data:`sys.stderr`. If not set, the exception is
10331033
swallowed.
10341034

1035-
.. note:: The default value of :data:`raiseExceptions` is ``True``. This is
1035+
.. note::
1036+
The default value of :data:`raiseExceptions` is ``True``. This is
10361037
because during development, you typically want to be notified of any
10371038
exceptions that occur. It's advised that you set :data:`raiseExceptions` to
10381039
``False`` for production usage.
@@ -1070,7 +1071,7 @@ You can write code like this::
10701071
expensive_func2())
10711072

10721073
so that if the logger's threshold is set above ``DEBUG``, the calls to
1073-
:func:`expensive_func1` and :func:`expensive_func2` are never made.
1074+
``expensive_func1`` and ``expensive_func2`` are never made.
10741075

10751076
.. note:: In some cases, :meth:`~Logger.isEnabledFor` can itself be more
10761077
expensive than you'd like (e.g. for deeply nested loggers where an explicit

Doc/library/logging.rst

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -519,12 +519,12 @@ subclasses. However, the :meth:`!__init__` method in subclasses needs to call
519519

520520
This method should be called from handlers when an exception is encountered
521521
during an :meth:`emit` call. If the module-level attribute
522-
``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
522+
:data:`raiseExceptions` is ``False``, exceptions get silently ignored. This is
523523
what is mostly wanted for a logging system - most users will not care about
524524
errors in the logging system, they are more interested in application
525525
errors. You could, however, replace this with a custom handler if you wish.
526526
The specified record is the one which was being processed when the exception
527-
occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
527+
occurred. (The default value of :data:`raiseExceptions` is ``True``, as that is
528528
more useful during development).
529529

530530

@@ -1443,6 +1443,18 @@ Module-Level Attributes
14431443

14441444
.. versionadded:: 3.2
14451445

1446+
.. attribute:: raiseExceptions
1447+
1448+
Used to see if exceptions during handling should be propagated.
1449+
1450+
Default: ``True``.
1451+
1452+
If :data:`raiseExceptions` is ``False``,
1453+
exceptions get silently ignored. This is what is mostly wanted
1454+
for a logging system - most users will not care about errors in
1455+
the logging system, they are more interested in application errors.
1456+
1457+
14461458
Integration with the warnings module
14471459
------------------------------------
14481460

Doc/tools/.nitignore

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ Doc/extending/extending.rst
1919
Doc/glossary.rst
2020
Doc/howto/descriptor.rst
2121
Doc/howto/enum.rst
22-
Doc/howto/logging.rst
2322
Doc/library/ast.rst
2423
Doc/library/asyncio-extending.rst
2524
Doc/library/asyncio-policy.rst

0 commit comments

Comments
 (0)