baldaquin.timeline — Time keeping#

The module provides the two basic data structures used by baldaquin to keep track of the time on the computer hosting the data acquisition: the Timeline and Timestamp objects.

A timeline is a simple object that keeps track of the date, time and the number of seconds elapsed since a fixed origin defined at creation time. It exposes a single public method Timeline.latch() that reads the system time at a given moment and returns the corresponding Timestamp object.

In order to avoid the pitfalls connected with using the local time (and the documentation of the pyzt package is a very entertaining reading in this respect), Timeline objects work internally in the UTC time zone, and the seconds field of a Timestamp object is always to be intended in UTC. That said, we recognize that the local time is often the most interesting piece of information when it comes to understanding when something happened in a specific place, and to this end Timestamp objects keep track internally of the local time, too. It’s just that local time isn’t that great to reconstruct an a absolute position in time unless one keeps track of a series of other things, such as the time zone and the daylight saving flag.

baldaquin tries and strike a sensible compromise between generality and simplicity, the basic usage ot the timeline objects being:

>>> from baldaquin.timeline import Timeline
>>>
>>> t = Timeline()
>>> timeline = Timeline()
>>> t1 = timeline.latch()
>>> print(t1)
2022-07-04 16:44:18.915834+02:00 (1656945858.915834 s)
>>> print(t1.utc_datetime)
2022-07-04 14:44:18.915834+00:00
>>> print(t1.local_datetime)
2022-07-04 16:44:18.915834+02:00
>>> print(t1.seconds)
1656945858.915834
>>> t2 = timeline.latch()
>>> t2 - t1
57.82228899002075

By default the Timeline origin is set to January 1, 1970 at 00:00:00 (UTC), in such a way that the seconds field of a Timestamp objects coincides with the familiar POSIX time. Setting the origin to a different value allow, e.g., to emulate the mission elapsed time (MET) concept that is common in space missions.

Warning

It is probably worth mentioning that all Timeline.latch() really does internally is the simple call

utc_datetime = datetime.datetime.now(datetime.timezone.utc)

and therefore one should not really expect the results to be accurate to 6 significant digits—results may vary depending of the OS and the configuration of the host computer. Nonetheless, the module should be more than adequate for book-keeping purposes.

Module documentation#

Time-related facilities.

class baldaquin.timeline.tzoffset(name: str, offset: float)[source]#

Minimal tzinfo class factory to create time-aware datetime objects.

See https://docs.python.org/3/library/datetime.html#datetime.tzinfo for more details.

Parameters:

  • name (str) – The tzinfo object name.

  • offset (float) – The UTC offset in seconds.

utcoffset(dt: datetime) → float[source]#

Overloaded method.

dst(dt: datetime) → float[source]#

Overloaded method.

According to the documentation, this Return the daylight saving time (DST) adjustment, as a timedelta object or None if DST information isn’t known.

tzname(dt: datetime) → str[source]#

Overloaded method.

class baldaquin.timeline.Timestamp(utc_datetime: datetime, local_datetime: datetime, seconds: float)[source]#

Small utility class to represent a timezone-aware timestamp.

A Timestamp encodes three basic pieces of information:

  • a datetime object in the UTC time zone;

  • a datetime object in the local time zone;

  • a timestamp in seconds, relative to the origin of the parent timeline.

Timestamp objects support subtraction aritmethics as a handy shortcut to calculate time differences.

Timestamp objects also support serialization/deserialization through the to_dict() and from_dict(), which, in turn, use internally a string conversion to ISO format. (datetime objects are implemented in C and therefore have no __dict__ slot.)

Parameters:

  • utc_datetime (datetime.datetime) – The (timezone-aware) UTC datetime object corresponding to the timestamp.

  • local_datetime (datetime.datetime) – The (timezone-aware) local datetime object corresponding to the timestamp.

  • seconds (float) – The seconds elapsed since the origin of the parent timeline.

utc_datetime: datetime#
local_datetime: datetime#
seconds: float#
_DATETIME_FIELDS = ('utc_datetime', 'local_datetime')#
to_dict() → dict[source]#

Serialization.

classmethod from_dict(**kwargs) → Timestamp[source]#

Deserialization.

class baldaquin.timeline.Timeline(origin: str = '1970-01-01')[source]#

Class representing a continuos timeline referred to a fixed origin.

Note that, by deafult, the origin of the Timeline is January 1, 1970 00:00:00 UTC, and the seconds field in the Timestamp objects that the Timeline returns when latched correspond to the standard POSIX time. Setting the origin to a different value allow, e.g., to emulate the mission elapsed time (MET) concept that is common in space missions.

Parameters:

origin (str) –

A string representation (in ISO 8601 format) of the date and time corresponding to the origin of the timeline in UTC (without the traling +00:00).

More specifically, according to the datetime documentation, we support strings in the format:

YYYY-MM-DD[*HH[:MM[:SS[.fff[fff]]]]

where * can match any single character.

_POSIX_ORIGIN = datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)#
static _utc_offset() → int[source]#

Return the local UTC offset in s, considering the DST—note this has to be calculated every time the timeline is latched, as one doesn’t know if a DST change has happened between two successive calls.

See https://stackoverflow.com/questions/3168096 for more details on why this is a sensible way to calculate this.

latch() → Timestamp[source]#

This is the workhorse function for keeping track of the time.

This function latches the system time and creates a frozen Timestamp object that can be reused at later time.