3.2. steelscript.common.timeutils

This module contains a number of utilities for working with dates and times, in conjunction with the python datetime module.

3.2.1. Timezone Handling

steelscript.common.timeutils.ensure_timezone(dt)

Return a datetime object that corresponds to dt but that always has timezone info.

If dt already has timezone info, then it is simply returned. If dt does not have timezone info, then the local time zone is assumed.

steelscript.common.timeutils.force_to_utc(dt)

Return a datetime object that corresponds to dt but in UTC rather than local time.

If dt includes timezone info, then this routine simply converts from the given timezone to UTC. If dt does not include timezone info, then it is assumed to be in local time, which is then converted to UTC.

3.2.2. Conversions

Devices often represent time as seconds (or microseconds or nanoseconds) since the Unix epoch (January 1, 1970). The following functions are useful for converting to and from native Python datetime.datetime objects:

steelscript.common.timeutils.datetime_to_seconds(dt)

Return the number of seconds since the Unix epoch for the datetime object dt.

steelscript.common.timeutils.datetime_to_microseconds(dt)

Return the number of microseconds since the Unix epoch for the datetime object dt.

steelscript.common.timeutils.datetime_to_nanoseconds(dt)

Return the number of nanoseconds since the Unix epoch for the datetime object dt.

steelscript.common.timeutils.usec_string_to_datetime(s)

Convert the string s which represents a time in microseconds since the Unix epoch to a datetime object.

steelscript.common.timeutils.nsec_to_datetime(ns)

Convert the value ns which represents a time in nanoseconds since the Unix epoch (either as an integer or a string) to a datetime object.

steelscript.common.timeutils.usec_string_to_timedelta(s)

Convert the string s which represents a number of microseconds to a timedelta object.

steelscript.common.timeutils.timedelta_total_seconds(td)

Handle backwards compatibility for timedelta.total_seconds.

3.2.3. Parsing dates and times

class steelscript.common.timeutils.TimeParser

Instances of this class parse strings representing dates and/or times into python datetime.datetime objects.

This class is capable of parsing a variety of different formats. On the first call, the method parse() may take some time, as it tries a series of pre-defined formats one after another. After successfully parsing a string, the parser object remembers the format that was used so subsequent calls with identically formatted strings are as efficient as the underlying method datetime.strptime.

3.2.4. Parsing time ranges

steelscript.common.timeutils.parse_timedelta(s)

Parse the string s representing some duration of time (e.g., “3 seconds” or “1 week”) and return a datetime.timedelta object representing that length of time.

If the string cannot be parsed, raises ValueError.

steelscript.common.timeutils.parse_range(s, begin_monday=False)

Parse the string s representing a range of times (e.g., “12:00 PM to 1:00 PM” or “last 2 weeks”).

Upon success returns a pair of datetime.datetime objects representing the beginning and end of the time range. If the string cannot be parsed, raises ValueError.