hec.timespan

Provides basic time span functionality. Like timedelta, but with calendar capabilities and without sub-second resolution.

class TimeSpanException(builtins.Exception):

Exception specific to TimeSpan operations

@total_ordering
class TimeSpan:

Class to provide generic timespan capabilities that includes both calendar-based and non-calendar-based functionality. Internal fields are:

  • years
  • months
  • days
  • hours
  • minutes
  • seconds

Comparison/Contrast with timedelta



timedeltaTimeSpan


Does not  support calendar-based
operationsDoes support calendar-based operations


Does have sub-second resolutionDoes not have sub-second resolution


Can always be combined/compared
with other timedelta objects

    

  • Can always be combined with other TimeSpan
objects
    • 

  • Can be combined with timedelta objects if years
and months are both zero
    • 

  • Can be compared with other TimeSpan objects if days
values don't conflict with years or months values
    • 

  • Can be compared with timedelta objects if years
and months are both zero
    •

Fractional Months

Since HEC-DSS supports intervals of 1/3 and 1/2 month, the month portion of a TimeSpan object may be an integer or a Fraction object from the fractions package. Rules for using fractions are:

  • Fractions can be used for the month portion only
  • n/2 and n/3 are the only fractions allowed
  • Fractions can be specified as:
    • mathimatical expression (1/3)
    • Fraction object (Fraction(1,3))
    • string ("1/3")

Uninitialized Objects

Objects constructed without any initializer (e.g., ts = TimeSpan()) are initialized to be instantaneous (all values are zero).

String Representation

The repr function returns: 

TimeSpan([years, months, days, hours, minutes, seconds])
The str function returns one or two ISO 8601 duration strings or pseudo-duration strings if the months value is a fraction.

  • If the object has both calendar- and non-calendar-based (non-zero) values, and the signs of those portions are different, the result will be one duration string for the calendar portion and one for the non-calendar portion, separated by a comma.
  • Otherwise the result will be a single duration string.
PT0S
P1Y2M3DT4H5M
-P1Y2M3DT4H5M
P1Y2M,-P3DT4H5M
-P1Y2M,P3DT4H5M
P3Y1/3M
-P2/3M
TimeSpan(*args: Any, **kwargs: Any)

Initialiazes the object at construction.

Arguments:
  • Default
    • TimeSpan() Initializes to default value of instantaneous (all values equal zero)

  • Positional

    • TimeSpan(timedelta)
    • TimeSpan(string) where string is:
      • an integer as a string
      • one or two ISO 8601 strings or pseudo-duration strings as discussed under String Representation
    • TimeSpan(list) where list contains 1..6 values interpreted as years, months, days, hours, minutes, and seconds. Values must be convertable via the int() function except for the second value, which may also be convertable via the Fraction() constructor.
    • TimeSpan(tuple) where tuple contains 1..6 values interpreted as years, months, days, hours, minutes, and seconds. Values must be convertable via the int() function except for the second value, which may also be convertable via the Fraction() constructor.
    • TimeSpan(years[,months[,days[,hours[,minutes[,seconds]]]]]) All values must be convertable via the int() function except for months, which may also be convertable via the Fraction() constructor.

  • Keyword:

    • TimeSpan([years=years,] [months=months,] [days=days,] [hours=hours,] [minutes=minutes,] [seconds=seconds]) All values must be convertable via the int() function except for months, which may also be convertable via the Fraction() constructor.
Raises:
  • TimeSpanException: if invalid initializers are specified
def set(self, *args: Any, **kwargs: Any) -> None:

Initialiazes or re-initializes the object.

Arguments:

  • Positional

    • set(timedelta)
    • set(string) where string is:
      • an integer as a string
      • one or two ISO 8601 strings or pseudo-duration strings as discussed under String Representation
    • set(list) where list contains 1..6 values interpreted as years, months, days, hours, minutes, and seconds. Values must be convertable via the int() function except for the second value, which may also be convertable via the Fraction() constructor.
    • set(tuple) where tuple contains 1..6 values interpreted as years, months, days, hours, minutes, and seconds. Values must be convertable via the int() function except for the second value, which may also be convertable via the Fraction() constructor.
    • set(years[,months[,days[,hours[,minutes[,seconds]]]]]) All values must be convertable via the int() function except for months, which may also be convertable via the Fraction() constructor.

  • Keyword:

    • set([years=years], [months=months], [days=days], [hours=hours], [minutes=minutes], [seconds=seconds]) All values must be convertable via the int() function except for months, which may also be convertable via the Fraction() constructor.
Raises:
  • TimeSpanException: if invalid initializers are specified
def timedelta(self) -> datetime.timedelta:

Returns an equivalent timedelta object

Raises:
  • TimeSpanException: if the object contains any calendar-based values
Returns:

timedelta: The equivalent timedelta object

def total_seconds(self) -> int:

Returns the total number of seconds represented by this object

Raises:
  • TimeSpanException: if the object contains any calendar-based values
Returns:

int: The total number of seconds

values: Optional[list[Union[int, fractions.Fraction]]]

A list of years, months, days, hours, minutes, and seconds in this time span. On read, all values will be normalized:

  • years and days are unconstrained in magnitude
  • integer months will be in the range of ±0..12
  • fractional months normalized
  • hours will be in the range of ±0..23
  • minutes and seconds will be in the range ±0..59
  • calendar-based values (years, months) will have the same sign if not zero
  • non-calendar-based values (days, hours, minutes, seconds) will have the same sign if not zero
  • calendar- and non-calendar-based values may have different signs
Operations:

Read/Write