Skip to content

chronix

Jump to bottom
github-actions[bot] edited this page Mar 5, 2026 · 3 revisions

chronix package

Subpackages

Module contents

This module provides a collection of timing utilities, including timers with different resolution levels, time formatting and conversion utilities, and performance measurement tools for function execution time analysis.

class chronix.BasicTimer(auto_start: bool = False)

Bases: object

A class to represent a basic timer that can be started, stopped, paused, resumed, and records tick-tock intervals. It also supports tallying recorded time intervals, calculating the average duration, and converting elapsed time to a readable format.

start_time

The timestamp when the timer started.

Type: float or None

stop_time

The timestamp when the timer stopped.

Type: float or None

pause_start_time

The timestamp when the timer was paused.

Type: float or None

pause_duration

The total duration the timer has been paused.

Type: float

tick_tocks

A list of tuples containing the start and stop times for each tick-tock interval.

Type: list of tuples

is_stopped

A flag indicating whether the timer is currently stopped.

Type: bool

is_ended

A flag indicating whether the timer has ended.

Type: bool
Parameters: auto_start (bool) – If True, starts the timer automatically upon initialization.

__init__(auto_start: bool = False) -> None

Initializes the BasicTimer object. Optionally starts the timer immediately.

Parameters: auto_start (bool) – If True, the timer starts automatically upon initialization.

average() -> timedelta | None

Calculates the average duration of all recorded tick-tock intervals.

Returns: The average duration as a timedelta object, or None if no intervals are recorded.
Return type: timedelta or None

end() -> Self

Ends the timer, preventing any further operations such as start, pause, or resume.

Returns: The current BasicTimer instance for method chaining.
Return type: self

get() -> timedelta | None

Retrieves the current elapsed time from when the timer was started. If the timer is paused or stopped, it calculates the time up to that point.

Returns: The total elapsed time as a timedelta object, or None if the timer has not been started.
Return type: timedelta or None

get_readable(format_to: PreciseTimeFormat = PreciseTimeFormat.SECONDS) -> str

Converts the current elapsed time to a human-readable format based on the specified time unit.

Parameters: format_to (int) – The time format to convert to. Defaults to TimeFormat.SECONDS.
Returns: A human-readable string representing the elapsed time in the specified format.
Return type: str

get_times() -> list[tuple[float, float]]

Retrieves the list of all tick-tock intervals recorded.

Returns: Each tuple contains the start and stop times for each tick-tock interval.
Return type: list of tuples

pause() -> Self

Pauses the timer, storing the current time as the pause start time. Raises an error if the timer is already paused, stopped, or not started.

Returns: The current BasicTimer instance for method chaining.
Return type: self

resume() -> Self

Resumes the timer from a paused state and adjusts the total paused duration. Raises an error if the timer is not paused or has ended.

Returns: The current BasicTimer instance for method chaining.
Return type: self

split_end() -> Self

Records a tock, which captures the current time as an interval end. Raises an error if the timer has ended or is not started.

Returns: The current BasicTimer instance for method chaining.
Return type: self

split_start() -> Self

Records a tick, which captures the current time as an interval start. Raises an error if the timer has ended or is not started.

Returns: The current BasicTimer instance for method chaining.
Return type: self

start() -> Self

Starts the timer. If the timer was stopped or paused, it resets the start time and resumes recording. Raises an error if the timer has already been started or ended.

Returns: The current BasicTimer instance for method chaining.
Return type: self

stop() -> Self

Stops the timer and records the current time as the stop time. Raises an error if the timer is already stopped or not started.

Returns: The current BasicTimer instance for method chaining.
Return type: self

tally() -> int | float

Calculates the total time recorded between all tick-tock intervals.

Returns: The total elapsed time in seconds.
Return type: float

class chronix.CPUFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.CPUFTimerNS(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.DateTimeFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

This is a joke and should not be taken seriously as it isn’t performant.

class chronix.FlexTimer(start_at: int | float = 0, start_now: bool = True)

Bases: object

A timer class to manage multiple timers and track elapsed time with nanosecond precision. If a time value is not specified as something specific, it is assumed to be in seconds.

EMPTY

A constant tuple representing an empty timer slot.

Type: tuple

EMPTY: tuple[int | float, int | float, int | float, allocate_lock | None] = (0, 0, 0, None)

SENTINEL = <object object>

__init__(start_at: int | float = 0, start_now: bool = True) -> None

Initializes the TimidTimer instance.

Parameters:
  • start_at (float* or int, **optional*) – The initial starting point of the timer. Defaults to 0.
  • start_now (bool*, **optional*) – If True, the timer starts immediately. Defaults to True.

after(delay: float | int, callback: Callable[[...], Any], *, ms: bool = False, long: bool = False, args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None) -> Self

Starts a countdown timer for a specified number of seconds. :param delay: The duration of the countdown in seconds. :param callback: The function to call when the countdown ends. Defaults to print. :param ms: Flag that determines if the delay param should be treated as seconds or milliseconds. :param long: Flag that determines if the timer should be optimized for long wait times. :param args: The arguments for the callback function. Defaults to a message with the countdown time. :param kwargs: The keyword arguments for the callback function. Defaults to None. :return:

classmethod at(index: int, *args: Any, **kwargs: Any) -> Self

Retrieves or creates a timer object at the specified index.

This method ensures that you can access or create a timer object at any index in the _tracked_timers list without having to pass a direct reference. If the index is beyond the current length of _tracked_timers, the list is extended to accommodate the new index.

Parameters: index (int) – The index of the timer to access or create.
Returns: The timer object at the specified index.
Return type: _te.Self

average(*indices: int | None, return_type: Literal['timedelta']) -> timedelta****average(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Calculates the average time recorded across all ticks and tocks.

Parameters:
  • indices (int*, **optional*) – The index or indices to average the time for. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta” or “PreciseTimeDelta”. Defaults to “PreciseTimeDelta”.
Returns:

The average elapsed time across all ticks and tocks.
Return type:

PreciseTimeDelta | timedelta

classmethod complexity(func: Callable, input_generator: Iterable[tuple[tuple[Any, ...], dict[str, Any]]] | Generator[tuple[tuple[Any, ...], dict[str, Any]], None, None], matplotlib_pyplt: ModuleType | None = None) -> str

Measures the execution time of a function over a range of input sizes and estimates the time complexity. Too little data points will lead to bigger error rates. Around 100 data points is the sweet spot. The first argument/keyword argument you pass (in the generator) will be used as the x so you need to enable int conversion for that class.

Parameters: func (Callable): The function to measure. input_generator (Iterable): A generator that yields increasing input sizes (e.g., range). matplotlib_pyplt: The pyplot class from the matplotlib library.

Returns: str: Estimated time complexity (e.g., “O(N)”, “O(N^2)”, etc.).

delete(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****delete(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Deletes the timer at the specified indices.

Parameters:
  • indices (int*, **optional*) – The index or indices to delete. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta”, “PreciseTimeDelta”, or None. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s) or TimidTimer: The current instance of the timer.
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

elapsed(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****elapsed(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Records how much time has passed since the start of the timer (similar to elapsed).

Parameters:
  • indices (int*, **optional*) – The index or indices to check the time for. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta”, “PreciseTimeDelta”, or None. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s) or TimidTimer: The current instance of the timer.
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

end(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****end(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Ends the timer at the specified indices.

Parameters:
  • indices (int*, **optional*) – The index or indices where the timer should be ended. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta”, “PreciseTimeDelta”, or None. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s) or TimidTimer: The current instance of the timer.
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

enter(index: int | None = None) -> Self

Starts the timer and sets the index for thread-local storage when using the timer in a context manager.

Parameters: index (int*, **optional*) – The index of the timer to start. Defaults to None.
Returns: The current instance of the timer.
Return type: FlexTimer

classmethod from_(index: int) -> Self

Retrieves the timer object at the specified index, if it exists.

This method attempts to access an existing timer at the specified index in the _tracked_timers list. If no timer exists at the given index, it raises an IndexError.

Parameters: index (int) – The index of the timer to retrieve.
Returns: The timer object at the specified index.
Return type: _te.Self
Raises: IndexError – If no timer exists at the given index.

get(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****get(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Retrieves the elapsed time for the specified indices.

Parameters:
  • indices (int*, **optional*) – The index or indices to retrieve elapsed time for. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta” or “PreciseTimeDelta”. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s).
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

get_readable(index: int | None = None, format_to: PreciseTimeFormat = PreciseTimeFormat.SECONDS) -> str

Returns a readable string of the timer’s elapsed time.

Parameters:
  • index (int*, **optional*) – The index to retrieve the elapsed time for. Defaults to the first active timer.
  • format_to (TimeFormat*, **optional*) – The format to return the time in. Defaults to TimeFormat.SECONDS.
Returns:

A human-readable string of the elapsed time.
Return type:

str

interval(interval: float | int, count: int | Literal['inf'], callback: Callable[[...], Any], *, ms: bool = False, long: bool = False, args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None) -> Self

Starts an interval timer that triggers the callback at specified intervals. :param interval: The interval in seconds between each callback trigger. :param count: The number of times to trigger the callback. Defaults to “inf” (infinite). :param callback: The function to call at each interval. Defaults to print. :param ms: Flag that determines if the interval param should be treated as seconds or milliseconds. :param long: Flag that determines if the timer should be optimized for long wait times. :param args: The arguments for the callback function. Defaults to a message with the interval time. :param kwargs: The keyword arguments for the callback function. Defaults to None. :return:

lap(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****lap(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Records the time between the last tock and the current tock (similar to lap or split time).

Parameters:
  • indices (int*, **optional*) – The index or indices to check the time for. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta”, “PreciseTimeDelta”, or None. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s) or TimidTimer: The current instance of the timer.
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

load_state(state_bytes: bytes) -> None

Loads a previously saved state for all timers (excluding threads).

Parameters: state_bytes (bytes) – The serialized state to load.

static load_state_static(state_bytes: bytes) -> `FlexTimer <#chronix.FlexTimer>`_

Loads a previously saved state for all timers (excluding threads).

Parameters: state_bytes (bytes) – The serialized state to load.

loop(interval: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, index: int | None = None, daemon: bool = False) -> Self

Starts a repeating timer that triggers the specified function at set intervals indefinitely.

Parameters:
  • interval (float* or **int*) – The interval between each execution, in seconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • index (int*, **optional*) – The index for the timer in the internal list. Defaults to None (appends a new timer).
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The current instance of the timer.
Return type:

FlexTimer

loop_long(interval: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, index: int | None = None) -> Self

Starts a long-running repeating timer that triggers the specified function at set intervals indefinitely.

Parameters:
  • interval (float* or **int*) – The interval between each execution, in seconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • index (int*, **optional*) – The index for the timer in the internal list. Defaults to None (appends a new timer).
Returns:

The current instance of the timer.
Return type:

FlexTimer

loop_ms(interval_ms: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, index: int | None = None, daemon: bool = False) -> Self

Starts a repeating timer that triggers the specified function at set intervals in milliseconds indefinitely.

Parameters:
  • interval_ms (float* or **int*) – The interval between each execution, in milliseconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • index (int*, **optional*) – The index for the timer in the internal list. Defaults to None (appends a new timer).
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The current instance of the timer.
Return type:

FlexTimer

pause(*indices: int | None, for_seconds: int | float | None = None) -> Self

Pauses the timer at the specified indices.

Parameters:
  • indices (int*, **optional*) – The index or indices where the timer should be paused. Defaults to the first active timer.
  • for_seconds (float* or int, **optional*) – The duration to pause the timer in seconds. If not specified, pauses indefinitely.
Returns:

The current instance of the timer.
Return type:

FlexTimer

classmethod repeat(interval: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, iterations: int = 1, daemon: bool = False) -> Type[Self]

Repeatedly triggers a function at a specified interval for a set number of iterations.

Parameters:
  • interval (float* or **int*) – The time interval between each execution, in seconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • iterations (int*, **optional*) – The number of times to execute the function. Defaults to 1.
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The class itself.
Return type:

FlexTimer

classmethod repeat_long(interval: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, iterations: int = 1) -> Type[Self]

Repeatedly triggers a function at a specified interval for a long-running timer, for a set number of iterations.

Parameters:
  • interval (float* or **int*) – The time interval between each execution, in seconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • iterations (int*, **optional*) – The number of times to execute the function. Defaults to 1.
Returns:

The class itself.
Return type:

FlexTimer

classmethod repeat_ms(interval_ms: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, iterations: int = 1, daemon: bool = False) -> Type[Self]

Repeatedly triggers a function at a specified interval in milliseconds for a set number of iterations.

Parameters:
  • interval_ms (float* or **int*) – The time interval between each execution, in milliseconds.
  • function (Callable) – The function to execute at each interval.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • iterations (int*, **optional*) – The number of times to execute the function. Defaults to 1.
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The class itself.
Return type:

FlexTimer

restart(*indices: int | None, return_type: Literal['timedelta']) -> list[timedelta] | timedelta****restart(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> list[`PreciseTimeDelta <#chronix.PreciseTimeDelta>`_] | `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Restarts an already running timer, skipping the whole .stop() .get_readable() .delete() boilerplate.

Parameters:
  • indices (int*, **optional*) – The index or indices where the timer should be ended. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta”, “PreciseTimeDelta”, or None. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time(s) or TimidTimer: The current instance of the timer.
Return type:

list[PreciseTimeDelta | timedelta] | PreciseTimeDelta | timedelta

resume(*indices: int | None) -> Self

Resumes the timer at the specified indices.

Parameters: indices (int*, **optional*) – The index or indices where the timer should be resumed. Defaults to the first paused timer.
Returns: The current instance of the timer.
Return type: FlexTimer

save_state() -> bytes

Saves the current state of all timers (excluding threads).

Returns: A serialized representation of the timer’s state.
Return type: bytes

static schedule_task_at(time_str, callback: ~collections.abc.Callable[[...], ~typing.Any] = <built-in function print>, args: tuple[~typing.Any, ...] = (), kwargs: dict[str, ~typing.Any] | None = None) -> None

Schedules a task to run at a specified time of day, either today or the next day if the time has passed.

Parameters:
  • time_str (str) – The time of day to run the task, in “HH:MM” or “HH:MM:SS” format.
  • callback (Callable*, **optional*) – The function to run when the scheduled time is reached. Defaults to print.
  • args (tuple*, **optional*) – The arguments for the callback function. Defaults to a message with the scheduled time.
  • kwargs (dict*, **optional*) – The keyword arguments for the callback function. Defaults to None.

show_laps(index: int | None = None, format_to: PreciseTimeFormat = PreciseTimeFormat.SECONDS) -> str

Displays the recorded times for each tick and tock.

Parameters:
  • index (int*, **optional*) – The index to display tick and tock times for. Defaults to the first active timer.
  • format_to (int*, **optional*) – The time format to use for displaying the times. Defaults to TimeFormat.SECONDS.
Returns:

The tick tocks of the index in a readable string format.
Return type:

str

classmethod single_shot(wait_time: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, daemon: bool = False) -> Type[Self]

Executes a single-shot timer that triggers the specified function after a set amount of time.

Parameters:
  • wait_time (float* or **int*) – The time to wait before executing the function, in seconds.
  • function (Callable) – The function to execute after the timer ends.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The class itself.
Return type:

FlexTimer

classmethod single_shot_long(wait_time: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None) -> Type[Self]

Executes a long-running single-shot timer that triggers the specified function after a set amount of time.

Parameters:
  • wait_time (float* or **int*) – The time to wait before executing the function, in seconds.
  • function (Callable) – The function to execute after the timer ends.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
Returns:

The class itself.
Return type:

FlexTimer

classmethod single_shot_ms(wait_time_ms: int | float, function: Callable[[...], Any], args: tuple[Any, ...] = (), kwargs: dict[str, Any] | None = None, daemon: bool = False) -> Type[Self]

Executes a single-shot timer that triggers the specified function after a set amount of time in milliseconds.

Parameters:
  • wait_time_ms (float* or **int*) – The time to wait before executing the function, in milliseconds.
  • function (Callable) – The function to execute after the timer ends.
  • args (tuple*, **optional*) – Arguments to pass to the function. Defaults to an empty tuple.
  • kwargs (dict*, **optional*) – Keyword arguments to pass to the function. Defaults to None.
  • daemon (bool*, **optional*) – Whether to run the timer thread as a daemon. Defaults to False.
Returns:

The class itself.
Return type:

FlexTimer

start(*indices: int | None, start_at: int | float = 0) -> Self

Starts the timer at the specified indices.

Parameters:
  • indices (int*, **optional*) – The index or indices where the timer should be started. Defaults to the next available index.
  • start_at (float* or int, **optional*) – The start time offset in seconds. Defaults to 0.
Returns:

The current instance of the timer.
Return type:

FlexTimer

stop(*indices: int | None) -> Self

Stops the timer at the specified indices.

Parameters: indices (int*, **optional*) – The index or indices where the timer should be stopped. Defaults to the first active timer.
Returns: The current instance of the timer.
Return type: FlexTimer

stop_loop(index: int | None = None, amount: int | None = None) -> Self

Stops the specified timer(s) and removes them from the internal list.

Parameters:
  • index (int*, **optional*) – The index of the timer to stop. Defaults to None (stops the first timer).
  • amount (int*, **optional*) – The number of timers to stop. Defaults to 1.
Returns:

The current instance of the timer.
Return type:

FlexTimer

stop_loops(*indices: int | None, not_exists_okay: bool = False) -> Self

Stops the specified timer(s) and removes them from the internal list.

Parameters:
  • indices (int*, **optional*) – The indices of the timers to stop. Defaults to None (stops the first timer).
  • not_exists_okay (bool) – Raise IndexError if index does not exist and this is False.
Returns:

The current instance of the timer.
Return type:

FlexTimer

static system_time() -> str

This method retrieves the current system time and returns it in “HH:MM:SS” format. :return: The current system time.

tally(*indices: int | None, return_type: Literal['timedelta']) -> timedelta****tally(*indices: int | None, return_type: Literal['PreciseTimeDelta']) -> `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Returns the total time recorded across all ticks and tocks.

Parameters:
  • indices (int*, **optional*) – The index or indices to tally the time for. Defaults to the first active timer.
  • return_type (str*, **optional*) – The format to return the time in, either “timedelta” or “PreciseTimeDelta”. Defaults to “PreciseTimeDelta”.
Returns:

The total elapsed time across all ticks and tocks.
Return type:

PreciseTimeDelta | timedelta

classmethod test_delay(amount: int | float, return_type: Literal['timedelta']) -> timedelta****classmethod test_delay(amount: int | float, return_type: Literal['PreciseTimeDelta']) -> `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Tests a delay of a specified amount of time and returns the elapsed time.

Parameters:
  • amount (float* or int, **optional*) – The amount of time to delay, in seconds. Defaults to 0.
  • return_type (str*, **optional*) – The format to return the elapsed time in, either “timedelta” or “PreciseTimeDelta”. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time during the delay.
Return type:

PreciseTimeDelta | timedelta

classmethod test_delay_ms(amount_ms: int | float, return_type: Literal['timedelta']) -> timedelta****classmethod test_delay_ms(amount_ms: int | float, return_type: Literal['PreciseTimeDelta']) -> `PreciseTimeDelta <#chronix.PreciseTimeDelta>`_

Tests a delay of a specified amount of time in milliseconds and returns the elapsed time.

Parameters:
  • amount_ms (float* or int, **optional*) – The amount of time to delay, in milliseconds. Defaults to 0.
  • return_type (str*, **optional*) – The format to return the elapsed time in, either “timedelta” or “PreciseTimeDelta”. Defaults to “PreciseTimeDelta”.
Returns:

The elapsed time during the delay.
Return type:

PreciseTimeDelta | timedelta

classmethod time(time_format: PreciseTimeFormat = PreciseTimeFormat.SECONDS) -> CallableCallable[[...], Any, Callable...], Any

A decorator to measure the execution time of a function and print the result.

This decorator uses the TimidTimer class to time how long a specific function takes to execute. The result is printed in the specified time format, and the function’s return value is passed through.

Parameters: time_format (TimeFormat*, **optional*) – The time format to display the elapsed time. Defaults to TimeFormat.SECONDS.
Returns: A decorator function.
Return type: Callable

wait(seconds: int | float = 0) -> Self

Pauses execution for a specified number of seconds.

Parameters: seconds (int*, **optional*) – The time to wait in seconds. Defaults to 0.
Returns: The current instance of the timer.
Return type: FlexTimer

wait_ms(milliseconds: int | float = 0) -> Self

Pauses execution for a specified number of milliseconds.

Parameters: milliseconds (int*, **optional*) – The time to wait in milliseconds. Defaults to 0.
Returns: The current instance of the timer.
Return type: FlexTimer

classmethod wait_ms_static(milliseconds: int | float = 0) -> Type[Self]

Pauses execution for a specified number of milliseconds, statically.

Parameters: milliseconds (int*, **optional*) – The time to wait in milliseconds. Defaults to 0.
Returns: The class itself.
Return type: FlexTimer

classmethod wait_static(seconds: int | float = 0) -> Type[Self]

Pauses execution for a specified number of seconds, statically.

Parameters: seconds (int*, **optional*) – The time to wait in seconds. Defaults to 0.
Returns: The class itself.
Return type: FlexTimer

warmup_timer(rounds: int = 300) -> Self

Warms up the timer by running short intervals repeatedly.

Parameters: rounds (int*, **optional*) – The number of warmup rounds. Defaults to 300.
Returns: The current instance of the timer.
Return type: FlexTimer

class chronix.MonotonicFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.MonotonicFTimerNS(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.PerfFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.PerfFTimerNS(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.PreciseTimeDelta(years: float = 0, months: float = 0, weeks: float = 0, days: float = 0, hours: float = 0, minutes: float = 0, seconds: float = 0, milliseconds: float = 0, microseconds: float = 0, nanoseconds: float = 0, picoseconds: float = 0, femtoseconds: float = 0, attoseconds: float = 0, max_precision: int = 10)

Bases: object

A class to represent small and precise time differences, allowing arithmetic operations and formatted output. This class handles time values from years to attoseconds and stores the total time in nanoseconds internally.

negative

Indicates if the time difference is negative.

Type: bool

_total_nanoseconds

The total time difference in nanoseconds, including fractional precision.

Type: float

max_precision

Number of decimal digits to display.

Type: int

DAYS_IN_MONTH = 30.44

DAYS_IN_WEEK = 7

DAYS_IN_YEAR = 365.25

NANOS_PER_DAY = 86400000000000.0

NANOS_PER_HOUR = 3600000000000.0

NANOS_PER_MICROSECOND = 1000.0

NANOS_PER_MILLISECOND = 1000000.0

NANOS_PER_MINUTE = 60000000000.0

NANOS_PER_MONTH = 2630016000000000.0

NANOS_PER_SECOND = 1000000000.0

NANOS_PER_WEEK = 604800000000000.0

NANOS_PER_YEAR = 3.15576e+16

SECONDS_IN_DAY = 86400

SECONDS_IN_HOUR = 3600

SECONDS_IN_MINUTE = 60

__init__(years: float = 0, months: float = 0, weeks: float = 0, days: float = 0, hours: float = 0, minutes: float = 0, seconds: float = 0, milliseconds: float = 0, microseconds: float = 0, nanoseconds: float = 0, picoseconds: float = 0, femtoseconds: float = 0, attoseconds: float = 0, max_precision: int = 10) -> None

Initializes the PreciseTimeDelta by converting all time formats into nanoseconds and summing them up.

Parameters:
  • years (float) – Number of years in the time difference.
  • months (float) – Number of months in the time difference.
  • weeks (float) – Number of weeks in the time difference.
  • days (float) – Number of days in the time difference.
  • hours (float) – Number of hours in the time difference.
  • minutes (float) – Number of minutes in the time difference.
  • seconds (float) – Number of seconds in the time difference.
  • milliseconds (float) – Number of milliseconds in the time difference.
  • microseconds (float) – Number of microseconds in the time difference.
  • nanoseconds (float) – Number of nanoseconds in the time difference.
  • picoseconds (float) – Number of picoseconds in the time difference.
  • femtoseconds (float) – Number of femtoseconds in the time difference.
  • attoseconds (float) – Number of attoseconds in the time difference.
  • max_precision (int) – Number of decimal digits to display for fractional seconds.

attoseconds() -> float

Returns the number of attoseconds in the time difference.

Returns: The number of attoseconds.
Return type: float

days() -> float

Returns the number of days in the time difference.

Returns: The number of days.
Return type: float

femtoseconds() -> float

Returns the number of femtoseconds in the time difference.

Returns: The number of femtoseconds.
Return type: float

classmethod from_timedelta(td: timedelta) -> Self

Convert a timedelta object into nanoseconds. :param td: The timedelta object to convert. :return: The equivalent PreciseTimeDelta.

hours() -> float

Returns the number of hours in the time difference.

Returns: The number of hours.
Return type: float

microseconds() -> float

Returns the number of microseconds in the time difference.

Returns: The number of microseconds.
Return type: float

milliseconds() -> float

Returns the number of milliseconds in the time difference.

Returns: The number of milliseconds.
Return type: float

minutes() -> float

Returns the number of minutes in the time difference.

Returns: The number of minutes.
Return type: float

months() -> float

Returns the number of months in the time difference.

Returns: The number of months.
Return type: float

nanoseconds() -> float

Returns the number of nanoseconds in the time difference.

Returns: The number of nanoseconds.
Return type: float

classmethod parse_timedelta_string(td_str: str) -> Self

Convert a timedelta-like string format (e.g., ‘00:00:00.123456789’) into nanoseconds.

Parameters: td_str (str) – A string in the form ‘HH:MM:SS.fffffffff’
Returns: Equivalent nanoseconds.
Return type: int

picoseconds() -> float

Returns the number of picoseconds in the time difference.

Returns: The number of picoseconds.
Return type: float

seconds() -> float

Returns the number of seconds in the time difference.

Returns: The number of seconds.
Return type: float

to_clock_string() -> str

Convert nanoseconds into a human-readable format with arbitrary precision, displaying the time in a format like 00:00:00.0000000000.

Returns: Human-readable string with days, weeks, months, and years if applicable.
Return type: str

to_readable(format_to: PreciseTimeFormat | None = None, max_precision: int | None = None) -> str

Convert a given timedelta to a human-readable string based on the specified time format. If no format is provided, it defaults to seconds. :param format_to: The time unit format to convert to. If None, defaults to SECONDS. :param max_precision: :return: A human-readable string representing the timedelta in the specified time format.

to_timedelta() -> timedelta

Convert nanoseconds into a timedelta object. :return: Corresponding timedelta object.

weeks() -> float

Returns the number of weeks in the time difference.

Returns: The number of weeks.
Return type: float

years() -> float

Returns the number of years in the time difference.

Returns: The number of years.
Return type: float

class chronix.PreciseTimeFormat(*values)

Bases: Enum

YEARS

Constant representing the time unit ‘years’.

Type: int

MONTHS

Constant representing the time unit ‘months’.

Type: int

WEEKS

Constant representing the time unit ‘weeks’.

Type: int

DAYS

Constant representing the time unit ‘days’.

Type: int

HOURS

Constant representing the time unit ‘hours’.

Type: int

MINUTES

Constant representing the time unit ‘minutes’.

Type: int

SECONDS

Constant representing the time unit ‘seconds’.

Type: int

MILLISECS

Constant representing the time unit ‘milliseconds’.

Type: int

MICROSECS

Constant representing the time unit ‘microseconds’.

Type: int

NANOSECS

Constant representing the time unit ‘nanoseconds’.

Type: int

PICOSECS

Constant representing the time unit ‘picoseconds’.

Type: int

FEMTOSECS

Constant representing the time unit ‘femtoseconds’.

Type: int

ATTOSECS

Constant representing the time unit ‘attoseconds’.

Type: int

ATTOSECS = 2048

DAYS = 4

FEMTOSECS = 1024

HOURS = 8

MICROSECS = 128

MILLISECS = 64

MINUTES = 16

MONTHS = 1

NANOSECS = 256

PICOSECS = 512

SECONDS = 32

WEEKS = 2

YEARS = 0

class chronix.ThreadFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.ThreadFTimerNS(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.TimeFTimer(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

class chronix.TimeFTimerNS(start_at: int | float = 0, start_now: bool = True)

Bases: FlexTimer

Clone this wiki locally