hec.hectime

Module to provide native python compatibility for the hec.heclib.util.HecTime java class

NOTE Static java fields and methods are now module constants and functions (e.g., java HecTime.isLeap() -> python hectime.is_leap())

Jump to class HecTime

UNDEFINED_TIME: int = -4294967296

The value for a time integer that repsents that the time has either not been set yet or has been set incorrectly.

SECOND_GRANULARITY: int = 10

Value that specifies that each granule represents one second

  • Values are offset from [1970, 1, 1, 0, 0, 0]
  • Earliest represntable time is [1901, 12, 13, 20, 45, 52] (integer value = -2147483648)
  • Latest represntable time is [2038, 1, 19, 3, 14, 7] (integer value = 2147483647)
MINUTE_GRANULARITY: int = 11

Value that specifies that each granule represents one minute. New HecTime objects default to this granularity if not otherwise specified.

  • Values are offset from [1899, 12, 31, 0, 0, 0]
  • Earliest represntable time is [-2184, 12, 6, 21, 52, 0] (integer value = -2147483648)
  • Latest represntable time is [5983, 1, 23, 2, 7, 0] (integer value = 2147483647)
HOUR_GRANULARITY: int = 12

Value that specifies that each granule represents one hour

  • Values are offset from [1899, 12, 31, 0, 0, 0]
  • Earliest represntable time is [-243084, 3, 22, 16, 0, 0] (integer value = -2147483648)
  • Latest represntable time is [246883, 10, 8, 7, 0, 0] (integer value = 2147483647)
DAY_GRANULARITY: int = 13

Value that specifies that each granule represents one day

  • Values are offset from [1899, 12, 31, 0, 0, 0]
  • Earliest represntable time is [-5877711, 6, 22, 0, 0, 0] (integer value = -2147483645)
  • Latest represntable time is [5879610, 7, 10, 0, 0, 0] (integer value = 2147483647)
def add_century(y: int) -> int:

Converts 2-digit years into 4 digit years.

If the year passed in is not in the range 0..99, the year is returned unchanged

Arguments:
  • y (int): The year
Returns:

int: The year as a 4 digit year

def clean_time(values: list[int]) -> None:

Normalizes in integer list of either [julian, minute] or [year, month, day, hour, minute, second]

Arguments:
  • values (list[int]): Either [julian, minute] or `[year, month, day, hour, minute, second]
def compute_number_intervals( start_time: int, end_time: int, interval: Union[hec.Interval, int]) -> int:

Returns the complete number of intervals between two times

Arguments:
  • start_time (int): The time to compute the number of intervals from, in julian * 1440 + minutes_since_midnight
  • end_time (int): The time to compute the number of intervals to, in julian * 1440 + minutes_since_midnight
  • interval (Union[Interval, int]): The interval to compute the number for. If an integer, it must the the
  • actual or characteristic minutes value of a standard Interval object.
Raises:
  • HecTimeException: if the interval is not one of the standard intervals
Returns:

int: The number of complete intervals between the two times

def convert_time_zone( hectime: HecTime, from_time_zone: zoneinfo.ZoneInfo, to_time_zone: zoneinfo.ZoneInfo, respect_daylight_savings: Optional[bool] = True) -> None:

Converts an HecTime object from one time zone to another, optionally specifyintg that the target time zone does not observe Daylight Saving Time (DST). Only for HecTime objects convertable to datetime objects (between 01Jan0001, 00:00 and 31Dec9999, 23:59).

Arguments:
  • hectime (HecTime): The HecTime object to convert
  • from_time_zone (ZoneInfo): The time zone that the object is currently in
  • to_time_zone (ZoneInfo): The target time
  • respect_daylight_savings (Optional[bool]): Specifies whether the target time zone. should observe DST. Defaults to True.
    • If True, the target time zone is used as specified
    • If False and the specified target time zone observes DST, then a time zone is found that has the same UTC offset as the specified target time zone but does not observe DST.
Raises:
  • HecTimeException: - If the HecTime object has an attached time zone that is not the same as from_time_zone.
    • If respect_daylight_savings is True, to_time_zone observes DST and no equivalent time zone could be found that does not observer DST
    • If the HecTime object is not convertable to a datetime object
def curtim(julian: list[int], minutes: list[int]) -> None:

Get the current timm as days since 1899 and minutes past midnight and return in parameters.

Arguments:
  • julian (list[int]): A list of length > 0 whose first value receives the current days since 1899
  • minutes (list[int]): A list of length > 0 whose first value receives the current minutes past midnight
Deprecated:

Use systim() instead

def datcln( julian_in: int, minutes_in: int, julian_out: list[int], minutes_out: list[int]) -> None:

Normalizes a time specified in days since 1899 and minutes past midnight so that 0 <= minutes_out < 1440

Arguments:
  • julian_in (int): _description_
  • minutes_in (int): _description_
  • julian_out (list[int]): _description_
  • minutes_out (list[int]): _description_
def datjul(datestr: str, julian: list[int]) -> None:

Parses a date string and sets the the number of days since 1899 in the return variable

Arguments:
  • datestr (str): The date string (may contain time portion)
  • julian (list[int]): A list of length > 0 that whose first element receives the days since 1988
Raises:
  • HecTimeException: if the date string cannot be successfully parsed
def datymd(datestr: str, ymd: list[int]) -> int:

Parses a date string and sets the year, month, and day in the return variable

Arguments:
  • datestr (str): The date string to parse (may contain a time portion)
  • ymd (list[int]): A list of length > 2 whose first three elements receive the year, month, and day
Returns:

int: 0 on success or -1 otherwise

def get_time_int(values: list[int], granularity: int) -> int:

Return a time integer for specified time values and granularity

Arguments:
  • values (list[int]): The time values ([year, month, day, hour, minute, second])
  • granularity (int): The granularity of the time integer to return
Raises:
  • HecTimeException: if values is less than six items in length
  • HecTimeException: if the specified granularity is not valid
Returns:

int: The time integer for the specified time values and granularity

See:

is_valid_granularity(...)

def get_time_vals(time_int: int, granularity: int) -> list[int]:

Return time values for a time value and granularity

NOTE This function always returns midnight as [..., 0, 0, 0]. Use to2400(...) to get midnight as hour 24

Arguments:
  • time_int (int): The time integer to return the time values for
  • granularity (int): The granularity of the time integer
Raises:
  • HecTimeException: if time_int is not valid for the specified granularity
Returns:

list[int]: The list of time values ([year, month, day, hour, minute, second]) represented by the time integer in and granularity

def get_time_window( time_window_str: str, start_time: HecTime, end_time: HecTime) -> int:

Parses or computes the start and end of a time window specified as a string in the general form start_time end_time and return the computed times in the specified parameters.

Arguments:
  • time_window_str (str): The time window string. Both start time and end time may be absolute times or relative times. The string is not case sensitive, but the start and end times must be separated by a comma or whitespace.
    • If absolute:
      • may contain commas and/or spaces
      • may specify a time portion or not:
    • If relative:
      • may not contain commas or spaces
      • are of the format <anchor><offset>... where each offset is of the format [+-]<count><unit> Multiple offsets are allowed.
        • Valid anchors are:
          • T the current time
          • D the start of the current day
          • B or S - the start time (allowed only on end time and end must not depend on start time)
          • E - the end time (allowed only on start time and the start time must not depend on end time)
        • The unit for each offset must be one of:
          • Y - year(s)
          • M - month(s)
          • D - days(s)
          • H - hour(s)
    • Examples:
      • 01Aug2024, 01:00 31Aug2024 2400
      • 2024-01-01 2024-12-31,24:00
      • t-7d, t
      • e-1m+1d-2h,d
      • 01Aug2024, 01:00, s+1m
  • start_time (HecTime): Is set to the parsed or computed start time if returned status == 0
  • end_time (HecTime): Is set to the parsed or computed end time if returned status == 0
Returns:

int: 0 on success or -1 on failure to parse the string

def getime( time_window_str: str, start_jul: list[int], start_min: list[int], end_jul: list[int], end_min: list[int], status: list[int]) -> None:

Parses or computes the start and end of a time window specified as a string in the general form start_time end_time and return the computed times in the specified parameters.

Arguments:
  • time_window_str (str): The time window string. Both start time and end time may be absolute times or relative times. The string is not case sensitive, but the start and end times must be separated by a comma or whitespace.
    • If absolute:
      • may contain commas and/or spaces
      • may specify a time portion or not:
    • If relative:
      • may not contain commas or spaces
      • are of the format <anchor><offset>... where each offset is of the format [+-]<count><unit> Multiple offsets are allowed.
        • Valid anchors are:
          • T the current time
          • D the start of the current day
          • B or S - the start time (allowed only on end time and end must not depend on start time)
          • E - the end time (allowed only on start time and the start time must not depend on end time)
        • The unit for each offset must be one of:
          • Y - year(s)
          • M - month(s)
          • D - days(s)
          • H - hour(s)
    • Examples:
      • 01Aug2024, 01:00 31Aug2024 2400
      • 2024-01-01 2024-12-31,24:00
      • t-7d, t
      • e-1m+1d-2h,d
      • 01Aug2024, 01:00, s+1m
  • start_jul (list[int]): Element[0] receives the days since 1899 for the start time if status[0] == 0
  • start_min (list[int]): Element[0] receives the minutes past midnight for the start time if status[0] == 0
  • end_jul (list[int]): Element[0] receives the days since 1899 for the end time if status[0] == 0
  • end_min (list[int]): Element[0] receives the minutes past midnight for the end time if status[0] == 0
  • status (list[int]): Element[0] recieves 0 if the time window string was successfully parsed, -1 otherwise
def hm2m(hm: Union[str, int]) -> int:

Converts a time in hhmm format (integer or string) to minutes

Arguments:
  • hm (int): The time to convert (e.g, '0730', 730)
Returns:

int: The equivalent minutes (e.g., 450)

def idaywk(date: Union[int, list[int]]) -> int:

Returns the weekday (1=Sunday -> 7=Saturday) for the specified date.

NOTE This differs from datetime.weekday() whch returns 0=Monday -> 6=Sunday.

Arguments:

  • date (Union[int, list[int]]): The date as:

    • int - number of days since 1899
    • list - a list of at least 3 integers specifying the year, month and day
Returns:

int: The weekday (1=Sunday -> 7=Saturday)

def ihm2m(hm: str) -> int:

Converts a string in hhmm format to integer minutes

Arguments:
  • hm (int): The time to convert (e.g, '0730', 730)
Deprecated:

Use hm2m() instead

Returns:

int: The equivalent minutes (e.g., 450)

def ihm2m_2(hm: str) -> int:

Converts integers in a string to integer minutes

Arguments:
  • hm (str): The string to collect integers from. Valid strings are:
    • "0730"
    • "730"
    • "7 30"
    • "0 7 3 0"
    • "7H30M"
Returns:

int: The equivalent minutes (e.g., 450)

def increment_time_vals(values: list[int], increment_value: int, granularity: int) -> list[int]:

Increment or decrement time values by a specified amount and return the result

Arguments:
  • values (list[int]): The time values ([year, month, day, hour, minute, sec]) to increment/decrement.
  • increment_value (int): The number of granules to increment (>0) or decrement (<0)
  • granularity (int): The granule size (SECOND_GRANULE, MINUTE_GRANULE, HOUR_GRANULE, or DAY_GRANULE)
Raises:
  • HecTimeException: if values is less than six items in length
Returns:

list[int]: The incremented or decremented values

def inctim(*args: Any) -> None:

Increments a number of days since 1899 and minutes past midnight by a specified number of intervals of a specified size

Args:

  • 6 Parameters:
    • interval (Union[TimeSpan, timedelta, int]): - If integer, it is in minutes
    • num_periods (int): - The number of intervals to increment
    • start_julian (int): - The starting number of days since 1899
    • start_minute (int): - The starting minutes past midnight
    • end_julian (list[int]): - Element 0 receives the ending days since 1899
    • end_minute (list[int]): - Element 0 receives the ending minutes past midnight
  • 7 Parameters:
    • interval (int): - The interval in minutes or days
    • unit_flag (int): - A flag spcifying whether interval is in minutes (0) or days (1)
    • start_julian (int): - The starting number of days since 1899
    • start_minute (int): - The starting minutes past midnight
    • end_julian (list[int]): - Element 0 receives the ending days since 1899
    • end_minute (list[int]): - Element 0 receives the ending minutes past midnight
Raises:
  • HecTimeException: if invalid arguments are passed to the function
def is_leap(y: int) -> bool:

Return whether the specified year is a leap year

Arguments:
  • y (int): The year
Returns:

bool: Whether the year is a leap year

def is_valid_granularity(value: int) -> bool:

Return whether specified granularity is valid

Arguments:
  • value (int): The granularity value to test
Returns:

bool: Whether the value is one of

def is_valid_time(date_time: Union[int, list[int]], granularity: int) -> bool:

Return whether a specified time integer or time values are in the valid range for the specified granularity

Arguments:
  • date_time (Union[int, list[int]]): The time integer or time values ([year, month, day, hour, minute, second]) to check validity for
  • granularity (int): The granularity to check validity for
Returns:

bool: Whether the time integer or time values are in the valid range for the granularity

def iymdjl(year: int, month: int, day: int) -> int:

Returns the number of days since 31Dec1899 for a specified year, month, and day

Arguments:
  • year (int): The year
  • month (int): The month
  • day (int): The day
Deprecated:

Use year_month_day_to_julian() instead

Returns:

int: The number of days sinc 31Dec1899

def jliymd(*args: Any) -> None:

Populates year, month, and day arguments with the appropriate values for a specified number of days since 31Dec1899

Args:

  • 2 args:
    • jul (int): The number of days since 31Dec1899
    • ymd (list[int]): A list of length >= 3 that receives the year, month, and day
  • 4 args
    • jul (int): The number of days since 31Dec1899
    • year (list[int]): An integer list whose first value received the year
    • month (list[int]): An integer list whose first value received the month
    • day (list[int]): An integer list whose first value received the day
Deprecated:

Use julian_to_year_month_day() instead

Raises:
  • HecTimeException: if invalid arguments are specified
def juldat(julian: int, style: int) -> str:

Returns the date of the specified number of days since 31Dec1899 in the specified style

Arguments:
  • julian (int): The number of days since 1899
  • style (int): The style to return the date in. See date()
Returns:

str: The date in the specified style

def julian_to_year_month_day(*args: Any) -> None:

Populates year, month, and day arguments with the appropriate values for a specified number of days since 31Dec1899

Args:

  • 2 args:
    • jul (int): The number of days since 31Dec1899
    • ymd (list[int]): A list of length >= 3 that receives the year, month, and day
  • 4 args
    • jul (int): The number of days since 31Dec1899
    • year (list[int]): An integer list whose first value received the year
    • month (list[int]): An integer list whose first value received the month
    • day (list[int]): An integer list whose first value received the day
Raises:
  • HecTimeException: if invalid arguments are specified
def m2hm(m: int) -> int:

Returns the equivalent time integer (hhmm) for a specified minute count

Arguments:
  • m (int): The minutes to convert (e.g., 450)
Returns:

int: The time equivalent in hhmm (e.g, 730)

def m2ihm(mintues: int, hour_minutes: list[str]) -> int:

Returns the equivalent time integer (hhmm) for a specified minute count and places the string representaion in HHMM format in the specified variable

Arguments:
  • m (int): The minutes to convert (e.g., 450)
  • hour_minutes (list[str]): Element 0 receives string equivalen in HHMM format (e.g., "0730")
Deprecated:

Use m2hm() instead

Returns:

int: The time equivalent in hhmm (e.g, 730)

def max_day(y: int, m: int) -> int:

Return the last month day for a specified year and month

Arguments:
  • y (int): The year
  • m (int): The month
Returns:

int: The last calendar day of the specified month

def minutes_since_midnight(values: list[int]) -> int:

Returns the number of minutes past midnight for specified time values

Arguments:
  • values (list[int]): The time values ([year, month, day, hour, minute, second])
Raises:
  • HecTimeException: If values is less than six items in length
Returns:

int: The number of minutes past midnight

def next_month(y: int, m: int) -> tuple[int, int]:

Returns the next year and for a specified year and month.

Arguments:
  • y (int): The specified year
  • m (int): The specified month
Returns:

tuple[int, int]: The next year and month

def NoOpWarning(func: Callable[..., Any]) -> Callable[..., Any]:
def nopers(*args: Any) -> int:

Returns the complete number of intervals between two times

Arguments:
  • 5-parameter version
    • interval (Union[Interval, int]): The interval to compute the number of. If an integer, must be the actual or characteristic minutes of a standard Interval object
    • start_julian (int): The days since 1899 of the first time
    • start_minute (int): The minutes past midnight of the first time
    • end_julian (int): The days since 1899 of the second time
    • end_minute (int): The minutes past midnight of the second time
  • 6 parameter version
    • interval (int): The number of minutes or days in the interval to compute the number of. Must be the actual or characteristic number of minutes (or equivalent days) of a standard Interval object
    • unit_flag (int): 0 for interval in minutes, 1 for interval in days
    • start_julian (int): The days since 1899 of the first time
    • start_minute (int): The minutes past midnight of the first time
    • end_julian (int): The days since 1899 of the second time
    • end_minute (int): The minutes past midnight of the second time
Raises:
  • HecTimeException: if the interval is not one of the standard intervals
Returns:

int: The number of complete intervals between the two times

def normalize_date_style(style: int) -> int:

Returns a valid date style for a specified input style

Arguments:
  • style (int): The input date style
Returns:

int: The valid date style

def normalize_time_vals(values: list[int]) -> None:

Normalize a list of time values ([year, month, day, hour, minute, second]) in place.

Adjusts each element of the list to be in the valid range for a date/time value.

Arguments:
  • values (list[int]): The values to normalize.
Raises:
  • HecTimeException: if values is less that six items in length
def NotImplementedWarning(func: Callable[..., Any]) -> Callable[..., Any]:
def parse_date_time_str( date_time_str: str, include_tz: bool = False) -> tuple[list[int], typing.Optional[str]]:

Parse date/time strings of various formats into time values ([year, month, day, hour, minute, second] and an optional time zone string).

The string must contain at least year, month, day. Missing seconds, (minutes, seconds), or (hours, minutes, seconds) are set to zero.

For strings that cannot be parsed with this method, use HecTime.strptime()

Arguments:
  • date_time_str (str): The date/time string
  • include_tz (bool): Whether to include the time zone portion if date_time_str is in ISO-8601 format.
  • If True, the tuple returned will include the time zone string. Defaults to False
Raises:
  • HecTimeException: if date_time_str cannot be parsed into at least year, month, and day
Returns:

tuple[list[int], Optional[str]]: *Position 0: The time values as parsed from the date/time string: [year, month, day, hour, minute, second] *Position 1: The time zone string if include_tz == True and date_time_str has a time zone portion, otherwise None

See Also:

HecTime.strptime()

def previous_month(y: int, m: int) -> tuple[int, int]:

Returns the previous year and for a specified year and month.

Arguments:
  • y (int): The specified year
  • m (int): The specified month
Returns:

tuple[int, int]: The previous year and month

def seconds_since_midnight(values: list[int]) -> int:

Returns the number of seconds past midnight for specified time values

Arguments:
  • values (list[int]): The time values ([year, month, day, hour, minute, second])
Raises:
  • HecTimeException: If values is less than six items in length
Returns:

int: The number of seconds past midnight

def systim( julian: list[int], time: list[int], time_in_minutes: Optional[bool] = False, in_time_zone: Optional[str] = None) -> None:

Get the current time as days since 1899 and minutes or seconds past midnight and return in parameters, optionally in a specified time zone

Arguments:
  • julian (list[int]): A list of length > 0 whose first value receives the current days since 1899
  • time (list[int]): A list of length > 0 whose first value receives the current minutes or seconds past midnight
  • time_in_minutes (Optional[bool]): Specifies whether to return the time in minutes (True) or seconds (False) past midnight. Default is False
  • in_time_zone (Optional[str]): If present, specifies the time zone of the current time. The days and time values will be converted from this time zone to UTC
def to0000(values: list[int]) -> list[int]:

Return a copy of time values ([year, month, day, hour, minute, second]) with [..., 24, 0, 0] changed to [..., 0, 0, 0] of the next day

Arguments:
  • values (list[int]): The values to modify if ending in [24, 0, 0]
Raises:
  • HecTimeException: if values less than six items in length
Returns:

list[int]: A copy of the time values, modified if necessrary

def to2400(values: list[int]) -> list[int]:

Return a copy of time values ([year, month, day, hour, minute, second]) with [..., 0, 0, 0] changed to [..., 24, 0, 0] of the previous day

Arguments:
  • values (list[int]): The values to modify if ending in [0, 0, 0]
Raises:
  • HecTimeException: if values less than six items in length
Returns:

list[int]: A copy of the time values, modified if necessrary

def year_month_day_to_julian(y: int, m: int, d: int, account_for_offset: bool = True) -> int:

Returns the number of days since 31Dec 1899 for a specified year, month, and day

Arguments:
  • y (int): The year
  • m (int): The month
  • d (int): The day
  • account_for_offset (bool) : (Default = True) Specifies whether to account for the missing date (31Dec0004). This should be True unless the function is called from an HecTime method which already accounts for it.
Returns:

int: The number of days since 31Dec1899

def ymddat(ymd: list[int], style: int, err: list[int]) -> str:

Returns the date in the specified style

Arguments:
  • ymd (list[int]): The year, month, and day to format
  • style (int): The style to use (see HecTime.date())
  • err (list[int]): Element 0 recieve 0 on success and -1 otherwise
Returns:

str: The date in the specified style, or None if err[0] == -1

def zofset( julian: list[int], minutes: list[int], interval: int, operation: int, offset: list[int]) -> None:

Computes the offet into a standard interval and/or adjusts the specified time to be at the computed offset

NOTE: Unlike HecTime.adjust_to_interval_offset, any adjustments made will result in the output time being earlier than the input time.

Arguments:
  • julian (list[int]): On input, element 0 specifies the days since 1899 of the date On output, element[0] recieves the adjusted days since 1899 if operation is 1 or 2
  • minutes (list[int]): On input, element 0 specifies the minutes past midnight of the time. On output, element[0] recieves the adjusted minutes past midnight if operation is 1 or 2
  • interval (int): The interval used to compute the offset and/or adjust the time
  • operation (int):
    • 0: Compute the offset only (return in offset[0])
    • 1: Compute the offset (return in offset[0]) and adjust the time to the offset (return in julian[0] and minutes[0])
    • 2: adjust the time to the offset only (return in julian[0] and minutes[0])
  • offset (list[int]): On output, element 0 receives the computed offset if operation is 0 or 1
class HecTimeException(builtins.Exception):

Exception specific to the hectime module

@total_ordering
class HecTime:

Class to facilitate moving Jython scripts that use Java class hec.heclib.util.HecTime to Python

Implementation:

Compatibility with Java HecTime

This class replicates the capabilities of the Java hec.heclib.util.HecTime class, and uses the same method names except the camel case names of the Java class have been renamed to snake case to match Python naming standards as shown in the following examples:



Java Method NamePython Method Name


adjustToIntervalOffset()adjust_to_interval_offset()


computeNumberIntervals()compute_number_intervals()

Granularity

Like Java HecTime, HecTime objects can be instaniated with different time granularities, with each granule specifying a second, minute, hour, or day. Specifically:



GranularityInteger RangeEach Granule SpecifiesDate Range


SECOND_GRANULARITY
= 10		-2147483648
+2147483647		Seconds after
01Jan1970, 00:00		+1901-12-13T20:45:52
+2030-01-19T03:14:17


MINUTE_GRANULARITY
= 11		-2147483648
+2147483647		Minutes after
31Dec1899, 00:00		-2184-12-06T21:52
+5983-01-23T02:07


HOUR_GRANULARITY
= 12		-2147483648
+2147483647		Hours after
31Dec1899, 00:00		-243084-03-22T16
+246883-10-08T07


DAY_GRANULARITY
= 13		-2147483645
+2146789687		Days after
31Dec1899		-5877711-06-22
+5879610-07-10

The default granularity is MINUTE_GRANULARITY, but this may be overridden when calling HecTime().

Chainable methods

Since, unlike Java, Python allows code to ignore the return value from functions and methods, many HecTime methods with a void return type in Java now return a modified HecTime object. This allows the chaining of methods together for simplify code. For example:

t = HecTime()
t.set_current()
t.adjust_to_interval_offset(intvl, 0)
t.increment(1, intvl)

can now be coded as:

t = HecTime.now().adjust_to_interval_offset(intvl, 0).increment(1, intvl)

although the previous style is still supported.

Compatibility with datetime

This class is written to be trivially convertable to/from datetime objects and updatable via timedelta objects. Like datetime objects, HecTime objects are not time zone aware unless given time zone information. For HecTime objects the label_as_time_zone() method is used for this purpose. Also like datetime objects, using the astimezone() method causes the object to act as if it had been initialized with the local time zone.

Initialization from a datetime object is acccomplished via ht = HecTime(dt_obj). Retieval of a datetime object is accomplished via dt_obj = ht.datetime(). The HecTime.label_as_time_zone(tz) accomplishes the same thing as datetime.replace(tzinfo=tz), and the HecTime.astimezone(tz) accomplishes the same thing as datetime.astimezone(tz)

datetime methods, properties, and operators supported in HecTime objects are:

  • Methods
    • now() (static method)
    • astimezone(timezone)*
    • strftime(format)
    • strptime(date_time_str, format)
    • __str__() (used in print())
  • Properties
  • Operators
    • + and +=
    • - and -=
    • == and !=
    • < and <=
    • > and >=`

*The astimezone(timezone), method, like all HecTime methods that take time zone will accept:

  • ZoneInfo object
  • String (timezone name)
  • HecTime object (the object's time zone is used)
  • datetime object (the object's time zone is used)

Note: Compatibility with datetime as well as time zone support is only available on HecTime objects that are within the datetime object range of 01Jan0001, 00:00 through 31Dec9999, 23:59. Also, time zone support is not provided for HecTime objects of DAY_GRANULARITY.

Addition, subtraction, and comparison operators

Integers, HecTime objects, TimeSpan objects, Interval objects, Duration objects, timedelta objects, and specially formatted strings (see below) can be used on the right side of the + and += operators. The result is always another HecTime object. Allowing HecTime objects to be added to each other breaks the similarity with datetime, but is included to provide the functionality Java HecTime.

Integers, HecTime objects, datetime objects, TimeSpan objects, Interval objects, Duration objects, timedelta objects, and specially formatted strings (see below) can be used on the right side of the - or -= operators.

  • The result is an HecTime object when subtracting intgers, TimeSpan objects, Interval objects, Duration objects, timedelta objects and strings.
  • The result is a TimeSpan object when subtracting HecTime objects
  • The result is a timedelta object when subtracting datetime objects

If the HecTime object on the left side of any +, -, +=, or -= operator has a time zone attached and the right- side object is an Interval has the is_local_regular property of True, then addition and subtraction is performed with respect to the time zone of the HecTime object. For example if the HecTime object is at midnight in the US/Pacific time zone, then adding a local-regular interval of 2 hours will result in an HecTime object at 2 a.m. in the same time zone. The actual amount of time added with respect to UTC will be 1, 2, or 3 hours, depending on the day, month, and year.

Adding and subtracting integers adds or subracts the number of granules in the object so the change may be in seconds, minutes, hours, or days, depending on the object's granularity.

Strings of the format used for the offset portion of relative time strings in get_time_window() can be used in addition and subtraction operators. Examples

  • t - "1y" would return an HecTime object one year prior to the t object
  • t += "3m-2d+1h" would increment the t object forward 3 months, back 2 days and forward 1 hour.

This precludes using ISO 8601 duration strings that have minutes or seconds components. To use these, create a TimeSpan object from the string for the addend

HecTime objects can be compared with each other or with datetime objects using the standard operators (==, !=, <, <=, >, >=). Either type may be on either side of the operators.

Use of properties

Many methods are deprecated and will generate deprecation warnings when used. Most have been replaced by direct read/write or read-only properties.

The value(), year(), month(), day(), hour(), minute(), and second() methods are still supported but are accessed in a more pythonic way as read/write (value) or read-only (year, month, day, hour, minute, second) properties. There is no clean way to issue deprecation warning if these properties are accessed by their getter functions.

HecTime(*args: Any)

Initializes a newly-created HecTime object.

Arguments:

Raises:
  • HecTimeException: if invalid parameters are specified
def add( self, time: Union[int, HecTime, hec.TimeSpan, datetime.timedelta, str]) -> HecTime:

Adds an number of granules or an HecTime to this object

Arguments:
  • other (Union[int, "HecTime", TimeSpan, timedelta, str]): item to add
Deprecated:

Use the += operator instead

Returns:

HecTime: The modified object

def add_days(self, days: int) -> HecTime:

Adds a number of days to the object

Arguments:
  • days (int): the number of days to add.
Returns:

HecTime: The modified object

def add_hours(self, hours: int) -> HecTime:

Adds a number of hours to the object

Arguments:
  • hours (int): the number of hours to add.
Returns:

HecTime: The modified object

def add_minutes(self, minutes: int) -> HecTime:

Adds a number of minutes to the object

Arguments:
  • minutes (int): the number of minutes to add.
Returns:

HecTime: The modified object

def add_seconds(self, seconds: int) -> HecTime:

Adds a number of seconds to the object

Arguments:
  • seconds (int): the number of seconds to add.
Returns:

HecTime: The modified object

def adjust_to_interval_offset( self, interval: Union[hec.Interval, int], offset_minutes: int) -> HecTime:

Adjusts this object to be at the specified offset past the specified interval.

NOTE: Unlike zofset The resulting time may be at, before, or after the this object, but will always be in the interval that begins at or before this object.

To get the begninning of the interval that starts at or before this object, set offset_minutes to 0. To get the beginning of the next interval set offset_minutes be the same as interval_minutes.

Arguments:
  • interval (Union[Interval, int]): The interval. If an integer, must be the actual or charactersitic minutes of a standard Interval
  • offset_minutes (int): The offset into the interval in minutes (0..interval)
Returns:

The adjusted object

Raises:
  • HecTimeException: if offset it out of range for interval
def astimezone( self, time_zone: Union[HecTime, datetime.datetime, zoneinfo.ZoneInfo, str], on_tz_not_set: int = 1) -> HecTime:

See convert_to_time_zone

@NoOpWarning
def clean_time(self) -> None:

Placeholder for API compatibility. Does nothing.

def clone(self) -> object:

Returns a clone of this object

Returns:

object: the clone of this object

def compare_times(self, other: HecTime) -> int:

Returns an integer comparison with another HecTime object

Arguments:
  • other (HecTime): The other HecTime object
Returns:

int:

  • -1 if this object < other
  • 0 if this object == other
  • 1 if this object > other
@NotImplementedWarning
def compare_to(self, other: object) -> Any:

Not supported in this implementation

def compute_number_intervals( self, other: HecTime, interval: Union[int, datetime.timedelta, hec.Interval]) -> int:

Returns the number of complete intervals between this object and another specified HecTime object

Arguments:
  • other (HecTime): The other time to compute the number of intervals to

  • interval (Union[int, timedelta]): The interval size to compute the number of intervals for.

    • int - the minutes in a standard interval
    • timedelta - If equivalent to a standard interval, the same result as specifying the equivalent integer is returned. Otherwise the both HecTime objects are converted to datetime objects and the number of intervals is computed as `((other.datetime - self.datetime) / timesdelta')
Raises:
  • HecTimeException: if interval is a non-standard integer or if it is a nonstandard timedelta and either of this object or other is not convertable to a datetime object
Returns:

int: The number of complete intervals between this time and the other time.

def convert_time_zone( self, from_time_zone: Union[zoneinfo.ZoneInfo, str], to_time_zone: Union[zoneinfo.ZoneInfo, str], respect_daylight_saving: Optional[bool] = True) -> HecTime:

Converts this object from one time zone to another, optionally specifyintg that the target time zone does not observe Daylight Saving Time (DST). Only for HecTime objects convertable to datetime objects (between 01Jan0001, 00:00 and 31Dec9999, 23:59).

NOTE: The Java signatures for this method that operate on and return a copy of the HecTime object are not supported in this implementation. The astimezone() method can be used for that purpose.

Arguments:
  • from_time_zone (Union[ZoneInfo, str]): The time zone to convert from
  • to_time_zone (Union[ZoneInfo, str]): The target time zone
  • respect_daylight_saving (Optional[bool]): Specifies whether the target time zone. should observe DST. Defaults to True.
    • If True, the target time zone is used as specified
    • If False and the specified target time zone observes DST, then a time zone is found that has the same UTC offset as the specified target time zone but does not observe DST.
Returns:

HecTime: The modified object

Raises:
  • HecTimeException: - If respect_daylight_saving is True, to_time_zone observes DST and no equivalent time zone could be found that does not observer DST
    • If this object is not convertable to a datetime object
def convert_to_time_zone( self, time_zone: Union[HecTime, datetime.datetime, zoneinfo.ZoneInfo, datetime.timezone, str, NoneType], on_tz_not_set: int = 1) -> HecTime:

Returns a copy of this object at the spcified time zone

Arguments:
  • time_zone (Optional[Union["HecTime", datetime, ZoneInfo, timezone, str]]): The target time zone or object containg the target time zone.
    • Use None to remove time zone information without time conversion.
    • Use "local" to specify the system time zone.
  • on_tz_not_set (int, optional): Specifies behavior if this object has no time zone attached. Defaults to 1.
    • 0: Quietly behave as if this object had the local time zone attached.
    • 1: (default) Same as 0, but issue a warning.
    • 2: Raise an exception preventing objectes with out time zones attached from using this method.
Returns:

HecTime: A copy of this object at the specified time zone

def copy(self) -> HecTime:

Returns a copy of this object already cast as an HecTime

Returns:

HecTime: The copy

def date(self, style: Optional[int] = None) -> str:

Returns the date in the specified style

Base date styles
0: June 2, 198510:  June 2, 85100: JUNE 2, 1985110: JUNE 2, 85
1:  Jun 2, 198511:   Jun 2, 85101:  JUN 2, 1985111:  JUN 2, 85
2:  2 June 198512:   2 June 85102:  2 JUNE 1985112:   2 JUN 85
3:    June 198513:     June 85103:    JUNE 1985113:    JUNE 85
4:    02Jun198514:     02Jun85104:    02JUN1985114:    02JUN85
5:     2Jun198515:      2Jun85105:     2JUN1985115:     2JUN85
6:      Jun198516:       Jun85106:      JUN1985116:      JUN85
7:  02 Jun 198517:   02 Jun 85107:  02 JUN 1985117:  02 JUN 85
8:   2 Jun 198518:    2 Jun 85108:   2 JUN 1985118:   2 JUN 85
9:     Jun 198519:      Jun 85109:     JUN 1985119:     JUN 85
Extended date styles
-1:      6/2/85-11:    06/02/85-101:     6/2/1985-111: 06/02/1985
-2:      6-2-85-12:    06-02-85-102:     6-2-1985-112: 06-02-1985
               -13:  1985-06-02

NOTE that years that overflow four digits will not be truncated if using a style that shows four digits in the table (styles 0..9, 100..109, -113..-101 and -13). Other formats will continue to show only the last two digits of the year. In all cases a negative sign will be prepended to the year for negative years (whether two digits or more are shown).

Arguments:
  • style (Optional[int]): The date style to use. If not specified the default_date_style property is used
Returns:

str: The formatted date

def date_and_time(self, style: Optional[int] = None) -> str:

Returns a string representing the date and time in the specified style.

Arguments:
  • style (Optional[int]): The date style to use. If not specified the default_date_style property is used
Returns:

str: The formatted date and time. The date is generated using the style parameter (see date), which is separated from the time portion (with colons) (see time) by a comma and space

date_str: str

The object's current date string using the default_date_style

Operations:

Read Only

date_time_str: str

The object's current date and time string using the default_date_style

Operations:

Read

def datetime(self) -> Optional[datetime.datetime]:

Returns a datetime object equivalent to this object.

Returns:

datetime: The equivalent datetime object or None if this object's time is undefined

day: Optional[int]

The object's day of month, or None if undefined

Operations:

Read Only

def day_of_week(self) -> Optional[int]:

Returns the day of week (1 = Sunday -> 7 = Saturday) for this object.

NOTE: This differs from datetime.weekday() whch returns 0=Monday -> 6=Sunday.

Returns:

int: The day of week (1 = Sunday -> 7 = Saturday)

def day_of_week_name(self) -> Optional[str]:
def day_of_year(self) -> Optional[int]:

Returns the day of the year of this object (01Jan = 1)

Returns:

Optional[int]: The day of the year

default_date_style: int

The object's current default data style.

Operations:

Read/Write

defined: bool

Whether this object has been defined

Operations:

Read Only

def equal_to(self, other: HecTime) -> bool:

Returns whether this object is equivalent to another

Arguments:
  • other (Union["HecTime", datetime]): The object to compare to
Deprrecated:

Use == operator instead

Returns:

bool: The result of the comparison

def get_default_date_style(self) -> int:

Returns the default date style

Deprecated:

Use default_date_style property instead

Returns int: The default date style

def get_interval_offset(self, interval: Union[hec.Interval, int]) -> Optional[int]:

Returns the number of minutes that the current object is after the top of the most recent standard interval

Arguments:
  • interval Union[Interval, int]: The interval to determine the offset into. If int, then the value is minutes.
Raises:
  • HecTimeException: if the interval is not a standard interval
Returns:

Optional[int]: The number of minutes into the interval

def get_iso_8601_date_time(self) -> str:

Returns the time of this object in ISO 8601 format.

Returns:

str: The time of this object in ISO 8601 format

def get_minutes( self, time_zone_offset: Union[int, zoneinfo.ZoneInfo, NoneType] = None) -> Optional[int]:

Returns the time of this object as (days since 1899) * 1400 + (minutes past midnight), optionally offsetting by a time zone

Arguments:
  • time_zone_offset (Optional[Union[int, ZoneInfo]]): if int, the number of minutes behind UTC (positive for western longitudes)
Returns:

int: The time in minutes

def get_shows_time_as_beginning_of_day(self) -> bool:

Retrieves whether midnight is shown as hour 0 instead of hour 24 of the previous day

Deprecated:

Use midnight_as_2400 property instead

Returns:

bool: True if midnight is shown as hour 0, False if midnight is shown as hour 24

def get_time(self, with_colons: Optional[bool] = True) -> str:

Returns a string representing the time portion

  • with_colons = True (default), [..., 6, 8, 23] is retuned is 06:08:23
  • with_colons = False, [..., 6, 8, 23] is retuned is 0608
Arguments:
  • with_colons (Optional[bool]): Specifies with or without colons. Defaults to True.
Deprecated:

use .HecTime.time">time method instead

Returns:

str: The time portion string with colons (hour, minute, and second), or without colons (hour, minute only))

def get_time_granularity(self) -> int:

Returns the granularity of this object

Deprecated:

Use granularity property instead

Returns:

int: The granularity

def get_time_in_millis( self, time_zone_offset: Union[int, zoneinfo.ZoneInfo, NoneType] = None) -> Optional[int]:

Returns the time of this object in milliseconds into of the Unix Epoch (01Jan1970 00:00:00 UTC).

Note that is the standard time value used in Java as well as 1000.0 times the standard time value used in python (e.g., time.time() or datetime.timestamp())

Arguments:
  • time_zone_offset (Optional[Union[int, ZoneInfo]]): if int, the number of minutes behind UTC (positive for western longitudes). If not specified, the milliseconds returned will be as if this object is in UTC
Returns:

Optional[int]: None if this object is not defined., otherwise the milliseconds of the current time from the beginning of the Unix Epoch

def get_xml_date_time(self) -> str:

Returns the time of this object in ISO 8601 format.

Deprecated:

Use get_iso_8601_date_time instead

Raises:
  • HecTimeException: if time_zone_offset is specifed but is not an integer or ZoneInfo object,
  • or is a ZoneInfo object and no UTC offset could be determined from it
Returns:

str: The time of this object in ISO 8601 format

granularity: int

The object's current granularity.

Operations:

Read/Write

Returns:

int: The granularity

def greater_than(self, other: HecTime) -> bool:

Returns whether this object is greater than (later than) another HecTime object

Arguments:
  • other (HecTime): The other object to compare to
Deprecated:

Use the the > operator instead.

Returns:

bool: Whether this object is greater than the other

def greater_than_equal_to(self, other: HecTime) -> bool:

Returns whether this object is greater than (later than) or equal to (same time as) another HecTime object

Arguments:
  • other (HecTime): The other object to compare to
Deprecated:

Use the the >= operator instead.

Returns:

bool: Whether this object is greater than or equal to the other

hour: Optional[int]

The object's hour of day, or None if undefined

Operations:

Read Only

def hour_minutes(self) -> str:

Returns the time portion in HHMM format or "" if this object is undefined

Returns:

str: The time portion in HHMM format or "" if this object is undefined

def hours_minutes_seconds(self, hours: list[int], minutes: list[int], seconds: list[int]) -> None:

Returns the object's hour, minute, and second in the spefied parameters

Arguments:
  • hours (list[int]): Element 0 recieves the hour
  • minutes (list[int]): Element 0 recieves the minute
  • seconds (list[int]): Element 0 receives the second
def increment( self, count: int, interval: Union[hec.Interval, hec.TimeSpan, datetime.timedelta, int]) -> HecTime:

Increments this object by a specified number of intervals.

For month-based intervals ("Tri-Month", "Semi-Month", "1Month", "1Year"), if the date of the current object is the last day of a month, the resulting date will be the last day of the month or sub-month (days 10 or 20 for "Tri-Month" and day 15 for "Semi-Month"), as shown:

Start TimeCountIntervalResult
28Feb2023, 01:001"Tri-Month"10Mar2023, 01:00
28Feb2023, 01:002"Tri-Month"20Mar2023, 01:00
28Feb2023, 01:003"Tri-Month"31Mar2023, 01:00
28Feb2024, 01:001"Tri-Month"08Mar2023, 01:00
28Feb2024, 01:002"Tri-Month"18Mar2023, 01:00
28Feb2024, 01:003"Tri-Month"28Mar2023, 01:00

Note that this method produces results that differ from the Java HecTime.increment() method where the Java code produces incorrect results, as in the following examples (all such discrepancies are limited to "Tri-Month", "Semi-Month", and "1Month":

Start TimeCountIntervalCorrect ResultJava HecTime Result
29Jan2023, 01:001"1Month"28Feb2023, 01:0001Mar2023, 01:00
09Feb2024, 01:002"Tri-Month"29Feb2024, 01:0009Mar2024, 01:00
28Feb2024, 01:002"Semi-Month"28Mar2024, 01:0031Mar2024, 01:00
Arguments:
  • count (int): The number of intervals to increment
  • interval (Union[Interval, TimeSpan, timedelta, int]): The interval to increment by. If int:
    • interpreted as a number of minutes
    • for standard intervals:
      • should be actual minutes for intervals <= 1Week
      • should characteristic minutes for intervals > 1Week
Returns:

HecTime: The incremented object

def increment_secs(self, count: int, interval: int) -> HecTime:

Increments this object by a specified number of intervals, which are specified in seconds

Arguments:
  • count (int): The number of intervals to increment
  • interval (int): The size of the interval in seconds. The behavior depends on whether the interval is < 60:
    • < 60 - the object is incremented by (count * interval) seconds
    • >= 60 - The object is incremented by (count * interval // 60) minutes
Returns:

HecTime: The incremented object

def is_defined(self) -> bool:

Returns whether this object has been defined

Deprecated:

Use defined property instead

Returns:

bool: Whether this object has been defined

def iso_date(self) -> str:

Returns the date of the current object as YYMMDD format

Returns:

str: The date in YYMMDD format

def iso_time(self) -> str:

Returns the time of the current object as HHMMSS format

Returns:

str: The date in HHMMSS format

def is_time_defined(self) -> bool:

Returns whether this object has been defined

Deprecated:

Use defined property instead

Returns:

bool: Whether this object has been defined

is_utc: bool
def label_as_time_zone( self, time_zone: Union[HecTime, datetime.datetime, zoneinfo.ZoneInfo, datetime.timezone, str, NoneType], on_already_set: int = 1) -> HecTime:

Attaches the specified time zone to this object. Does not change the time

Arguments:
  • time_zone (Optional[Union["HecTime", datetime, ZoneInfo, timezone, str]]): The time zone to attach or object containing that time zone. Use "local" to specify the system time zone.
  • on_already_set (int, optional): Specifies action to take if a different time zone is already attached. Defaults to 1.
    • 0: Quietly attach the new time zone
    • 1: (default) Issue a warning about attaching a different time zone
    • 2: Raises an exception
Raises:
  • HecTimeException: if a different time zone is already attached and on_already_set == 2
Returns:

HecTime: The updated object

def julian(self) -> Optional[int]:

Returns the number of days since 31Dec8199 for this object

Returns:

int: The number of days since 31Dec1899

def less_than(self, other: HecTime) -> bool:

Returns whether this object is less than (earlier than) another HecTime object

Arguments:
  • other (HecTime): The other HecTime object
Deprecated:

Use the < operator instead

Returns:

bool: Whether this object is less than the other object

def less_than_equal_to(self, other: HecTime) -> bool:

Returns whether this object is less than (earlier than) another or equal to (same time as) HecTime object

Arguments:
  • other (HecTime): The other HecTime object
Deprecated:

Use the <= operator instead

Returns:

bool: Whether this object is less than or equal to the other object

midnight_as_2400: bool

The object's current setting of whether to show midnight as hour 24 (default) or not.

Operations:

Read/Write

minute: Optional[int]

The object's minute of hour, or None if undefined

Operations:

Read Only

def minutes_since_midnight(self) -> Optional[int]:

Returns the number of minutes past midnight for this object

Returns:

int: the number of minutes past midnight

month: Optional[int]

The object's month, or None if undefined

Operations:

Read Only

def not_equal_to(self, other: HecTime) -> bool:

Returns whether this object is not equivalent to another

Arguments:
  • other (Union["HecTime", datetime]): The object to compare to
Deprrecated:

Use != operator instead

Returns:

bool: The result of the comparison

@staticmethod
def now(granularity: int = 11) -> HecTime:

Returns a new HecTime object initialized to the current system time and specified or default granularity

Arguments:
  • granularity (int, optional): The granularity of the new object. Defaults to MINUTE_GRANULARITY.
Returns:

HecTime: The newly created object

second: Optional[int]

The object's second of minute, or None if undefined

Operations:

Read Only

def seconds_since_midnight(self) -> int:

Returns the number of seconds past midnight for this object

Returns:

int: the number of seconds past midnight

def set(self, *args: Any) -> int:

Set the object to a specified date/time. Valid parameters are:

  • set(time_int: int) sets the time to the value of time_int for the current granularity
  • set(date_time_str: str) sets the time to the results of .parse_date_time_str">parse_date_time_str(date_time_str)
  • set(dt: datetime) sets the time to the value of dt
  • set(values: Union[list[int],tuple[int,...]]) sets the time to values
  • set(other_hectime: HecTime) sets the time and granularity to be the same as other_hectime
  • set(date_str: str, time_str: str) sets the time to the results of .parse_date_time_str">parse_date_time_str(date_str+" "+time_str)
Returns:

int: 0 if date/time is successfully set, otherwise non-zero

See Also:

parse_date_time_str()
HecTime.strptime()

def set_current(self) -> HecTime:

Sets this object to the current time

Returns:

HecTime: The modified object

def set_date(self, date_str: str) -> int:

Sets the date portion only from a string

Arguments:
  • date_str (str): The date string. Any time portion is ignored
Returns:

int: 0 on success or -1 on failure

def set_default_date_style(self, style: int) -> None:

Sets the default date style

Arguments:
  • style (int): The default date style
Deprecated:

Use default_date_style property instead

def set_julian( self, julian: int, minutes_since_midnight: Optional[int] = None, seconds_since_midnight: Optional[int] = None) -> HecTime:

Sets the date portion from the number of days since 1899, and optionally the time portion

Arguments:
  • julian (int): The number of days since 1899
  • minutes_since_midnight (Optional[int]): The number of minutes past midnight for the time portion. Defaults to None.
  • seconds_since_midnight (Optional[int]): The number of seconds past the minute for the time portion. Defaults to None.
Returns:

HecTime: The modified object

def set_minutes( self, total_minutes: int, time_zone_offset: Union[int, zoneinfo.ZoneInfo, NoneType]) -> HecTime:

Set the date and time portions of this object from the number of minutes since 1899

Arguments:
  • total_minutes (int): The number of minutes since 1899
  • time_zone_offset (Optional[Union[int, "ZoneInfo"]]): The time zone to represent this object in. Defaults to None. If int, the number of minutes behind UTC (positive for western longitudes)
Returns:

HecTime: The modified object

Raises:
  • HecTimeException: if time_zone_offset is not an integer or ZoneInfo object, or if the UTC offset cannot be determed for the ZoneInfo object
def set_seconds(self, total_seconds: int) -> HecTime:

Sets the date and time portions of this object from the number seconds since 1970-01-01T00:00:00Z

Arguments:
  • total_seconds (int): The number of seconds since 1970-01-01T00:00:00Z (same as Python timestamps and seconds of Unix Epoch)
Returns:

HecTime: The modified object

def set_time(self, time_str: str) -> int:

Set the time portion of this object from a time string with or without the date portion

Arguments:
  • time_str (str): the time string
Returns:

int: 0 on success or -1 if the time string cannot be parsed

def set_time_granularity(self, granularity: int) -> HecTime:

Sets the granularity, keeping the existing time values if possible

Arguments:
  • granularity (int): The new granularity
Deprecated:

Use granularity property instead

Returns:

HecTime: The modified object

@NotImplementedWarning
def set_time_granularity_seconds(self, granularity_in_seconds: int) -> None:

Not supported in this implementation

def set_time_in_millis( self, milliseconds: int, time_zone_offset: Union[int, zoneinfo.ZoneInfo, NoneType]) -> HecTime:

Sets the date and time portions of this object from the number milliseconds since 1970-01-01T00:00:00Z

Arguments:
  • milliseconds (int): The number of seconds since 1970-01-01T00:00:00Z (same as Java milliseconds and milliseconds of Unix Epoch)
  • time_zone_offset (Optional[Union[int, "ZoneInfo"]]): The time zone to represent this object in. Defaults to None. If int, the number of minutes behind UTC (positive for western longitudes)
Returns:

HecTime: The modified object

def set_undefined(self) -> HecTime:

Sets this object to the undefined state.

Returns:

HecTime: The modified object

def set_xml(self, date_time_str: str) -> int:

Sets this object from an ISO 8601 date/time string.

Arguments:
  • date_time_str (str): The date/time string
Deprecated:

The set() function handles this. Use it instead

Returns:

int: 0 on success, -1 otherwise

def set_year_month_day( self, year: int, month: int, day: int, minutes_since_midnight: Optional[int]) -> HecTime:

Sets the date portion from a year, month, and day, and optioally the time portion from minutes past midnight

Arguments:
  • year (int): The year
  • month (int): The month
  • day (int): The day
  • minutes_since_midnight (Optional[int]): The minutes past midnight
Returns:

HecTime: The modified object

def show_time_as_beginning_of_day(self, state: bool) -> HecTime:

Sets whether to show midnight as hour 0 instead of hour 24 of the previous day

Arguments:
  • state (bool): Whether to show midnight as hour 0 instead of hour 24 of the previous day
Deprecated:

Use midnight_as_2400 property instead

Returns:

HecTime: The modified object

def strftime(self, format: str) -> str:

Returns a string representing the date and time in the specified format.

Arguments:
  • format (str): The format string. Format specfics can be found here.
Returns:

str: The formatted date and time

See Also:
def strptime(self, date_time_str: str, format: str) -> HecTime:

Sets this object from a string representation and a matching format.

Arguments:
  • date_time_str (str): The string to parse.
  • format (str): The format describing the string. Format specfics can be found here.
Returns:

HecTime: The object updated from the string representation and formt.

See Also:

parse_date_time_str()
HecTime.set()

def subtract( self, other: Union[int, HecTime, hec.TimeSpan, datetime.timedelta, str]) -> HecTime:

Subtracts an integer number of granules or HecTime object from this one

Arguments:
  • other (Union[int, "HecTime", TimeSpan, timedelta, str]): item to subtract
Deprecated:

Use the -= operator instead

Returns:

HecTime: The modified object

def subtract_days(self, days: int) -> HecTime:

Subtracts a number of days from the object

Arguments:
  • days (int): the number of days to subtract.
Returns:

HecTime: The modified object

def subtract_hours(self, hours: int) -> HecTime:

Subtracts a number of hours fram the object

Arguments:
  • hours (int): the number of hours to subtract.
Returns:

HecTime: The modified object

def subtract_minutes(self, minutes: int) -> HecTime:

Subtracts a number of minutes from the object

Arguments:
  • minutes (int): the number of minutes to subtract.
Returns:

HecTime: The modified object

def subtract_seconds(self, seconds: int) -> HecTime:

Subtracts a number of seconds from the object

Arguments:
  • seconds (int): the number of seconds to subtract.
Returns:

HecTime: The modified object

def time(self, with_colons: Optional[bool] = True) -> str:

Returns a string representing the time portion

  • with_colons = True (default), [..., 6, 8, 23] is retuned is 06:08:23
  • with_colons = False, [..., 6, 8, 23] is retuned is 0608
Arguments:
  • with_colons (Optional[bool]): Specifies with or without colons. Defaults to True.
Returns:

str: The time portion string with colons (hour, minute, and second), or without colons (hour, minute only))

def time_granularity(self) -> int:

Returns the granularity of this object

Deprecated:

Use granularity property instead

Returns:

int: The granularity

@NotImplementedWarning
def to_string(self, style: Optional[int]) -> Any:

Not supported in this implementation

tzinfo: Optional[zoneinfo.ZoneInfo]

The object's attached time zone

Operations:

Read Only

value: int

The object's current time integer.

Operations:

Read/Write

year: Optional[int]

The object's year, or None if undefined

Operations:

Read Only

values: Optional[list[int]]

The object's current time values ([year, month, day, hour, minute, second]).

This property is None when the value property is UNDEFINED_TIME

Operations:

Read/Write