diff options
Diffstat (limited to 'Doc/library/logging.handlers.rst')
| -rw-r--r-- | Doc/library/logging.handlers.rst | 104 |
1 files changed, 75 insertions, 29 deletions
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index b16eef03b1..f13f765c01 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -84,6 +84,9 @@ sends logging output to a disk file. It inherits the output functionality from 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. + .. versionchanged:: 3.6 + As well as string values, :class:`~pathlib.Path` objects are also accepted + for the *filename* argument. .. method:: close() @@ -160,12 +163,23 @@ for this value. 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. + .. versionchanged:: 3.6 + As well as string values, :class:`~pathlib.Path` objects are also accepted + for the *filename* argument. + + .. method:: reopenIfNeeded() + + Checks to see if the file has changed. If it has, the existing stream is + flushed and closed and the file opened again, typically as a precursor to + outputting the record to the file. + + .. versionadded:: 3.6 + .. method:: emit(record) - Outputs the record to the file, but first checks to see if the file has - changed. If it has, the existing stream is flushed and closed and the - file opened again, before outputting the record to the file. + Outputs the record to the file, but first calls :meth:`reopenIfNeeded` to + reopen the file if it has changed. .. _base-rotating-handler: @@ -268,17 +282,21 @@ module, supports rotation of disk log files. 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, the file is closed and a new file is silently opened for output. Rollover occurs - whenever the current log file is nearly *maxBytes* in length; if either of - *maxBytes* or *backupCount* is zero, rollover never occurs. If *backupCount* - is non-zero, the system will save old log files by appending the extensions - '.1', '.2' etc., to the filename. For example, with a *backupCount* of 5 and - a base file name of :file:`app.log`, you would get :file:`app.log`, + whenever the current log file is nearly *maxBytes* in length; but if either of + *maxBytes* or *backupCount* is zero, rollover never occurs, so you generally want + to set *backupCount* to at least 1, and have a non-zero *maxBytes*. + When *backupCount* is non-zero, the system will save old log files by appending + the extensions '.1', '.2' etc., to the filename. For example, with a *backupCount* + of 5 and a base file name of :file:`app.log`, you would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to :file:`app.log.5`. The file being written to is always :file:`app.log`. When this file is filled, it is closed and renamed to :file:`app.log.1`, and if files :file:`app.log.1`, - :file:`app.log.2`, etc. exist, then they are renamed to :file:`app.log.2`, - :file:`app.log.3` etc. respectively. + :file:`app.log.2`, etc. exist, then they are renamed to :file:`app.log.2`, + :file:`app.log.3` etc. respectively. + .. versionchanged:: 3.6 + As well as string values, :class:`~pathlib.Path` objects are also accepted + for the *filename* argument. .. method:: doRollover() @@ -310,21 +328,24 @@ timed intervals. You can use the *when* to specify the type of *interval*. The list of possible values is below. Note that they are not case sensitive. - +----------------+-----------------------+ - | Value | Type of interval | - +================+=======================+ - | ``'S'`` | Seconds | - +----------------+-----------------------+ - | ``'M'`` | Minutes | - +----------------+-----------------------+ - | ``'H'`` | Hours | - +----------------+-----------------------+ - | ``'D'`` | Days | - +----------------+-----------------------+ - | ``'W0'-'W6'`` | Weekday (0=Monday) | - +----------------+-----------------------+ - | ``'midnight'`` | Roll over at midnight | - +----------------+-----------------------+ + +----------------+----------------------------+-------------------------+ + | Value | Type of interval | If/how *atTime* is used | + +================+============================+=========================+ + | ``'S'`` | Seconds | Ignored | + +----------------+----------------------------+-------------------------+ + | ``'M'`` | Minutes | Ignored | + +----------------+----------------------------+-------------------------+ + | ``'H'`` | Hours | Ignored | + +----------------+----------------------------+-------------------------+ + | ``'D'`` | Days | Ignored | + +----------------+----------------------------+-------------------------+ + | ``'W0'-'W6'`` | Weekday (0=Monday) | Used to compute initial | + | | | rollover time | + +----------------+----------------------------+-------------------------+ + | ``'midnight'`` | Roll over at midnight, if | Used to compute initial | + | | *atTime* not specified, | rollover time | + | | else at time *atTime* | | + +----------------+----------------------------+-------------------------+ When using weekday-based rotation, specify 'W0' for Monday, 'W1' for Tuesday, and so on up to 'W6' for Sunday. In this case, the value passed for @@ -352,16 +373,35 @@ timed intervals. If *atTime* is not ``None``, it must be a ``datetime.time`` instance which specifies the time of day when rollover occurs, for the cases where rollover - is set to happen "at midnight" or "on a particular weekday". + is set to happen "at midnight" or "on a particular weekday". Note that in + these cases, the *atTime* value is effectively used to compute the *initial* + rollover, and subsequent rollovers would be calculated via the normal + interval calculation. + + .. 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 + this is not kept in mind, it might lead to some confusion. For example, + if an interval of "every minute" is set, that does not mean you will + always see log files with times (in the filename) separated by a minute; + if, during application execution, logging output is generated more + frequently than once a minute, *then* you can expect to see log files + with times separated by a minute. If, on the other hand, logging messages + are only output once every five minutes (say), then there will be gaps in + the file times corresponding to the minutes where no output (and hence no + rollover) occurred. .. versionchanged:: 3.4 *atTime* parameter was added. + .. versionchanged:: 3.6 + As well as string values, :class:`~pathlib.Path` objects are also accepted + for the *filename* argument. + .. method:: doRollover() Does a rollover, as described above. - .. method:: emit(record) Outputs the record to the file, catering for rollover as described above. @@ -798,12 +838,18 @@ should, then :meth:`flush` is expected to do the flushing. overridden to implement custom flushing strategies. -.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None) +.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None, flushOnClose=True) Returns a new instance of the :class:`MemoryHandler` class. The instance is initialized with a buffer size of *capacity*. If *flushLevel* is not specified, :const:`ERROR` is used. If no *target* is specified, the target will need to be - set using :meth:`setTarget` before this handler does anything useful. + set using :meth:`setTarget` before this handler does anything useful. If + *flushOnClose* is specified as ``False``, then the buffer is *not* flushed when + the handler is closed. If not specified or specified as ``True``, the previous + behaviour of flushing the buffer will occur when the handler is closed. + + .. versionchanged:: 3.6 + The *flushOnClose* parameter was added. .. method:: close() |