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 datetime.datetime.

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 datetime.datetime year parameter. Must be provided unless the object is built with data or timestamp.

  • month (int, optional) – Datetime month value. Must be a valid datetime.datetime month parameter. Must be provided unless the object is built with data or timestamp.

  • day (int, optional) – Datetime day value. Must be a valid datetime.datetime day parameter. Must be provided unless the object is built with data or timestamp.

  • hour (int, optional) – Datetime hour value. Must be a valid datetime.datetime hour parameter.

  • minute (int, optional) – Datetime minute value. Must be a valid datetime.datetime minute parameter.

  • sec (int, optional) – Datetime seconds value. Must be a valid datetime.datetime second parameter.

  • nsec – Datetime nanoseconds value.

  • 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 conversion 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 conversion. In that case, timestamp won’t be equal to initialization timestamp for all timezones with non-zero offset.

    If True, behaves similar to datetime.datetime:

    >>> 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, datetime.datetime exceptions

__add__(other)

Valid operations:

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) – Second operand.

Return type

bool

__sub__(other)

Valid operations:

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

module tarantool.msgpack_ext.types.interval

Tarantool datetime.interval extension type implementation module.

class tarantool.msgpack_ext.types.interval.Adjust(value)

Interval adjustment mode for year and month arithmetic. Refer to __add__().

EXCESS = 0

Overflow mode.

LAST = 2

Mode when day snaps to the end of month, if it happens.

NONE = 1

Only truncation toward the end of month is performed.

class tarantool.msgpack_ext.types.interval.Interval(*, year=0, month=0, week=0, day=0, hour=0, minute=0, sec=0, nsec=0, adjust=Adjust.NONE)

Class representing Tarantool datetime.interval info.

You can create Interval objects either from MessagePack data or by using the same API as in Tarantool:

di = tarantool.Interval(year=-1, month=2, day=3,
                        hour=4, minute=-5, sec=6,
                        nsec=308543321,
                        adjust=tarantool.IntervalAdjust.NONE)

Its attributes (same as in init API) are exposed, so you can use them if needed.

Parameters
  • year (int, optional) – Interval year value.

  • month (int, optional) – Interval month value.

  • week (int, optional) – Interval week value.

  • day (int, optional) – Interval day value.

  • hour (int, optional) – Interval hour value.

  • minute (int, optional) – Interval minute value.

  • sec (int, optional) – Interval seconds value.

  • nsec (int, optional) – Interval nanoseconds value.

  • adjust (IntervalAdjust, optional) – Interval adjustment rule. Refer to __add__().

__add__(other)

Valid operations:

Adjust of the first operand is used in result.

Parameters

other (Interval) – Second operand.

Return type

Interval

Raise

TypeError

__eq__(other)

Compare equality of each field, no casts.

Parameters

other (Interval) – Second operand.

Return type

bool

__sub__(other)

Valid operations:

Adjust of the first operand is used in result.

Parameters

other (Interval) – Second operand.

Return type

Interval

Raise

TypeError