[Python-checkins] cpython: Closes #20124: clarified usage of the atTime parameter in
vinay.sajip
python-checkins at python.org
Wed Aug 24 12:49:24 EDT 2016
https://hg.python.org/cpython/rev/8d13c1f33d21
changeset: 102890:8d13c1f33d21
parent: 102887:b004da19b869
user: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: Wed Aug 24 17:49:15 2016 +0100
summary:
Closes #20124: clarified usage of the atTime parameter in TimedRotatingFileHandler documentation.
files:
Doc/library/logging.handlers.rst | 52 +++++++++++++------
1 files changed, 35 insertions(+), 17 deletions(-)
diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst
--- a/Doc/library/logging.handlers.rst
+++ b/Doc/library/logging.handlers.rst
@@ -327,21 +327,24 @@
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
@@ -369,7 +372,23 @@
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.
@@ -382,7 +401,6 @@
Does a rollover, as described above.
-
.. method:: emit(record)
Outputs the record to the file, catering for rollover as described above.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list