module `tarantool.msgpack_ext.types`¶

module `tarantool.msgpack_ext.types.datetime`¶

Tarantool datetime extension type implementation module.

class tarantool.msgpack_ext.types.datetime.Datetime(*, timestamp=None, year=None, month=None, day=None, hour=None, minute=None, sec=None, nsec=None, tzoffset=0, tz='', timestamp_since_utc_epoch=False)¶

Class representing Tarantool datetime info. Internals are based on pandas.Timestamp.

You can create Datetime objects by using the same API as in Tarantool:

dt1 = tarantool.Datetime(year=2022, month=8, day=31,
                         hour=18, minute=7, sec=54,
                         nsec=308543321)

dt2 = tarantool.Datetime(timestamp=1661969274)

dt3 = tarantool.Datetime(timestamp=1661969274, nsec=308543321)

Datetime exposes year, month, day, hour, minute, sec, nsec, timestamp and value (integer epoch time with nanoseconds precision) properties if you need to convert Datetime to any other kind of datetime object:

pdt = pandas.Timestamp(year=dt.year, month=dt.month, day=dt.day,
                       hour=dt.hour, minute=dt.minute, second=dt.sec,
                       microsecond=(dt.nsec // 1000),
                       nanosecond=(dt.nsec % 1000))

Use tzoffset parameter to set up offset timezone:

dt = tarantool.Datetime(year=2022, month=8, day=31,
                        hour=18, minute=7, sec=54,
                        nsec=308543321, tzoffset=180)

You may use the tzoffset property to get the timezone offset of a datetime object.

Use tz parameter to set up timezone name:

dt = tarantool.Datetime(year=2022, month=8, day=31,
                        hour=18, minute=7, sec=54,
                        nsec=308543321, tz='Europe/Moscow')

If both tz and tzoffset are specified, tz is used.

You may use the tz property to get the timezone name of a datetime object.

Parameters

timestamp¶ (float or int, optional) – Timestamp since epoch. Cannot be provided together with year, month, day, hour, minute, sec. If nsec is provided, it must be int. Refer to timestamp_since_utc_epoch to clarify how timezone-aware datetime is computed from the timestamp.
year¶ (int, optional) – Datetime year value. Must be a valid pandas.Timestamp year parameter. Must be provided unless the object is built with data or timestamp.
month¶ (int, optional) – Datetime month value. Must be a valid pandas.Timestamp month parameter. Must be provided unless the object is built with data or timestamp.
day¶ (int, optional) – Datetime day value. Must be a valid pandas.Timestamp day parameter. Must be provided unless the object is built with data or timestamp.
hour¶ (int, optional) – Datetime hour value. Must be a valid pandas.Timestamp hour parameter.
minute¶ (int, optional) – Datetime minute value. Must be a valid pandas.Timestamp minute parameter.
sec¶ (int, optional) – Datetime seconds value. Must be a valid pandas.Timestamp second parameter.
nsec¶ – Datetime nanoseconds value. Quotient of a division by 1000 (nanoseconds in microseconds) must be a valid pandas.Timestamp microsecond parameter, remainder of a division by 1000 must be a valid pandas.Timestamp nanosecond parameter.
tzoffset¶ (int, optional) – Timezone offset. Ignored, if provided together with tz.
tz¶ (str, optional) – Timezone name from Olson timezone database.

timestamp_since_utc_epoch¶ (bool, optional) –

Parameter to set timestamp convertion behavior for timezone-aware datetimes.

If False (default), behaves similar to Tarantool datetime.new():

>>> dt = tarantool.Datetime(timestamp=1640995200, timestamp_since_utc_epoch=False)
>>> dt
datetime: Timestamp('2022-01-01 00:00:00'), tz: ""
>>> dt.timestamp
1640995200.0
>>> dt = tarantool.Datetime(timestamp=1640995200, tz='Europe/Moscow',
...                         timestamp_since_utc_epoch=False)
>>> dt
datetime: Timestamp('2022-01-01 00:00:00+0300', tz='Europe/Moscow'), tz: "Europe/Moscow"
>>> dt.timestamp
1640984400.0

Thus, if False, datetime is computed from timestamp since epoch and then timezone is applied without any convertion. In that case, timestamp won’t be equal to initialization timestamp for all timezones with non-zero offset.

If True, behaves similar to pandas.Timestamp:

>>> dt = tarantool.Datetime(timestamp=1640995200, timestamp_since_utc_epoch=True)
>>> dt
datetime: Timestamp('2022-01-01 00:00:00'), tz: ""
>>> dt.timestamp
1640995200.0
>>> dt = tarantool.Datetime(timestamp=1640995200, tz='Europe/Moscow',
...                         timestamp_since_utc_epoch=True)
>>> dt
datetime: Timestamp('2022-01-01 03:00:00+0300', tz='Europe/Moscow'), tz: "Europe/Moscow"
>>> dt.timestamp
1640995200.0

Thus, if True, datetime is computed in a way that timestamp will always be equal to initialization timestamp.

Raise

ValueError, MsgpackError, pandas.Timestamp exceptions

__add__(other)¶

Valid operations:

Datetime + Interval = Datetime

Since Interval could contain month and year fields and such operations could be ambiguous, you can use the adjust field to tune the logic. The behavior is the same as in Tarantool, see Interval arithmetic RFC.

tarantool.IntervalAdjust.NONE – only truncation toward the end of month is performed (default mode).

>>> dt = tarantool.Datetime(year=2022, month=3, day=31)
datetime: Timestamp('2022-03-31 00:00:00'), tz: ""
>>> di = tarantool.Interval(month=1, adjust=tarantool.IntervalAdjust.NONE)
>>> dt + di
datetime: Timestamp('2022-04-30 00:00:00'), tz: ""

tarantool.IntervalAdjust.EXCESS – overflow mode, without any snap or truncation to the end of month, straight addition of days in month, stopping over month boundaries if there is less number of days.

>>> dt = tarantool.Datetime(year=2022, month=1, day=31)
datetime: Timestamp('2022-01-31 00:00:00'), tz: ""
>>> di = tarantool.Interval(month=1, adjust=tarantool.IntervalAdjust.EXCESS)
>>> dt + di
datetime: Timestamp('2022-03-02 00:00:00'), tz: ""

tarantool.IntervalAdjust.LAST – mode when day snaps to the end of month, if it happens.

>>> dt = tarantool.Datetime(year=2022, month=2, day=28)
datetime: Timestamp('2022-02-28 00:00:00'), tz: ""
>>> di = tarantool.Interval(month=1, adjust=tarantool.IntervalAdjust.LAST)
>>> dt + di
datetime: Timestamp('2022-03-31 00:00:00'), tz: ""

Parameters: other¶ (Interval) – Second operand.
Return type: Datetime
Raise: TypeError

__eq__(other)¶

Datetimes are equal when underlying datetime infos are equal.

Parameters: other¶ (Datetime or Timestamp) – Second operand.
Return type: bool

__sub__(other)¶

Valid operations:

Datetime - Interval = Datetime
Datetime - Datetime = Interval

Refer to __add__() for interval adjustment rules.

Parameters: other¶ (Interval or Datetime) – Second operand.
Return type: Datetime or Interval
Raise: TypeError

property day¶

Datetime day.

Return type: int

property hour¶

Datetime day.

Return type: int

property minute¶

Datetime minute.

Return type: int

property month¶

Datetime month.

Return type: int

property nsec¶

Datetime nanoseconds (everything less than seconds is included).

Return type: int

property sec¶

Datetime seconds.

Return type: int

property timestamp¶

Datetime time since epoch, in seconds.

Return type: float

property tz¶

Datetime timezone name.

Return type: str

property tzoffset¶

Datetime current timezone offset.

Return type: int

property value¶

Datetime time since epoch, in nanoseconds.

Return type: int

property year¶

Datetime year.

Return type: int