timeutils¶
Time related utilities and helper functions.
-
class
oslo_utils.timeutils.
Split
(elapsed, length)¶ A immutable stopwatch split.
See: http://en.wikipedia.org/wiki/Stopwatch for what this is/represents.
New in version 1.4.
-
property
elapsed
¶ Duration from stopwatch start.
-
property
length
¶ Seconds from last split (or the elapsed time if no prior split).
-
property
-
class
oslo_utils.timeutils.
StopWatch
(duration=None)¶ A simple timer/stopwatch helper class.
Inspired by: apache-commons-lang java stopwatch.
Not thread-safe (when a single watch is mutated by multiple threads at the same time). Thread-safe when used by a single thread (not shared) or when operations are performed in a thread-safe manner on these objects by wrapping those operations with locks.
New in version 1.4.
-
__enter__
()¶ Starts the watch.
-
__exit__
(type, value, traceback)¶ Stops the watch (ignoring errors if stop fails).
-
elapsed
(maximum=None)¶ Returns how many seconds have elapsed.
-
expired
()¶ Returns if the watch has expired (ie, duration provided elapsed).
-
has_started
()¶ Returns True if the watch is in a started state.
-
has_stopped
()¶ Returns True if the watch is in a stopped state.
-
leftover
(return_none=False)¶ Returns how many seconds are left until the watch expires.
- Parameters
return_none (boolean) – when
True
instead of raising aRuntimeError
when no duration has been set this call will returnNone
instead.
-
restart
()¶ Restarts the watch from a started/stopped state.
-
resume
()¶ Resumes the watch from a stopped state.
-
split
()¶ Captures a split/elapsed since start time (and doesn’t stop).
-
property
splits
¶ Accessor to all/any splits that have been captured.
-
start
()¶ Starts the watch (if not already started).
NOTE(harlowja): resets any splits previously captured (if any).
-
stop
()¶ Stops the watch.
-
-
oslo_utils.timeutils.
advance_time_delta
(timedelta)¶ Advance overridden time using a datetime.timedelta.
-
oslo_utils.timeutils.
advance_time_seconds
(seconds)¶ Advance overridden time by seconds.
-
oslo_utils.timeutils.
clear_time_override
()¶ Remove the overridden time.
-
oslo_utils.timeutils.
delta_seconds
(before, after)¶ Return the difference between two timing objects.
Compute the difference in seconds between two date, time, or datetime objects (as a float, to microsecond resolution).
-
oslo_utils.timeutils.
is_newer_than
(after, seconds)¶ Return True if after is newer than seconds.
Changed in version 1.7: Accept datetime string with timezone information. Fix comparison with timezone aware datetime.
-
oslo_utils.timeutils.
is_older_than
(before, seconds)¶ Return True if before is older than seconds.
Changed in version 1.7: Accept datetime string with timezone information. Fix comparison with timezone aware datetime.
-
oslo_utils.timeutils.
is_soon
(dt, window)¶ Determines if time is going to happen in the next window seconds.
- Parameters
dt – the time
window – minimum seconds to remain to consider the time not soon
- Returns
True if expiration is within the given duration
-
oslo_utils.timeutils.
marshall_now
(now=None)¶ Make an rpc-safe datetime with microseconds.
Changed in version 1.6: Timezone information is now serialized instead of being stripped.
-
oslo_utils.timeutils.
normalize_time
(timestamp)¶ Normalize time in arbitrary timezone to UTC naive object.
-
oslo_utils.timeutils.
parse_isotime
(timestr)¶ Parse time from ISO 8601 format.
-
oslo_utils.timeutils.
parse_strtime
(timestr, fmt='%Y-%m-%dT%H:%M:%S.%f')¶ Turn a formatted time back into a datetime.
-
oslo_utils.timeutils.
set_time_override
(override_time=None)¶ Overrides utils.utcnow.
Make it return a constant time or a list thereof, one at a time.
See
oslo_utils.fixture.TimeFixture
.- Parameters
override_time – datetime instance or list thereof. If not given, defaults to the current UTC time.
-
oslo_utils.timeutils.
time_it
(logger, log_level=10, message="It took %(seconds).02f seconds to run function '%(func_name)s'", enabled=True, min_duration=0.01)¶ Decorator that will log how long its decorated function takes to run.
This does not output a log if the decorated function fails with an exception.
- Parameters
logger – logger instance to use when logging elapsed time
log_level – logger logging level to use when logging elapsed time
message – customized message to use when logging elapsed time, the message may use automatically provide values
%(seconds)
and%(func_name)
if it finds those values useful to recordenabled – whether to enable or disable this decorator (useful to decorate a function with this decorator, and then easily be able to switch that decoration off by some config or other value)
min_duration – argument that determines if logging is triggered or not, it is by default set to 0.01 seconds to avoid logging when durations and/or elapsed function call times are less than 0.01 seconds, to disable any
min_duration
checks this value should be set to less than or equal to zero or set to none
-
oslo_utils.timeutils.
unmarshall_time
(tyme)¶ Unmarshall a datetime dict.
Changed in version 1.5: Drop leap second.
Changed in version 1.6: Added support for timezone information.
-
oslo_utils.timeutils.
utcnow
(with_timezone=False)¶ Overridable version of utils.utcnow that can return a TZ-aware datetime.
See
oslo_utils.fixture.TimeFixture
.Changed in version 1.6: Added with_timezone parameter.
-
oslo_utils.timeutils.
utcnow_ts
(microsecond=False)¶ Timestamp version of our utcnow function.
See
oslo_utils.fixture.TimeFixture
.Changed in version 1.3: Added optional microsecond parameter.