TimeUtils

class TimeUtils[source]

Bases: object

Utility class for time-related operations using monotonic and wall-clock time.

__init__() → None[source]: Initializes the TimeUtils instance with current time values.

Methods

`__init__`()	Initializes the TimeUtils instance with current time values.
`date_from_path`(path)	Extracts date from a file path based on filename convention.
`date_from_previous_weekday`(weekday)	Returns the date of the most recent occurrence of a specific weekday.
`date_from_string`(string)	Parses a date string into a datetime object.
`days_ago_init_times`(first, second, days[, ...])	Calculates initialization times for a previous day.
`filename_string_from_date`(date)	Formats a date object for filenames.
`find_closest_file_and_seconds`(directory, ...)	Finds the file closest to a given date and calculates time difference.
`format_duration`(milliseconds)	Formats a duration in milliseconds to a string.
`get_time_monotonic`()	Returns the current monotonic time in seconds.
`hours_ago`(hours)	Returns a datetime a specific number of hours in the past.
`measure_time`(func)	Decorator to measure execution time of a function.
`monotonic_ns_to_timestamps`(mono_ns)	Converts monotonic nanoseconds to a timestamp.
`now`()	Returns the current datetime calculated from monotonic time.
`now_string`()	Returns the current time as a formatted string.
`now_string_for_filename`()	Returns the current time formatted for filenames.
`now_timestamp`()	Returns the current timestamp.
`range_24_hours`(day_date, first_init_time)	Calculates a 24-hour range starting from a specific time.
`seconds_since_start`(start)	Returns the number of seconds elapsed since a given start time.
`string_from_date`(date)	Formats a date object as a string.
`string_from_timestamp`(timestamp)	Formats a timestamp as a string.
`sync`()	Synchronizes base time references.
`time_from_setting_string`(string)	Parses a time string from settings.
`time_in_future_seconds`(seconds)	Returns a datetime a specific number of seconds in the future.
`time_since_day_started`()	Returns the time elapsed since the start of the current day.
`tomorrow_init_time`(first)	Calculates the initialization time for tomorrow.

sync() → None[source]: Synchronizes base time references.

now() → datetime[source]

Returns the current datetime calculated from monotonic time.

Returns:: Current time.
Return type:: datetime.datetime

get_time_monotonic() → float[source]

Returns the current monotonic time in seconds.

Returns:: Monotonic time.
Return type:: float

now_timestamp() → float[source]

Returns the current timestamp.

Returns:: Current timestamp.
Return type:: float

monotonic_ns_to_timestamps(mono_ns: int) → float[source]

Converts monotonic nanoseconds to a timestamp.

Parameters:: mono_ns (int) – Monotonic time in nanoseconds.
Returns:: Corresponding timestamp.
Return type:: float

time_in_future_seconds(seconds: int) → datetime[source]

Returns a datetime a specific number of seconds in the future.

Parameters:: seconds (int) – seconds to add.
Returns:: Future time.
Return type:: datetime.datetime

hours_ago(hours: int) → datetime[source]

Returns a datetime a specific number of hours in the past.

Parameters:: hours (int) – hours to subtract.
Returns:: Past time.
Return type:: datetime.datetime

date_from_previous_weekday(weekday: int) → datetime[source]

Returns the date of the most recent occurrence of a specific weekday.

Parameters:: weekday (int) – The day of the week (0=Monday, 6=Sunday).
Returns:: The resulting date.
Return type:: datetime.datetime

time_since_day_started() → timedelta[source]

Returns the time elapsed since the start of the current day.

Returns:: Time elapsed.
Return type:: datetime.timedelta

seconds_since_start(start: datetime) → int[source]

Returns the number of seconds elapsed since a given start time.

Parameters:: start (datetime.datetime) – Start time.
Returns:: Seconds elapsed.
Return type:: int

now_string() → str[source]

Returns the current time as a formatted string.

Returns:: Formatted time string (“%Y-%m-%d %H:%M:%S”).
Return type:: str

now_string_for_filename() → str[source]

Returns the current time formatted for filenames.

Returns:: Formatted time string (“%Y%m%d_%H%M%S”).
Return type:: str

string_from_date(date: datetime) → str[source]

Formats a date object as a string.

Parameters:: date (datetime.datetime) – Date object.
Returns:: Formatted string (“%Y-%m-%d %H:%M:%S”).
Return type:: str

string_from_timestamp(timestamp: float) → str[source]

Formats a timestamp as a string.

Parameters:: timestamp (float) – Timestamp to format.
Returns:: Formatted string (“%Y-%m-%d %H:%M:%S”).
Return type:: str

filename_string_from_date(date: datetime) → str[source]

Formats a date object for filenames.

Parameters:: date (datetime.datetime) – Date object.
Returns:: Formatted string (“%Y%m%d_%H%M%S”).
Return type:: str

date_from_string(string: str) → datetime[source]

Parses a date string into a datetime object.

Parameters:: string (str) – Date string (“%Y-%m-%d %H:%M:%S”).
Returns:: Parsed datetime object.
Return type:: datetime.datetime

time_from_setting_string(string: str) → time[source]

Parses a time string from settings.

Parameters:: string (str) – Time string (“%H:%M”).
Returns:: Parsed time object, defaults to 08:00 on error.
Return type:: datetime.time

date_from_path(path: str) → datetime[source]

Extracts date from a file path based on filename convention.

Parameters:: path (str) – File path.
Returns:: Extracted date.
Return type:: datetime.datetime

days_ago_init_times(first: time, second: time, days: int, time_to_end: datetime | None = None) → Tuple[datetime, datetime][source]

Calculates initialization times for a previous day.

Parameters:

first (datetime.time) – First time.
second (datetime.time) – Second time.
days (int) – Days ago.
time_to_end (datetime.datetime | None) – End time reference.

Returns:

Calculated datetimes.

Return type:

Tuple[datetime.datetime, datetime.datetime]

tomorrow_init_time(first: time) → datetime[source]

Calculates the initialization time for tomorrow.

Parameters:: first (datetime.time) – Target time.
Returns:: Calculated datetime.
Return type:: datetime.datetime

range_24_hours(day_date: datetime, first_init_time: time) → Tuple[datetime, datetime][source]

Calculates a 24-hour range starting from a specific time.

Parameters:

day_date (datetime.datetime) – The date.
first_init_time (datetime.time) – The start time.

Returns:

Start and end datetimes.

Return type:

Tuple[datetime.datetime, datetime.datetime]

measure_time(func) → Callable[[...], Any][source]

Decorator to measure execution time of a function.

Parameters:: func (Callable) – Function to measure.
Returns:: Wrapped function.
Return type:: Callable

find_closest_file_and_seconds(directory: str, prefix: str, date: datetime) → Tuple[str, int][source]

Finds the file closest to a given date and calculates time difference.

Parameters:

directory (str) – Directory to search.
prefix (str) – Filename prefix.
date (datetime.datetime) – Target date.

Returns:

Path to closest file and seconds difference.

Return type:

Tuple[str, int]

format_duration(milliseconds: int) → str[source]

Formats a duration in milliseconds to a string.

Parameters:: milliseconds (int) – Duration in milliseconds.
Returns:: Formatted string (“HH:MM:SS.mmm”).
Return type:: str

class Chrono[source]

Bases: object

Simple specific chronometer for measuring elapsed time.

reset() → None[source]: Resets the chronometer.

get_time() → float[source]

Returns elapsed time in seconds.

Returns:: Elapsed time.
Return type:: float

get_seconds() → int[source]

Returns elapsed time in seconds as integer.

Returns:: Elapsed seconds.
Return type:: int

get_milliseconds() → int[source]

Returns elapsed time in milliseconds.

Returns:: Elapsed milliseconds.
Return type:: int

class Timer(seconds: int)[source]

Bases: object

Timer for checking if a specific duration has elapsed.

has_elapsed() → bool[source]

Checks if the timer has elapsed.

Returns:: True if elapsed, resets automatically.
Return type:: bool

ten_seconds_elapsed() → bool[source]

Checks if 10 seconds have elapsed.

Returns:: True if 10 seconds elapsed, resets automatically.
Return type:: bool

reset() → None[source]: Resets the timer.

class HourChangeDetector[source]

Bases: object

Detects if the hour has changed.

has_hour_changed() → bool[source]

Checks if the hour has changed since last check.

Returns:: True if hour changed.
Return type:: bool

class CycleChangeDetector(day_time: str, night_time: str)[source]

Bases: object

Detects if the day/night cycle has changed.

has_cycle_changed() → bool[source]

Checks if the cycle has changed.

Returns:: True if cycle changed.
Return type:: bool

class TimestampTracker(hours: int)[source]

Bases: object

Tracks timestamps and checks for emptiness within a time window.

add_timestamp() → None[source]: Adds a current timestamp.

trigger_empty() → bool[source]

Checks if the tracker is empty / inactive for the duration.

Returns:: True if state changed to empty.
Return type:: bool