FlyScript Documentation

Version 0.6.1 - last updated May 01, 2014 at 01:05 PM

rvbd.common.timeutils

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

Handling time zones

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.

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.

Conversions

The Shark and Profiler APIs often represesent time as seconds (or microseconds or nanoseconds) since the Unix epoch (January 1, 1970). Many of the methods on Shark objects and Profiler objects accept datetime.datetime objects but if you need to work with the raw numbers, these routines may be useful:

datetime_to_seconds(dt)

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

datetime_to_microseconds(dt)

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

datetime_to_nanoseconds(dt)

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

usec_string_to_datetime(s)

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

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

usec_string_to_timedelta(s)

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

timedelta_total_seconds(td)

Handle backwards compatability for timedelta.total_seconds.

Parsing dates and times

class rvbd.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.

TimeParser()

Construct a new TimeParser object

parse(s)

Parse the string s as a date and time. Returns a datetime.datetime object on success or raises ValueError if the string cannot be parsed.

parse_one(s)

do a "one-shot" parsing of string s as a date/time. doesn't remember anything about the format that was used.

Parsing time ranges

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.

parse_range(s)

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.