deephaven.time¶

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

DurationLike¶

A Union representing objects that can be coerced into a Duration.

alias of Union[java.time.Duration, int, str, timedelta, timedelta64, Timedelta]

InstantLike¶

A Union representing objects that can be coerced into an Instant.

alias of Union[java.time.Instant, int, str, datetime, datetime64, Timestamp]

LocalDateLike¶

A Union representing objects that can be coerced into a LocalDate.

alias of Union[java.time.LocalDate, str, date, datetime, datetime64, Timestamp]

LocalTimeLike¶

A Union representing objects that can be coerced into a LocalTime.

alias of Union[java.time.LocalTime, int, str, time, datetime, datetime64, Timestamp]

PeriodLike¶

A Union representing objects that can be coerced into a Period.

alias of Union[java.time.Period, str, timedelta, timedelta64, Timedelta]

TimeZoneLike¶

A Union representing objects that can be coerced into a TimeZone.

alias of Union[java.time.ZoneId, str, tzinfo, datetime, Timestamp]

ZonedDateTimeLike¶

A Union representing objects that can be coerced into a ZonedDateTime.

alias of Union[java.time.ZonedDateTime, str, datetime, datetime64, Timestamp]

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 –

simple_date_format(pattern)[source]¶

Creates a Java SimpleDateFormat from a date-time format pattern.

This method is intended for use in Python code when a SimpleDateFormat is needed. It should not be used directly in query strings. The most common use case will use this function to construct a SimpleDateFormat in Python and then use the result in query strings.

Parameters:: pattern (str) – A date-time format pattern string.
Return type:: JType
Returns:: JObject
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 (Optional[DurationLike]) – 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 (Optional[InstantLike]) – 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 (Optional[LocalDateLike]) – 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 (Optional[LocalTimeLike]) – 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 (Optional[PeriodLike]) – 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 (Optional[TimeZoneLike]) – 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 (Optional[ZonedDateTimeLike]) – 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 –