deephaven.time

This module defines functions for handling Deephaven date/time data.

DAY = 86400000000000

One day in nanoseconds.

HOUR = 3600000000000

One hour in nanoseconds.

MINUTE = 60000000000

One minute in nanoseconds.

SECOND = 1000000000

One second in nanoseconds.

class TimeZone(value)[source]

Bases: enum.Enum

A Enum for known time zones.

AL = io.deephaven.time.TimeZone(objectRef=0x331c3a8)

America/Anchorage

AT = io.deephaven.time.TimeZone(objectRef=0x331c398)

Canada/Atlantic

BT = io.deephaven.time.TimeZone(objectRef=0x32cd0b8)

America/Sao_Paulo

CE = io.deephaven.time.TimeZone(objectRef=0x331c3b8)

Europe/Berlin

CH = io.deephaven.time.TimeZone(objectRef=0x331c3e0)

Europe/Zurich

CT = io.deephaven.time.TimeZone(objectRef=0x32cd098)

America/Chicago

ET = io.deephaven.time.TimeZone(objectRef=0x32cd088)

America/New_York

HI = io.deephaven.time.TimeZone(objectRef=0x32cd0b0)

Pacific/Honolulu

HK = io.deephaven.time.TimeZone(objectRef=0x331c388)

Asia/Hong_Kong

IN = io.deephaven.time.TimeZone(objectRef=0x331c3b0)

Asia/Kolkata

JP = io.deephaven.time.TimeZone(objectRef=0x331c390)

Asia/Tokyo

KR = io.deephaven.time.TimeZone(objectRef=0x331c380)

Asia/Seoul

LON = io.deephaven.time.TimeZone(objectRef=0x331c3c8)

Europe/London

MN = io.deephaven.time.TimeZone(objectRef=0x32cd090)

America/Chicago

MOS = io.deephaven.time.TimeZone(objectRef=0x331c3d0)

Europe/Moscow

MT = io.deephaven.time.TimeZone(objectRef=0x32cd0a0)

America/Denver

NF = io.deephaven.time.TimeZone(objectRef=0x331c3a0)

Canada/Newfoundland

NL = io.deephaven.time.TimeZone(objectRef=0x331c3e8)

Europe/Amsterdam

NY = io.deephaven.time.TimeZone(objectRef=0x32cd080)

America/New_York

PT = io.deephaven.time.TimeZone(objectRef=0x32cd0a8)

America/Los_Angeles

SG = io.deephaven.time.TimeZone(objectRef=0x331c3c0)

Asia/Singapore

SHG = io.deephaven.time.TimeZone(objectRef=0x331c3d8)

Asia/Shanghai

SYD = io.deephaven.time.TimeZone(objectRef=0x331c3f8)

Australia/Sydney

TW = io.deephaven.time.TimeZone(objectRef=0x331c3f0)

Asia/Taipei

UTC = io.deephaven.time.TimeZone(objectRef=0x331c400)

UTC

static get_default_timezone()[source]

Gets the default time zone.

Return type

TimeZone

static set_default_timezone(tz)[source]

Sets the default time zone.

Parameters

tz (TimeZone) – the TimeZone to use as default

Return type

None

WEEK = 604800000000000

One week in nanoseconds.

YEAR = 31449600000000000

One year in nanoseconds.

datetime_at_midnight(dt, tz)[source]

Returns a DateTime for the requested DateTime at midnight in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which the new value at midnight should be calculated

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Return type

DType

Returns

DateTime

Raises

DHError

day_of_month(dt, tz)[source]

Returns an 1-based int value of the day of the month for a DateTime and specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the day of the month

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

day_of_week(dt, tz)[source]
Returns an 1-based int value of the day of the week for a DateTime in the specified time zone, with 1 being

Monday and 7 being Sunday.

Parameters
  • dt (DateTime) – the DateTime for which to find the day of the week.

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime.

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

day_of_year(dt, tz)[source]

Returns an 1-based int value of the day of the year (Julian date) for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the day of the year

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

diff_nanos(dt1, dt2)[source]

Returns the difference in nanoseconds between two DateTime values.

Parameters
  • dt1 (DateTime) – the 1st DateTime

  • dt2 (DateTime) – the 2nd DateTime

Returns

NULL_LONG if either dt1 or dt2 is None

Return type

int

Raises

DHError

format_date(dt, tz)[source]

Returns a string date representation of a DateTime interpreted for a specified time zone formatted as “yyy-MM-dd”.

Parameters
  • dt (DateTime) – the DateTime to format

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Return type

str

Returns

str

Raises

DHError

format_datetime(dt, tz)[source]

Returns a string DateTime representation formatted as “yyyy-MM-ddThh:mm:ss.SSSSSSSSS TZ”.

Parameters
  • dt (DateTime) – the DateTime to format as a string

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Return type

str

Returns

str

Raises

DHError

format_nanos(ns)[source]

Returns a string DateTime representation formatted as “yyyy-MM-ddThh:mm:ss.SSSSSSSSS”.

Parameters

ns (int) – the number of nanoseconds

Return type

str

Returns

str

Raises

DHError

hour_of_day(dt, tz)[source]

Returns the hour of the day for a DateTime in the specified time zone. The hour is on a 24 hour clock (0 - 23).

Parameters
  • dt (DateTime) – the DateTime for which to find the hour of the day

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

is_after(dt1, dt2)[source]

Evaluates whether one DateTime value is later than a second DateTime value.

Parameters
  • dt1 (DateTime) – the 1st DateTime

  • dt2 (DateTime) – the 2nd DateTime

Return type

bool

Returns

bool

Raises

DHError

is_before(dt1, dt2)[source]

Evaluates whether one DateTime value is before a second DateTime value.

Parameters
  • dt1 (DateTime) – the 1st DateTime

  • dt2 (DateTime) – the 2nd DateTime

Return type

bool

Returns

bool

Raises

DHError

lower_bin(dt, interval, offset=0)[source]
Returns a DateTime value, which is at the starting (lower) end of a time range defined by the interval

nanoseconds. For example, a 5*MINUTE intervalNanos value would return the DateTime value for the start of the five minute window that contains the input date time.

Parameters
  • dt (DateTime) – the DateTime for which to evaluate the start of the containing window

  • interval (int) – the size of the window in nanoseconds

  • offset (int) – the window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute. Default is 0

Return type

DType

Returns

DateTime

Raises

DHError

millis(dt)[source]

Returns milliseconds since Epoch for a DateTime value.

Parameters

dt (DateTime) – the DateTime for which the milliseconds offset should be returned

Returns

NULL_LONG if dt is None

Return type

int

Raises

DHError

millis_of_day(dt, tz)[source]

Returns the number of milliseconds since midnight for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the milliseconds since midnight

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

millis_of_second(dt, tz)[source]

Returns the number of milliseconds since the top of the second for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the milliseconds

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

millis_to_datetime(ms)[source]

Converts a value of milliseconds from Epoch in the UTC time zone to a DateTime.

Parameters

ms (int) – the milliseconds value to convert

Return type

DType

Returns

DateTime

Raises

DHError

millis_to_nanos(ms)[source]

Converts milliseconds to nanoseconds.

Parameters

ms (int) – the milliseconds value to convert

Returns

NULL_LONG if ms is NULL_LONG

Return type

int

Raises

DHError

minus(dt1, dt2)[source]

Subtracts one time from another, returns the difference in nanos.

Parameters
  • dt1 (DateTime) – the 1st DateTime

  • dt2 (DateTiem) – the 2nd DateTime

Returns

NULL_LONG if either dt1 or dt2 is None

Return type

int

Raises

DHError

minus_nanos(dt, ns)[source]

Subtracts nanoseconds from a DateTime.

Parameters
  • dt (DateTime) – the starting DateTime value

  • ns (int) – the number of nanoseconds to subtract from dateTime

Return type

DType

Returns

DateTime

Raises

DHError

minus_period(dt, period)[source]

Subtracts a period from a DateTime.

Parameters
  • dt (DateTime) – the starting DateTime value

  • period (Period) – the Period to subtract from dateTime

Return type

DType

Returns

DateTime

Raises

DHError

minute_of_day(dt, tz)[source]

Returns the number of minutes since midnight for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the minutes

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

minute_of_hour(dt, tz)[source]

Returns the number of minutes since the top of the hour for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the minutes

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

month_of_year(dt, tz)[source]

Returns an 1-based int value for the month of a DateTime in the specified time zone. January is 1, and December is 12.

Parameters
  • dt (DateTime) – the DateTime for which to find the month

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

nanos(dt)[source]

Returns nanoseconds since Epoch for a DateTime value.

Parameters

dt (DateTime) – the DateTime for which the nanoseconds offset should be returned

Returns

NULL_LONG if dt is None

Return type

int

Raises

DHError

nanos_of_day(dt, tz)[source]

Returns the number of nanoseconds since midnight for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the nanoseconds since midnight

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_LONG if dt is None

Return type

int

Raises

DHError

nanos_of_second(dt, tz)[source]

Returns the number of nanoseconds since the top of the second for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the nanoseconds

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_LONG if dt is None

Return type

int

Raises

DHError

nanos_to_datetime(ns)[source]

Converts a value of nanoseconds from Epoch to a DateTime.

Parameters

ns (long) – the long nanoseconds since Epoch value to convert

Return type

DType

Returns

DateTime

nanos_to_millis(ns)[source]

Converts nanoseconds to milliseconds.

Parameters

ns (int) – the value of nanoseconds to convert

Returns

NULL_LONG if ns is NULL_LONG

Return type

int

Raises

DHError

now()[source]

Provides the current datetime.

Return type

DType

Returns

DateTime

Raises

DHError

plus_nanos(dt, ns)[source]

Adds nanoseconds to a DateTime.

Parameters
  • dt (DateTime) – the starting DateTime value

  • ns (int) – the number of nanoseconds to add to DateTime

Returns

None if dt is None or ns is NULL_LONG

Return type

DateTime

Raises

DHError

plus_period(dt, period)[source]

Adds a period to a DateTime.

Parameters
  • dt (DateTime) – the starting DateTime value

  • period (Period) – the Period to add to the DateTime

Returns

None if either dt or period is None

Return type

DateTime

Raises

DHError

second_of_day(dt, tz)[source]

Returns the number of seconds since midnight for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the seconds

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

second_of_minute(dt, tz)[source]

Returns the number of seconds since the top of the minute for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the seconds

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

to_datetime(s, quiet=False)[source]

Converts a datetime string to a DateTime object.

Supports ISO 8601 format and others.

Parameters
  • s (str) – in the form of ISO 8601 or “yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ”

  • quiet (bool) – when True, if the datetime string can’t be parsed, this function returns None, otherwise it raises an exception. The default is False

Return type

DType

Returns

a DateTime

Raises

DHError

to_nanos(s, quiet=False)[source]

Converts a time string to nanoseconds.

Parameters
  • s (str) – in the format of: hh:mm:ss[.SSSSSSSSS]

  • quiet (bool) – to return None or raise an exception if the string can’t be parsed, default is False

Return type

int

Returns

int

Raises

DHError

to_period(s, quiet=False)[source]

Converts a period string into a Period object.

Parameters
  • s (str) – a string in the form of nYnMnWnDTnHnMnS, with n being numeric values, e.g. 1W for one week, T1M for one minute, 1WT1H for one week plus one hour

  • quiet (bool) – when True, if the period string can’t be parsed, this function returns None, otherwise it raises an exception. The default is False

Return type

DType

Returns

a Period

Raises

DHError

upper_bin(dt, interval, offset=0)[source]
Returns a DateTime value, which is at the ending (upper) end of a time range defined by the interval

nanoseconds. For example, a 5*MINUTE intervalNanos value would return the DateTime value for the end of the five minute window that contains the input date time.

Parameters
  • dt (DateTime) – the DateTime for which to evaluate the end of the containing window

  • interval (int) – the size of the window in nanoseconds

  • offset (int) – the window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute. Default is 0

Returns

DateTime

Raises

DHError

year(dt, tz)[source]

Returns an int value of the year for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the year

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Returns

NULL_INT if dt is None

Return type

int

Raises

DHError

year_of_century(dt, tz)[source]

Returns the two-digit year for a DateTime in the specified time zone.

Parameters
  • dt (DateTime) – the DateTime for which to find the year

  • tz (TimeZone) – the TimeZone to use when interpreting the DateTime

Return type

int

Returns

int

Raises

DHError