deephaven.time#

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

dh_now(system=False, resolution='ns')[source]#

Provides the current datetime according to the current Deephaven clock.

Query strings should use the built-in “now” function instead of this function. The build-in “now” function is pure Java and will be more efficient because fewer Java/Python boundary crossings will be needed.

Parameters:
  • system (bool) – True to use the system clock; False to use the default clock. Under most circumstances, the default clock will return the current system time, but during replay simulations, the default clock can return the replay time.

  • resolution (str) – The resolution of the returned time. The default “ns” will return nanosecond resolution times if possible. “ms” will return millisecond resolution times.

Return type:

DType

Returns:

Instant

Raises:

DHError, TypeError

dh_time_zone()[source]#

Provides the current Deephaven system time zone.

Query strings should use the built-in “timeZone” function instead of this function. The build-in “timeZone” function is pure Java and will be more efficient because fewer Java/Python boundary crossings will be needed.

Return type:

DType

Returns:

TimeZone

Raises:

DHError

dh_today(tz=None)[source]#

Provides the current date string according to the current Deephaven clock. Under most circumstances, this method will return the date according to current system time, but during replay simulations, this method can return the date according to replay time.

Query strings should use the built-in “today” function instead of this function. The build-in “today” function is pure Java and will be more efficient because fewer Java/Python boundary crossings will be needed.

Parameters:

tz (TimeZone) – Time zone to use when determining the date. If None is provided, the Deephaven system default time zone is used.

Return type:

str

Returns:

Date string

Raises:

DHError

time_zone_alias_add(alias, tz)[source]#

Adds a new time zone alias.

Parameters:
  • alias (str) – Alias name.

  • tz (str) – Time zone name.

Return type:

None

Returns:

None

Raises:

DHError

time_zone_alias_rm(alias)[source]#

Removes a time zone alias.

Parameters:

alias (str) – Alias name.

Return type:

bool

Returns:

True if the alias was present; False if the alias was not present.

Raises:

DHError

to_date(dt)[source]#

Converts a Java date time to a datetime.date.

Parameters:

dt (Union[None, LocalDate, ZonedDateTime]) – A Java date time. If None is provided, None is returned.

Return type:

Optional[date]

Returns:

datetime.date

Raises:

DHError, TypeError

to_datetime(dt)[source]#

Converts a Java date time to a datetime.datetime.

Parameters:

dt (Union[None, Instant, ZonedDateTime]) – A Java date time. If None is provided, None is returned.

Return type:

Optional[datetime]

Returns:

datetime.datetime

Raises:

DHError, TypeError

to_j_duration(dt)[source]#

Converts a time duration value to a Java Duration, which is a unit of time in terms of clock time (24-hour days, hours, minutes, seconds, and nanoseconds). Time duration values can be None, a Java Duration, an int, a string, a datetime.timedelta, a numpy.timedelta64, or a pandas.Timedelta.

int values are nanoseconds.

Duration strings can be formatted according to the ISO-8601 duration format as ‘[-]PnDTnHnMn.nS’, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

Examples

“PT20.345S” – parses as “20.345 seconds”
“PT15M” – parses as “15 minutes” (where a minute is 60 seconds)
“PT10H” – parses as “10 hours” (where an hour is 3600 seconds)
“P2D” – parses as “2 days” (where a day is 24 hours or 86400 seconds)
“P2DT3H4M” – parses as “2 days, 3 hours and 4 minutes”
“PT-6H3M” – parses as “-6 hours and +3 minutes”
“-PT6H3M” – parses as “-6 hours and -3 minutes”
“-PT-6H+3M” – parses as “+6 hours and -3 minutes”
Parameters:

dt (Union[None, Duration, int, str, datetime.timedelta, numpy.timedelta64, pandas.Timedelta]) – A time duration value. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

Duration

Raises:

DHError, TypeError

to_j_instant(dt)[source]#

Converts a date time value to a Java Instant. Date time values can be None, a Java Instant, an int, a string, a datetime.datetime, a numpy.datetime64, or a pandas.Timestamp.

int values are the number of nanoseconds since the Epoch.

Instant strings can be formatted according to the ISO 8601 date time format ‘yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ’ and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

Parameters:

dt (Union[None, Instant, int, str, datetime.datetime, numpy.datetime64, pandas.Timestamp]) – A date time value. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

Instant, TypeError

Raises:

DHError

to_j_local_date(dt)[source]#

Converts a date time value to a Java LocalDate. Date time values can be None, a Java LocalDate, a string, a datetime.date, a datetime.datetime, a numpy.datetime64, or a pandas.Timestamp.

Date strings can be formatted according to the ISO 8601 date time format as ‘YYYY-MM-DD’.

Parameters:

dt (Union[None, LocalDate, str, datetime.date, datetime.datetime, numpy.datetime64, pandas.Timestamp]) – A date time value. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

LocalDate

Raises:

DHError, TypeError

to_j_local_time(dt)[source]#

Converts a date time value to a Java LocalTime. Date time values can be None, a Java LocalTime, an int, a string, a datetime.time, a datetime.datetime, a numpy.datetime64, or a pandas.Timestamp.

int values are the number of nanoseconds since the start of the day.

Time strings can be formatted as ‘hh:mm:ss[.nnnnnnnnn]’.

Parameters:

dt (Union[None, LocalTime, int, str, datetime.time, datetime.datetime, numpy.datetime64, pandas.Timestamp]) – A date time value. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

LocalTime

Raises:

DHError, TypeError

to_j_period(dt)[source]#

Converts a time duration value to a Java Period, which is a unit of time in terms of calendar time (days, weeks, months, years, etc.). Time duration values can be None, a Java Period, a string, a datetime.timedelta, a numpy.timedelta64, or a pandas.Timedelta.

Period strings can be formatted according to the ISO-8601 duration format as ‘PnYnMnD’ and ‘PnW’, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

Examples

“P2Y” – 2 Years
“P3M” – 3 Months
“P4W” – 4 Weeks
“P5D” – 5 Days
“P1Y2M3D” – 1 Year, 2 Months, 3 Days
“P-1Y2M” – -1 Year, 2 Months
“-P1Y2M” – -1 Year, -2 Months
Parameters:

dt (Union[None, Period, str, datetime.timedelta, numpy.timedelta64, pandas.Timedelta]) – A Python period or period string. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

Period

Raises:

DHError, TypeError, ValueError

to_j_time_zone(tz)[source]#

Converts a time zone value to a Java TimeZone. Time zone values can be None, a Java TimeZone, a string, a datetime.tzinfo, a datetime.datetime, or a pandas.Timestamp.

Parameters:

tz (Union[None, TimeZone, str, datetime.tzinfo, datetime.datetime, pandas.Timestamp]) – A time zone value. If None is provided, None is returned. If a string is provided, it is parsed as a time zone name.

Return type:

Optional[DType]

Returns:

TimeZone

Raises:

DHError, TypeError

to_j_zdt(dt)[source]#

Converts a date time value to a Java ZonedDateTime. Date time values can be None, a Java ZonedDateTime, a string, a datetime.datetime, a numpy.datetime64, or a pandas.Timestamp.

Date time strings can be formatted according to the ISO 8601 date time format 'yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ' and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

Converting a datetime.datetime or pandas.Timestamp to a ZonedDateTime will use the datetime’s timezone information. Converting a numpy.datetime64 to a ZonedDateTime will use the Deephaven default time zone.

Parameters:

dt (Union[None, ZonedDateTime, str, datetime.datetime, numpy.datetime64, pandas.Timestamp]) – A date time value. If None is provided, None is returned.

Return type:

Optional[DType]

Returns:

ZonedDateTime

Raises:

DHError, TypeError

to_np_datetime64(dt)[source]#

Converts a Java date time to a numpy.datetime64.

Parameters:

dt (Union[None, Instant, ZonedDateTime]) – A Java date time. If None is provided, None is returned.

Return type:

Optional[datetime64]

Returns:

numpy.datetime64

Raises:

DHError, TypeError

to_np_timedelta64(dt)[source]#

Converts a Java time durationto a numpy.timedelta64.

Parameters:

dt (Union[None, Duration, Period]) – A Java time period. If None is provided, None is returned.

Return type:

Optional[timedelta64]

Returns:

numpy.timedelta64

Raises:

DHError, TypeError, ValueError

to_pd_timedelta(dt)[source]#

Converts a Java time duration to a pandas.Timedelta.

Parameters:

dt (Union[None, Duration]) – A Java time duration. If None is provided, None is returned.

Return type:

Optional[Timedelta]

Returns:

pandas.Timedelta

Raises:

DHError, TypeError, ValueError

to_pd_timestamp(dt)[source]#

Converts a Java date time to a pandas.Timestamp.

Parameters:

dt (Union[None, Instant, ZonedDateTime]) – A Java date time. If None is provided, None is returned.

Return type:

Optional[Timestamp]

Returns:

pandas.Timestamp

Raises:

DHError, TypeError

to_time(dt)[source]#

Converts a Java date time to a datetime.time.

Parameters:

dt (Union[None, LocalTime, ZonedDateTime]) – A Java date time. If None is provided, None is returned.

Return type:

Optional[time]

Returns:

datetime.time

Raises:

DHError, TypeError

to_timedelta(dt)[source]#

Converts a Java time duration to a datetime.timedelta.

Parameters:

dt (Union[None, Duration]) – A Java time duration. If None is provided, None is returned.

Return type:

Optional[timedelta]

Returns:

datetime.timedelta

Raises:

DHError, TypeError, ValueError