tracktable.core.timestamp module¶
Module contents¶
Utility classes for position update data
- class tracktable.core.timestamp.Timestamp[source]¶
Bases:
objectConvenience class that can convert from different formats to an ‘aware’ datetime
- BEGINNING_OF_TIME = datetime.datetime(1400, 1, 1, 0, 0)¶
- static beginning_of_time()[source]¶
Return a timestamp guaranteed to be before any legal data point
- Returns
Timestamp equal to January 1, 1400.
- static from_any(thing)[source]¶
Try to construct a timestamp from whatever we’re given.
The possible inputs can be:
a Python datetime (in which case we just return a copy of the input)
a string in the format ‘2013-04-05 11:23:45’, in which case we will assume that it resides in timestamp.DEFAULT_TIMEZONE
a string in the format ‘2013-04-05 11:23:45-05’, in which case we will assume that it’s UTC-5 (or other time zone, accordingly)
a string in the format ‘2013-04-05T11:23:45’ or ‘2013-04-05T11:23:45-05’ – just like above but with a T in the middle instead of a space
a string in the format ‘20130405112345’ - these are assumed to reside in timestamp.DEFAULT_TIMEZONE
a string in the format ‘MM-DD-YYYY HH:MM:SS’
a string such as ‘08-Aug-2013 12:34:45’ where ‘Aug’ is the abbreviated name for a month in your local environment
a dict containing at least ‘year’, ‘month’, ‘day’ entries and optionally ‘hour’, ‘minute’ and ‘second’ - these will always represent UTC times until I implement it otherwise
- Parameters
thing (Various) – String, datetime, or dict (see above)
- Returns
Timezone-aware datetime object
- static from_datetime(mytime)[source]¶
Convert a datetime to an aware timestamp
- Parameters
mytime (datetime) – Possibly-naive timestamp
- Returns
New datetime that will definitely have a time zone attached
- static from_dict(mydict)[source]¶
Construct a datetime from a dict with named elements.
- Parameters
mydict (dict) – Dict with zero or more of ‘hour’, ‘minute’, ‘second’, ‘year’, ‘month’, ‘day’, and ‘utc_offset’ entries. Missing entries will be set to their minimum legal values.
- Returns
- An aware datetime object imbued with tracktable.core.DEFAULT_TIMEZONE
unless a ‘utc_offset’ value is specified, in which case the specified time zone will be used instead.
- static from_string(timestring, format_string=None)[source]¶
Convert from a string to a datetime
Populate from a string such as ‘2012-09-10 12:34:56’ or ‘2012-09-10T12:34:56’. Note that you must have both a date and a time in that format or else the method will fail.
You can use a different format if you like but you will have to supply the ‘format_string’ argument. It will be passed to datetime.strptime. In Python 3 you can use the ‘%z’ directive to parse a time zone declaration – for example, ‘2017-06-01 12:34:56-0500’ is June 5, 2017 in UTC-5, aka the US east coast.
Note
Python 2.7 does not have the %z directive. You must use Python 3.4 or newer to get that.
- Parameters
timestring (str) – String containing your timestamp
- Keyword Arguments
format_string (str) – Format string for datetime.strptime
- Returns
An aware datetime object. By default this will be imbued with tracktable.core.timestamp.DEFAULT_TIMEZONE. If you used a format string with %z or %Z then you will get whatever time zone Python parsed.
- static from_struct_time(mytime)[source]¶
Construct a datetime from a time.struct_time object.
- Parameters
mytime (time.struct_time) – Source time
- Returns
An aware datetime object imbued with tracktable.core.timestamp.DEFAULT_TIMEZONE.
- static sanity_check(timestamp)[source]¶
Check to see whether a timestamp might be real
We assume that any timestamp after the year 1600 has a non-zero chance of being real and that anything before that is bogus.
- Parameters
timestamp (datetime) – Timestamp to check
- Returns
Timestamp argument if sane, None if not
- static to_iso_string(dt, include_tz=True)[source]¶
Convert a timestamp to a string in format YYYY-MM-DDTHH:MM:SS
- Parameters
dt (datetime) – Timezone-aware datetime object
- Keyword Arguments
include_tz (bool) – Whether or not to append a ‘+XXXX’ timezone offset (Default: True)
- Returns
String representation of the timestamp
- static to_string(dt, format_string='%Y-%m-%d %H:%M:%S', include_tz=True)[source]¶
Convert a datetime to a string
Format contents as a string, by default formatted as ‘2013-04-21 14:45:00’. You may supply an argument ‘format_string’ if you want it in a different form. See the documentation for datetime.strftime() for information on what this format string looks like.
- Parameters
dt (datetime) – Timestamp object to stringify
- Keyword Arguments
- Returns
String version of timestamp
- static truncate_to_day(orig_dt)[source]¶
Zero out the time portion of a timestamp
- Parameters
orig_dt (datetime) – Input datetime
- Returns
New timestamp with hours=0, minutes=0 and seconds=0
- static truncate_to_hour(orig_dt)[source]¶
Zero out the minutes and seconds in a timestamp
- Parameters
orig_dt (datetime) – Input datetime
- Returns
New timestamp with minutes=0 and seconds=0
- tracktable.core.timestamp.localize_timestamp(naive_ts, utc_offset=0)[source]¶
Imbue a naive timestamp with a timezone
Python has two kinds of timestamps: naive (just a datetime, no time zone) and aware (time plus time zone). Mixing the two is awkward. Thie routine will assign a time zone to a datetime (UTC by default) for consistency throughout Tracktable.
Note
You can change the default timezone by setting the module-level variable DEFAULT_TIMEZONE. This is not recommended.
- Parameters
naive_ts (datetime) – Timestamp to localize
- Keyword Arguments
utc_offset (integer) – Number of hours offset from UTC. You can also specify a fraction of an hour as ‘0530’, meaning 5 hours 30 minutes. (Default: 0)
- Returns
A new datetime imbued with the desired time zone