lair.utils.clock#

Utility classes & functions for working with time and dates.

Functions

`convert_timezones`(x, totz[, fromtz, ...])	Convert the times from one timezone to another.
`datetime_accessor`(obj[, accessor])	Returns the datetime accessor of the object.
`decimalDate2dt`(decimalDate)	Convert a decimal date to a datetime object.
`diurnal`(data[, freq, statistic, method])	Aggregate the data to the specified frequency and compute the statistic for each group.
`dt2decimalDate`(datetime)	Convert a datetime object to a decimal date.
`seasonal`(data[, statistic])	Aggregate data by season and year.

Classes

`TimeRange`([time_range, start, stop])	TimeRange class to represent a time range with start and stop times.
`Timer`(name, text, logger, None] \| None =)	Time your code using a class, context manager, or decorator

TimeRange class to represent a time range with start and stop times.

Attributes

start	(dt.datetime \| None) The start time of the time range.
stop	(dt.datetime \| None) The stop time of the time range.
total_seconds	(float) The total number of seconds in the time range.

Methods

parse_iso(string: str, inclusive: bool = False) -> dt.datetime

Parse the ISO8601 formatted time string and return a datetime object.

Initialize a TimeRange object with the specified time range.

Parameters:

time_rangestr | list[Union[str, dt.datetime, None]] | tuple[Union[str, dt.datetime, None], Union[str, dt.datetime, None]] | slice | None: _description_, by default None
startUnion[_input_types, dt.datetime], optional: _description_, by default None
stopUnion[_input_types, dt.datetime], optional: _description_, by default None

Raises:

ValueError: _description_

static parse_iso(string: str, inclusive: bool = False) → datetime[source]#

Parse the ISO8601 formatted time string and return a namedtuple with the parsed components.

Parameters:

stringstr: The ISO8601 formatted time string.
inclusive

Returns:

dt.datetime: The parsed datetime object.

Raises:

ValueError: If the time_str format is invalid.

class lair.utils.clock.Timer(name: str | None = None, text: str = 'Elapsed time: {:0.4f} seconds', logger: ~typing.Callable[[str], None] | None = <built-in function print>)[source]#

Time your code using a class, context manager, or decorator

https://realpython.com/python-timer

logger(*args, sep=' ', end='\n', file=None, flush=False)#

Prints the values to a stream, or to sys.stdout by default.

sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
file: a file-like object (stream); defaults to the current sys.stdout.
flush: whether to forcibly flush the stream.

exception TimerError[source]#: A custom exception used to report errors in use of Timer class

start() → None[source]#: Start a new timer

stop() → float[source]#: Stop the timer, and report the elapsed time

reset_timers()[source]#: Reset class timers

__init__(name: str | None = None, text: str = 'Elapsed time: {:0.4f} seconds', logger: ~typing.Callable[[str], None] | None = <built-in function print>) → None#

lair.utils.clock.datetime_accessor(obj, accessor='dt')[source]#: Returns the datetime accessor of the object.

lair.utils.clock.diurnal(data: DataFrame, freq: str = '1H', statistic: str = 'mean', method: Literal['floor', 'ceil', 'round'] = 'floor')[source]#

Aggregate the data to the specified frequency and compute the statistic for each group.

Parameters:

datapd.DataFrame: The data to aggregate. Panda DataFrame with a DateTimeIndex.
freqstr: The frequency to aggregate the data to. Sub-Daily.
statisticstr or list of str, optional: The statistic to compute for each group. Default is ‘mean’.
methodone of ‘floor’, ‘ceil’, ‘round’: The method to use to round the index to the nearest freq.

Returns:

pd.DataFrame: The aggregated data.

lair.utils.clock.seasonal(data: DataFrame, statistic: str = 'mean') → DataFrame[source]#

Aggregate data by season and year.

Parameters:

datapd.DataFrame: The data to aggregate. Panda DataFrame with a DateTimeIndex.
statisticstr, optional: The statistic to compute for each group. Default is ‘mean’.

Returns:

pd.DataFrame: The aggregated data.

lair.utils.clock.dt2decimalDate(datetime: datetime) → float[source]#

Convert a datetime object to a decimal date.

Parameters:

datetimedt.datetime: The datetime object to convert.

Returns:

float: The decimal date.

lair.utils.clock.decimalDate2dt(decimalDate: float) → datetime[source]#

Convert a decimal date to a datetime object.

Parameters:

decimalDatefloat: The decimal date to convert.

Returns:

dt.datetime: The datetime object.

lair.utils.clock.convert_timezones(x, totz, fromtz=None, localize=False, driver=None)[source]#