API Reference

If you are looking for information on a specific class or method, this part of the documentation is for you.

Timers

class pytimers.Timer(triggers: Optional[Iterable[BaseTrigger | Callable[[float, bool, Optional[str]], Any]]] = None)

Initializes Timer object with a set of triggers to be applied after the timer finishes.

Parameters:

triggers – An iterable of callables to be called after the timer finishes. All triggers should accept keywords arguments duration_s: float, decorator: bool, label: str. PyTimers also provide an abstract class BaseTrigger to help with trigger interface implementation. See the BaseTrigger for more details. Any instance of BaseTrigger subclass is a valid trigger and can be passed to the argument triggers.

label(text: str) → Timer

Sets label for the next timed code block. This label propagates to all triggers once the context managers is closed.

Parameters:

text – Code block label text.

Returns:

Returns self. This makes possible to call the method directly inside context manager with statement.

named(name: str) → Timer

This method only ensures backwards compatibility. Use pytimers.Timer.label() instead.

Deprecated since version 3.0.

class pytimers.clock.Clock(label: Optional[str])

current_duration(precision: Optional[int] = None) → float

Calculates the current duration elapsed since the clock was started. This property can be used inside a timed code block.

Parameters:

precision – Number of decimal places of the returned time. If set to None the full precision is returned.

Returns:

Measured time in seconds between start of the clock and the method call.

duration(precision: Optional[int] = None) → float

Exposes measured time of the clock. You can use this method to access the measured time even after the context manager is closed. This property should never be used directly inside a timed code block as it would raise an pytimers.exceptions.ClockStillRunning exception.

Parameters:

precision – Number of decimal places of the returned time. If set to None the full precision is returned.

Returns:

Measured time in seconds between start and stop of the clock.

Raises:

pytimers.exceptions.ClockStillRunning – Clock has to be stopped before accessing elapsed time.

stop() → None

Stops the running clock.

exception pytimers.exceptions.ClockStillRunning

Custom exception to be raised while accessing properties of pytimers.clock.Clock before being stopped.

Triggers

class pytimers.BaseTrigger

This class provides timer trigger abstraction. Custom triggers can be implemented using simple functions but subclassing this abstract class is the preferred way. Any custom implementation has to override pytimers.BaseTrigger.__call__() method where the trigger logic should be provided.

abstract __call__(duration_s: float, decorator: bool, label: Optional[str] = None) → None

This is a trigger action entrypoint. This method is called in pytimers.Timer once the timer stops.

Parameters:

• duration_s – The measured duration in seconds.

• decorator – True if the timer was used as a decorator for callable. False if used as a context manager for timing code blocks.

• label – The label of the measured code block provided by client before entering the context manager. For decorator usage this value is set to the callable name.

static humanized_duration(duration_s: float, precision: int = 0) → str

This method provides formatter for human-readable duration with hours being the highest level of the format.

Parameters:

• duration_s – The duration in seconds to be formatted.

• precision – Number of decimal places for milliseconds.

Returns:

Human-readable duration as a string.

class pytimers.LoggerTrigger(level: int = 20, template: str = 'Finished ${label} in ${humanized_duration} [${duration}s].', precision: int = 3, humanized_precision: int = 3, default_code_block_label: str = 'code block')

Provided trigger class for logging the measured duration using std logging library.

Parameters:

• level – Log level (as understood by the standard logging library logging) used for the message.

• template – Message template string containing placeholders for label, duration and/or humanized_duration.

• precision – Number of decimal places for the message duration in seconds.

• humanized_precision – Number of decimal places for milliseconds in human-readable duration in the message.

• default_code_block_label – Label used for code blocks with missing label.