bpo-37111: Add 'encoding' and 'errors' parameters to logging.basicCon… (GH-14008)
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