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.

It will use the monotonic pypi library to find an appropriate monotonically increasing time providing function (which typically varies depending on operating system and python version).

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 a RuntimeError when no duration has been set this call will return None 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.

See oslo_utils.fixture.TimeFixture.

oslo_utils.timeutils.advance_time_seconds(seconds)

Advance overridden time by seconds.

See oslo_utils.fixture.TimeFixture.

oslo_utils.timeutils.clear_time_override()

Remove the overridden time.

See oslo_utils.fixture.TimeFixture.

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.iso8601_from_timestamp(timestamp, microsecond=False)

Returns an iso8601 formatted date from timestamp.

Changed in version 1.3: Added optional microsecond parameter.

Deprecated since version 1.5.0: Use datetime.datetime.utcfromtimestamp() and datetime.datetime.isoformat() instead.

oslo_utils.timeutils.isotime(at=None, subsecond=False)

Stringify time in ISO 8601 format.

Deprecated since version 1.5.0: Use utcnow() and datetime.datetime.isoformat() instead.

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.strtime(at=None, fmt='%Y-%m-%dT%H:%M:%S.%f')

Returns formatted utcnow.

Deprecated since version 1.5.0: Use utcnow(), datetime.datetime.isoformat() or datetime.strftime() instead:

  • strtime() => utcnow().isoformat()

  • strtime(fmt=...) => utcnow().strftime(fmt)

  • strtime(at) => at.isoformat()

  • strtime(at, fmt) => at.strftime(fmt)

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 record

  • enabled – 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.