bpo-37111: Add 'encoding' and 'errors' parameters to logging.basicCon… (GH-14008)
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index 7a68ca8..fbe5a11 100644
--- a/Doc/howto/logging.rst
+++ b/Doc/howto/logging.rst
@@ -128,10 +128,18 @@
interpreter, and don't just continue from the session described above::
import logging
- logging.basicConfig(filename='example.log',level=logging.DEBUG)
+ logging.basicConfig(filename='example.log', encoding='utf-8', level=logging.DEBUG)
logging.debug('This message should go to the log file')
logging.info('So should this')
logging.warning('And this, too')
+ logging.error('And non-ASCII stuff, too, like Øresund and Malmö')
+
+.. versionchanged:: 3.9
+ The *encoding* argument was added. In earlier Python versions, or if not
+ specified, the encoding used is the default value used by :func:`open`. While
+ not shown in the above example, an *errors* argument can also now be passed,
+ which determines how encoding errors are handled. For available values and
+ the default, see the documentation for :func:`open`.
And now if we open the file and look at what we have, we should find the log
messages:
@@ -141,6 +149,7 @@
DEBUG:root:This message should go to the log file
INFO:root:So should this
WARNING:root:And this, too
+ ERROR:root:And non-ASCII stuff, too, like Øresund and Malmö
This example also shows how you can set the logging level which acts as the
threshold for tracking. In this case, because we set the threshold to
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
index dee9a84..822f82d 100644
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -89,18 +89,22 @@
:class:`StreamHandler`.
-.. class:: FileHandler(filename, mode='a', encoding=None, delay=False)
+.. class:: FileHandler(filename, mode='a', encoding=None, delay=False, errors=None)
Returns a new instance of the :class:`FileHandler` class. The specified file is
opened and used as the stream for logging. If *mode* is not specified,
:const:`'a'` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
- first call to :meth:`emit`. By default, the file grows indefinitely.
+ first call to :meth:`emit`. By default, the file grows indefinitely. If
+ *errors* is specified, it's used to determine how encoding errors are handled.
.. versionchanged:: 3.6
As well as string values, :class:`~pathlib.Path` objects are also accepted
for the *filename* argument.
+ .. versionchanged:: 3.9
+ The *errors* parameter was added.
+
.. method:: close()
Closes the file.
@@ -168,18 +172,22 @@
for this value.
-.. class:: WatchedFileHandler(filename, mode='a', encoding=None, delay=False)
+.. class:: WatchedFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)
Returns a new instance of the :class:`WatchedFileHandler` class. The specified
file is opened and used as the stream for logging. If *mode* is not specified,
:const:`'a'` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
- first call to :meth:`emit`. By default, the file grows indefinitely.
+ first call to :meth:`emit`. By default, the file grows indefinitely. If
+ *errors* is provided, it determines how encoding errors are handled.
.. versionchanged:: 3.6
As well as string values, :class:`~pathlib.Path` objects are also accepted
for the *filename* argument.
+ .. versionchanged:: 3.9
+ The *errors* parameter was added.
+
.. method:: reopenIfNeeded()
Checks to see if the file has changed. If it has, the existing stream is
@@ -205,7 +213,7 @@
not need to instantiate this class, but it has attributes and methods you may
need to override.
-.. class:: BaseRotatingHandler(filename, mode, encoding=None, delay=False)
+.. class:: BaseRotatingHandler(filename, mode, encoding=None, delay=False, errors=None)
The parameters are as for :class:`FileHandler`. The attributes are:
@@ -284,13 +292,14 @@
module, supports rotation of disk log files.
-.. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False)
+.. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None)
Returns a new instance of the :class:`RotatingFileHandler` class. The specified
file is opened and used as the stream for logging. If *mode* is not specified,
``'a'`` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
- first call to :meth:`emit`. By default, the file grows indefinitely.
+ first call to :meth:`emit`. By default, the file grows indefinitely. If
+ *errors* is provided, it determines how encoding errors are handled.
You can use the *maxBytes* and *backupCount* values to allow the file to
:dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
@@ -311,6 +320,9 @@
As well as string values, :class:`~pathlib.Path` objects are also accepted
for the *filename* argument.
+ .. versionchanged:: 3.9
+ The *errors* parameter was added.
+
.. method:: doRollover()
Does a rollover, as described above.
@@ -331,7 +343,7 @@
timed intervals.
-.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None)
+.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None, errors=None)
Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
specified file is opened and used as the stream for logging. On rotating it also
@@ -391,6 +403,9 @@
rollover, and subsequent rollovers would be calculated via the normal
interval calculation.
+ If *errors* is specified, it's used to determine how encoding errors are
+ handled.
+
.. note:: Calculation of the initial rollover time is done when the handler
is initialised. Calculation of subsequent rollover times is done only
when rollover occurs, and rollover occurs only when emitting output. If
@@ -411,6 +426,9 @@
As well as string values, :class:`~pathlib.Path` objects are also accepted
for the *filename* argument.
+ .. versionchanged:: 3.9
+ The *errors* parameter was added.
+
.. method:: doRollover()
Does a rollover, as described above.
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 08555c3..3e4d7de 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1196,6 +1196,21 @@
| | carrying out the configuration as specified |
| | by the other arguments. |
+--------------+---------------------------------------------+
+ | *encoding* | If this keyword argument is specified along |
+ | | with *filename*, its value is used when the |
+ | | FileHandler is created, and thus used when |
+ | | opening the output file. |
+ +--------------+---------------------------------------------+
+ | *errors* | If this keyword argument is specified along |
+ | | with *filename*, its value is used when the |
+ | | FileHandler is created, and thus used when |
+ | | opening the output file. If not specified, |
+ | | the value 'backslashreplace' is used. Note |
+ | | that if ``None`` is specified, it will be |
+ | | passed as such to func:`open`, which means |
+ | | that it will be treated the same as passing |
+ | | 'errors'. |
+ +--------------+---------------------------------------------+
.. versionchanged:: 3.2
The *style* argument was added.
@@ -1209,6 +1224,9 @@
.. versionchanged:: 3.8
The *force* argument was added.
+ .. versionchanged:: 3.9
+ The *encoding* and *errors* arguments were added.
+
.. function:: shutdown()
Informs the logging system to perform an orderly shutdown by flushing and
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 85263d4..fcf556e 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -81,6 +81,7 @@
howto/ipaddress,,:ffff,IPv6Address('2001:db8::ffff:ffff')
howto/logging,,:And,"WARNING:And this, too"
howto/logging,,:And,"WARNING:root:And this, too"
+howto/logging,,:And,"ERROR:root:And non-ASCII stuff, too, like "
howto/logging,,:Doing,INFO:root:Doing something
howto/logging,,:Finished,INFO:root:Finished
howto/logging,,:logger,severity:logger name:message
@@ -90,6 +91,7 @@
howto/logging,,:root,INFO:root:Doing something
howto/logging,,:root,INFO:root:Finished
howto/logging,,:root,INFO:root:So should this
+howto/logging,,:root,"ERROR:root:And non-ASCII stuff, too, like "
howto/logging,,:root,INFO:root:Started
howto/logging,,:root,"WARNING:root:And this, too"
howto/logging,,:root,WARNING:root:Look before you leap!