acme.etc.DateUtils

module documentation

This module contains various utilty functions that deal with dates and times.

Function	`cronInPeriod`	A parser to check whether a cron pattern has been true during a certain time period.
Function	`cronMatchesTimestamp`	A cron parser to determine if the cronPattern matches for a given timestamp ts.
Function	`fromAbsRelTimestamp`	Parse a ISO 8601 string and return a UTC-based POSIX timestamp as a float.
Function	`fromDuration`	Convert a duration to a number of seconds (float).
Function	`fromISO8601Date`	Convert an ISO 8601 date time string to a datetime object.
Function	`getResourceDate`	Generate an UTC-relative ISO 8601 timestamp and return it.
Function	`isodateDelta`	Calculate the delta between and ISO 8601 date time string and a UTC-based POSIX timestamp.
Function	`rfc1123Date`	Return a date time string in RFC 1123 format, e.g. for use in HTTP requests.
Function	`timeUntilAbsRelTimestamp`	Return the time in seconds until the UTC-based POSIX absRelTimestamp is reached.
Function	`timeUntilTimestamp`	Return the time in seconds until the UTC-based POSIX timestamp is reached.
Function	`toDuration`	Convert a POSIX timestamp to ISO 8601 duration format.
Function	`toISO8601Date`	Convert and return a UTC-relative float timestamp or datetime object to an ISO 8601 string.
Function	`utcDatetime`	Return the current datetime, but relative to UTC.
Function	`utcTime`	Return the current time's timestamp, but relative to UTC.
Function	`waitFor`	Busy waiting for timeout seconds, or until a condition callback function returns True.

def cronInPeriod(cronPattern: str | list[str], startTs: datetime, endTs: datetime | None = None) -> tuple[bool, datetime]: ¶

A parser to check whether a cron pattern has been true during a certain time period.

This is useful for applications which cannot check every minute or need to catch up during a restart, or want to determinethe next run at some time in the future.

Attention

Be aware that this function just tries every minute between startTs and endTs, so it might take some time to execute.

Parameters
cronPattern:`str \| list[str]`	Either a string with the pattern or a list of strings, one for each pattern element.
startTs:`datetime`	Start UTC-based POSIX timestamp.
endTs:`datetime \| None`	End UTC-based POSIX timestamp. If None then the current UTC time is used to fill the timestamp. In this case startTs must be before endTs.

Returns
`tuple[bool, datetime]`	Tupple[bool, datetime]. The first element indicates whether the cronPattern matches any time in the given period. The second element provides the matched timestamp.

Raises
`ValueError`	If cronPattern is invalid.

def cronMatchesTimestamp(cronPattern: str | list[str], ts: datetime | None = None) -> bool: ¶

A cron parser to determine if the cronPattern matches for a given timestamp ts.

The cronPattern must follow the usual crontab pattern of 7 fields:

second minute hour dayOfMonth month dayOfWeek year

which each must comply to the following patterns:

* : any integer value
*/num : step values
num[,num]* : value list separator (either num, range or step)
num-num : range of values

Parameters
cronPattern:`str \| list[str]`	Either a string with the pattern or a list of strings, one for each pattern element.
ts:`datetime \| None`	Optional timestamp. If None then a current UTC-based timestamp is used to fill the timestamp.

Returns
`bool`	Boolean, indicating whether time pattern matches the given timestamp.

Raises
`ValueError`	If cronPattern is invalid.

def fromAbsRelTimestamp(absRelTimestamp: str, default: float | None = 0.0, withMicroseconds: bool | None = True) -> float: ¶

Parse a ISO 8601 string and return a UTC-based POSIX timestamp as a float.

If the absRelTimestamp is a period (relative) timestamp (e.g. "PT2S"), then this function tries to convert it and return an absolute POSIX timestamp as a float, based on the current UTC time.

If the absRelTimestamp contains a stringified integer then it is treated as a relative offset in ms and a UTC-based POSIX timestamp is generated for this offset and returned.

Parameters
absRelTimestamp:`str`	A string with either a stringified integer that represents a POSIX UTC-based timestamp, or a ISO 8601 period timestamp.
default:`float \| None`	The default that is returned in case a conversion fails.
withMicroseconds:`bool \| None`	The function handles the timestamps including micro seconds.

Returns
`float`	A float representing a UTC-based POSIX timestamp.

def fromDuration(duration: str, allowMS: bool = True) -> float: ¶

Convert a duration to a number of seconds (float).

Parameters
duration:`str`	String with either an ISO 8601 period or a string with a number of ms.
allowMS:`bool`	If True, the function tries to convert the string as if it contains a number of ms.

Returns
`float`	Float, number of seconds.

Raises
`Exception if wrong format is provided in duration.`

def fromISO8601Date(date: str) -> datetime: ¶

Convert an ISO 8601 date time string to a datetime object.

Parameters
date:`str`	ISO 8601 datetime string.

Returns
`datetime`	Datetime object.

def getResourceDate(offset: float | None = 0.0) -> str: ¶

Generate an UTC-relative ISO 8601 timestamp and return it.

Parameters
offset:`float \| None`	adds or substracts offset seconds to the generated timestamp.

Returns
`str`	String with UTC-relative ISO 8601 timestamp.

def isodateDelta(isoDateTime: str, now: float | None = None) -> float | None: ¶

Calculate the delta between and ISO 8601 date time string and a UTC-based POSIX timestamp.

Parameters
isoDateTime:`str`	ISO 8601 compatible string.
now:`float \| None`	Optional float with a time stamp. If None is given then the current time (UTC-based) will be taken.

Returns
`float \| None`	A signed float value indicating the delta (negative when the given ISO date time is earlier then "now"), or None in case of an error.

def rfc1123Date(timeval: float | None = None) -> str: ¶

Return a date time string in RFC 1123 format, e.g. for use in HTTP requests.

The timestamp is UTC-based.

Parameters
timeval:`float \| None`	Optional UTC-based POSIX timestamp to use, otherwise the current time is used.

Returns
`str`	String with the UTC-based time.

def timeUntilAbsRelTimestamp(absRelTimestamp: str) -> float: ¶

Return the time in seconds until the UTC-based POSIX absRelTimestamp is reached.

Parameters
absRelTimestamp:`str`	String with either an ISO 8601 period or a string with an integer (UTC-based POSIX timestamp in seconds).

Returns
`float`	Time in seconds until the timestamp is reached. Negative values mean that the timestamp lies is the past. 0.0 is returned in case of an error.

def timeUntilTimestamp(ts: float) -> float: ¶

Return the time in seconds until the UTC-based POSIX timestamp is reached.

Parameters
ts:`float`	UTC-based POSIX timestamp.

Returns
`float`	Number of seconds until the timestamp. A negative value means that the timestamp lies is the past.

def toDuration(ts: float) -> str: ¶

Convert a POSIX timestamp to ISO 8601 duration format.

Parameters
ts:`float`	Float with a UTC-based POSIX time stamp.

Returns
`str`	A string with an ISO 8601 duration.

def toISO8601Date(ts: float | datetime, readable: bool | None = False) -> str: ¶

Convert and return a UTC-relative float timestamp or datetime object to an ISO 8601 string.

Parameters
ts:`float \| datetime`	Timestamp. Either a POSIX float timestamp, of a datetime object.
readable:`bool \| None`	Optional boolean indicating whether the output should be in the format "YYYY-MM-DDThh:mm:ss,f

Returns
`str`	ISO 8601 datetime string.

def utcDatetime() -> datetime: ¶

Return the current datetime, but relative to UTC.

Returns
`datetime`	Datetime with current UTC-based time.

def utcTime() -> float: ¶

Return the current time's timestamp, but relative to UTC.

Returns
`float`	Float with current UTC-based POSIX time.

def waitFor(timeout: float, condition: Callable[[], bool] | None = None, latency: float | None = 0.01) -> bool: ¶

Busy waiting for timeout seconds, or until a condition callback function returns True.

Parameters
timeout:`float`	The time to wait at most for the event to be true.
condition:`Callable[[], bool] \| None`	A callback. It it returns True the wait-for condition is met and the waiting stops. If it is None, then only the timeout is used, and False is always returned.
latency:`float \| None`	The time between condition checks.

Returns
`bool`	The functionn returns True if the condition returns True before the timeout is reached, and False otherwise. It returns False if timeout is negative. If condition is not callable then False is returned.