tracktable.core.timestamp module¶
Utility classes for position update data
-
class
tracktable.core.timestamp.
Timestamp
[source]¶ Bases:
object
Convenience 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 – 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 (string) – String containing your timestamp
- Kwargs:
format_string (string): 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
include_tz (boolean) – Whether or not to append a ‘+XXXX’ timezone offset
- 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
format_string (string) – String to pass to datetime.strftime() that describes format
include_tz – Whether or not to append timezone UTC offset
- 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
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.
- Returns
A new datetime imbued with the desired time zone