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).
- 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.