How to use timing

timing provides simple and powerful timing utilities for measuring execution time, collecting statistics, and analyzing performance.

• Everything runs using Sktimer

Statistical timer that collects timing measurements and provides comprehensive statistics (mean, median, stdev, percentiles). Has more statistics that timeit.

• timethis

Decorator for timing function executions with automatic statistics collection.

• TimeThis

Context manager for timing code blocks with automatic start/stop.

With timethis and TimeThis you have 100% coverage. Anything and everything can be timed with one line of code.

Includes:

• Thread safety
• Deep statistical analysis
• One-line setup
• Native async support

Importing

from suitkaise import timing

from suitkaise.timing import Sktimer, TimeThis, timethis, time, sleep, elapsed, clear_global_timers

Simple Functions

time()

Get the current Unix timestamp.

from suitkaise import timing

start_time = timing.time()

Wraps time.time() so that you don't have to import both timing and time.

Returns

float: Current Unix timestamp.

sleep()

Sleep the current thread for a given number of seconds.

from suitkaise import timing

# sleep for 2 seconds
timing.sleep(2)

# returns current time after sleeping
end_time = timing.sleep(2)

Arguments

seconds: Number of seconds to sleep.

• float
• Required

Returns

float: Current time after sleeping.

Async Support

Use .asynced() for async contexts.

# in an async function
end_time = await timing.sleep.asynced()(2)

Uses asyncio.sleep internally.

elapsed()

Get the elapsed time between two timestamps.

from suitkaise import timing

start_time = timing.time()
timing.sleep(2)
end_time = timing.time()

# with two times
elapsed = timing.elapsed(start_time, end_time)  # 2.0

# with one time (uses current time as end)
elapsed = timing.elapsed(start_time)

Arguments

time1: First timestamp.

• float
• Required

time2: Second timestamp.

• float | None = None
• If None, uses current time

Returns

float: Absolute elapsed time in seconds.

Note: Order doesn't matter - always returns positive elapsed time.

from suitkaise import timing

timer = timing.Sktimer()

for i in range(100):
    timer.start()
    do_work()
    timer.stop()

print(f"Mean: {timer.mean:.3f}s")
print(f"Std Dev: {timer.stdev:.3f}s")
print(f"95th percentile: {timer.percentile(95):.3f}s")

timer.start()

timer.start()
do_work()
elapsed = timer.stop()  # returns elapsed time, records it

timer.start()
try:
    result = risky_operation()
    timer.stop()  # record successful timing
except Exception:
    timer.discard()  # don't record failed timing

timer.start()

for i in range(100):
    do_work()
    timer.lap()  # records time since last lap/start, continues timing

timer.discard()  # don't record the 101st measurement still running

print(timer.mean)  # 100 measurements recorded

timer.start()
do_work()

timer.pause()
user_input = input("Continue? ")  # not counted in timing
timer.resume()

do_more_work()
elapsed = timer.stop()  # only counts work, not user input

timer.resume()

timer.add_time(1.5)
timer.add_time(2.3)
timer.add_time(1.8)

print(timer.mean)  # 1.867

timer.set_max_times(100)  # keep only last 100 measurements
timer.set_max_times(None)  # keep all measurements

timer.reset()  # clears all measurements, like a new Sktimer()

first_time = timer.get_time(0)
last_time = timer.get_time(-1)

p50 = timer.percentile(50)   # median
p95 = timer.percentile(95)   # 95th percentile
p99 = timer.percentile(99)   # 99th percentile

snapshot = timer.get_statistics()

# snapshot won't change even if timer continues
timer.start()
do_more_work()
timer.stop()

# snapshot still has old values
print(snapshot.mean)

p95 = snapshot.percentile(95)

first = snapshot.get_time(0)

timethis Decorator

Decorator that times function executions and records results in a Sktimer.

from suitkaise import timing

@timing.timethis()
def quick_function():
    # ...
    pass

quick_function()

# access the auto-created timer
print(f"Last time: {quick_function.timer.most_recent:.3f}s")

# calling multiple times builds statistics
for i in range(100):
    quick_function()

print(f"Mean: {quick_function.timer.mean:.3f}s")

Arguments

timer: Sktimer to accumulate timing data in.

• Sktimer | None = None
• If None, creates an auto-named global timer attached to the function

threshold: Minimum elapsed time to record.

• float = 0.0
• Times below this threshold are discarded

max_times: Keep only the most recent N measurements.

• int | None = None

Auto-Created Timers

When no timer is provided, the decorator creates a global timer with a naming convention:

• Module-level functions: module_function_timer
• Class methods: module_ClassName_method_timer

The timer is attached to the function as .timer:

@timing.timethis()
def my_function():
    pass

my_function()
print(my_function.timer.mean)

Shared Timer

Use a single timer across multiple functions:

perf_timer = timing.Sktimer()
perf_timer.set_max_times(1000)

@timing.timethis(perf_timer)
def multiply(a, b):
    return a * b

@timing.timethis(perf_timer)
def divide(a, b):
    return a / b

for a, b in zip(range(1000), range(1, 1001)):
    multiply(a, b)
    divide(a, b)

print(f"Combined mean: {perf_timer.mean:.6f}s")

Stacked Decorators

Use both a shared timer and a function-specific timer:

perf_timer = timing.Sktimer()
overall_timer = timing.Sktimer()

# 2 stacked decorators on the same function
@timing.timethis(perf_timer)
@timing.timethis()
def multiply(a, b):
    return a * b

# supports infinite stacking
@timing.timethis(overall_timer)
@timing.timethis(perf_timer)
@timing.timethis()
def divide(a, b):
    return a / b

# ... call functions ...

# combined stats
print(f"Combined mean: {perf_timer.mean:.6f}s")

# individual stats
print(f"Multiply mean: {multiply.timer.mean:.6f}s")
print(f"Divide mean: {divide.timer.mean:.6f}s")

TimeThis Context Manager

Context manager for timing code blocks with automatic timer management.

from suitkaise import timing

with timing.TimeThis() as timer:
    do_work()

print(f"Time taken: {timer.most_recent:.3f}s")

Constructor

Arguments

timer: Sktimer instance to use.

• Sktimer | None = None
• If None, creates a new Sktimer

threshold: Minimum elapsed time to record.

• float = 0.0
• times below this threshold are discarded

One-Use Timer

For quick, one-off measurements:

with timing.TimeThis() as timer:
    compress_file_with_gzip("data.csv")

print(f"Compression took: {timer.most_recent:.3f}s")

Shared Timer

For accumulating statistics across multiple runs:

api_timer = timing.Sktimer()

with timing.TimeThis(api_timer):
    response = requests.get("https://api.example.com/users")

with timing.TimeThis(api_timer):
    response = requests.get("https://api.example.com/posts")

print(f"Average API time: {api_timer.mean:.3f}s")

Pause and Resume

with timing.TimeThis() as timer:
    results = database.query("SELECT * FROM users")
    
    timer.pause()
    user_wants_export = input("Export to CSV? (y/n): ")
    timer.resume()
    
    if user_wants_export.lower() == 'y':
        export_to_csv(results)

print(f"Database operation took: {timer.most_recent:.3f}s (excluding user input)")

Methods

pause(): Pause timing.

resume(): Resume timing.

lap(): Record a lap and continue timing.

clear_global_timers()

Clear all auto-created global timers used by the @timethis() decorator.

from suitkaise import timing

# ... many @timethis() decorated functions called ...

# clear data from auto-created timers to save resources
timing.clear_global_timers()

Useful for:

• Long-lived processes
• Test environments
• Releasing references and starting fresh

Thread Safety

All Sktimer operations are thread-safe.

• Each thread gets its own timing session
• Multiple threads can time concurrently
• Statistics are aggregated across all threads

import threading

timer = timing.Sktimer()

def worker():
    for _ in range(100):
        timer.start()
        do_work()
        timer.stop()

threads = [threading.Thread(target=worker) for _ in range(4)]
for t in threads:
    t.start()
for t in threads:
    t.join()

# 400 total measurements across all threads (4 threads * 100 iterations)
print(f"Total measurements: {timer.num_times}")
print(f"Mean: {timer.mean:.3f}s")