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.