Datetime API

Parsers

dt

ptr.datetime.dt(time) → datetime.datetime

Datetime parser.

td

ptr.datetime.td(delta) → datetime.timedelta

Time delta parser.

Example: 7 day, 12:34:56.789 for 7 days, 12 hours, 34 minutes, 56 secondes and 789 milliseconds.

We recommend to use this formatting but you can provide explicit units following the rules below:

Valid units:

• ms, msec, millisecond

• s, sec, second

• m, min, minute

• h, hr, hour

• d, D, day

Plural units are also valid.

Space between the value and the units is accepted.

Month(s) and year(s) are not accepted.

If a int or a float is provide, it is assume that the value is express in secondes.

Raises

ValueError – If the provided value format is invalid.

Elements

Time

class ptr.Time(time)

Bases: ptr.datetime.time.WithTime

Generic Time object.

property datetime: datetime.datetime

Datetime value.

edit(value)

Edit time value.

StartTime

class ptr.datetime.StartTime(time, description=None)

Bases: ptr.datetime.time.ElementTime

PTR start ElementTime element.

Parameters

• time (str, datetime.datetime or numpy.datetime64) – Element start time.

• description (str or list, optional) – Element description, put as a xml-comment on top of the element.

EndTime

class ptr.datetime.EndTime(time, description=None)

Bases: ptr.datetime.time.ElementTime

PTR end time element.

Parameters

• time (str, datetime.datetime or numpy.datetime64) – Element end time.

• description (str or list, optional) – Element description, put as a xml-comment on top of the element.

ElementTime

class ptr.datetime.time.ElementTime(tag, time, description=None)

Bases: ptr.datetime.time.WithTime, ptr.element.Element

Time element.

Parameters

• tag (str) – Element tag name.

• time (str, datetime.datetime or numpy.datetime64) – Element time.

• description (str or list, optional) – Element description, put as a xml-comment on top of the element.

Note

The element is parsed as a native datetime.datetime object, and display in XML in ISO format: YYYY-MM-DDThh:mm:ss.

property datetime: datetime.datetime

Datetime value.

edit(value)

Edit time value.

WithTime

class ptr.datetime.time.WithTime

Bases: object

Add Time properties to Element objects.

property datetime: datetime.datetime

Datetime value.

edit(value)

Edit time value.

property date

Date value.

property time

Time value.

property iso

ISO formatted datetime.

item() → <property object at 0x7fbe5aef6040>

Datetime value (numpy-like).

offset(offset)

Shift time value.

ElementWindow

class ptr.datetime.window.ElementWindow(tag, start, end, *elements, **attrs)

Bases: ptr.element.Element, ptr.datetime.window.WithDatetimeWindow

Element with datetime window properties.

WithDatetimeWindow

class ptr.datetime.window.WithDatetimeWindow

Bases: object

Add Time window properties to Element objects.

property start: ptr.datetime.time.StartTime

Time window start time value.

property end: ptr.datetime.time.EndTime

Time window end time value.

property window

Time window start and end time values.

set_window(start, end)

Set time window boundaries.

property duration

Block duration.

append(element)

Append a new element or text/numeric value.

copy()

Element deep copy.

edit(*, start=None, end=None)

Edit temporal window boundaries.

Parameters

• start (str, datetime.datetime or datetime.timedelta) – Start time absolute or relative offset.

• end (str, datetime.datetime or datetime.timedelta) – End time absolute or relative offset.

Raises

• ValueError – If the new start time is after the end time.

• ValueError – If the new end time is before the start time.

Warning

This operation change the duration of the temporal window.

offset(offset, *, ref='start')

Offset the temporal window globally.

Parameters

• offset (str datetime.timedelta or datetime.datetime) – Global or relative offset.

• ref (str, optional) – Boundary reference for relative offset. Only start|end|center are accepted

Raises

KeyError – If the reference keyword is invalid.

Note

This operation does not change the duration of the window.

split(time, *, gap=None, ref='start')

Split the temporal window in two windows.

Parameters

• time (str or datetime.datetime) – Splitting datetime.

• gap (str, optional) – Time delta gap between the windows.

• ref (str, optional) – Reference location of the gap with respect to provided time. Only start|end|center are accepted

Returns

Two copy of the original element in each time window.

Return type

WithDatetimeWindow, WithDatetimeWindow

Raises

• KeyError – If the reference keyword is invalid.

• ValueError – If the gap is too large for the window.

Warning

This operation change the duration of the temporal window.