Note: This is supported from 0.3b2 and up.
As PSI gets many times from the system and needs to be able to offer these in a convenient form for Python developers we ended up making our own type to represent time. However it contains convenience functions to convert to most types of interest.
Internally PSI uses the POSIX
timespec to store any times. It is the most accurate time structure
available in POSIX and can represent both absolute time as well
relative time. This is not the most versatile time representation
possible, but is perfectly adequate for the time ranges and durations
a kernel will expose. Often, time information is even exposed as this
structure (or the slightly older and less accurate ``struct timeval``
Important to note is the the timespec structure does not contain any timezone information. If used as absolute time it is measured as seconds since the epoch, since the epoch is defined as 1 January 1970 Coordinated Universal Time (UTC) this means all times are in UTC and not local time.
TimeSpec class is used by PSI to represent any times,
whether absolute time or duration. It is essentially a tuple
representing the two values of the timespec structure as Python long
(tv_sec, tv_nsec), these two values are also available
tv_nsec attributes. Tuple-like access
to the attributes is limited to the index 0 and 1, negative indices
are not supported since
len() of a
TimeSpec is undefined.
Just like a tuple it is an immutable object.
Depending on the application these might not be convenient, therefore the object has the following methods to retrieve the time in different formats:
This returns a UNIX timestamp value of the time as a Python float. Equivalent of
t.tv_sec + t.tv_nsec/10.0**-9. If you wanted the integer timestamp just use the
.timestamp(), but this may be more natural when working with durations.
Return the time as a floating point, but converted to the local timezone. The returned time is not a UNIX or POSIX timestamp.
time.struct_timeinstance in UTC.
time.struct_timeinstance in the local timezone.
datetime.datetimeinstance representing the time in the local timezone. Note that the tzinfo of the datetime object will be unset.
datetime.datetimeinstance representing the time in UTC.
Note that when using Python 2.2 you don't have the
module available and hence the
.timedelta() methods will not be present.
On top of the above mentioned methods the TimeSpec class also supports part of the numeric protocol. It is possible to use a number of standard Python objects together with TimeSpec objects when using the numeric protocol. They are each converted on the fly for the operation, the result is always a TimeSpec object however.
When integers or floats are used they represent the seconds part of a timespec, the decimal part of a float counts towards the nanoseconds.
A 2-tuple of integers is accepted too. The first integer is treated as the seconds, the second integer as the nanoseconds.
Specifically these operations are supported:
You can compare with integers, floats and 2-tuples of integers. The numbers are interpreted as explained above.
You can add two TimsSpec objects together as well as add integers, floats and 2-tuples of integers.
Subtraction, same rules as for addition.
- Boolean Representation
If a TimeSpec value is
bool()will treat is as
False, otherwise it will be treated as
bool(). Bear in mind that a TimeSpec value could be negative too which is also
It is debatable if more of the numeric protocol should be defined.
Multiplication with an integer would be easily done for example. But
this might create more confusion then it's worth. Supporting
int() just like we support
be convenient too.