py-smarttimer 0.1.0

Tiny, friendly timing utilities for Python code blocks and functions.

⏱️ smarttimer

Tiny, friendly timing utilities for Python code blocks and functions. Perfect for quick performance checks and micro-benchmarks.

🚀 Install

pip install py-smarttimer

📖 Quick Start

from smarttimer import time_block, benchmark, measure, compare

🎯 Features

⏲️ Time any code block

from smarttimer import time_block

with time_block("data processing"):
    df = pd.read_csv("large_file.csv")
    result = df.groupby("category").sum()

[smarttimer] data processing took 2.3451s

🎪 Benchmark functions with a decorator

from smarttimer import benchmark

@benchmark
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

result = fibonacci(30)  # Automatically prints timing

📊 Measure with statistics

from smarttimer import measure

def matrix_multiply(a, b):
    return [[sum(x*y for x,y in zip(row,col)) for col in zip(*b)] for row in a]

# Run 10 times with 2 warmup runs
result, elapsed = measure(
    matrix_multiply,
    [[1,2],[3,4]], [[5,6],[7,8]],
    repeats=10,
    warmup=2
)

🏁 Compare multiple functions

from smarttimer import compare

def bubble_sort(arr):
    n = len(arr)
    for i in range(n):
        for j in range(0, n-i-1):
            if arr[j] > arr[j+1]:
                arr[j], arr[j+1] = arr[j+1], arr[j]
    return arr

def quick_sort(arr):
    if len(arr) <= 1:
        return arr
    pivot = arr[len(arr) // 2]
    left = [x for x in arr if x < pivot]
    middle = [x for x in arr if x == pivot]
    right = [x for x in arr if x > pivot]
    return quick_sort(left) + middle + quick_sort(right)

# Compare performance
data = [64, 34, 25, 12, 22, 11, 90]
compare(bubble_sort, quick_sort, args=(data.copy(),), repeats=100)

[smarttimer] Function comparison (100 runs):
  quick_sort: 0.000012s ± 0.000003s (fastest)
  bubble_sort: 0.000089s ± 0.000012s (7.4x slower)

🔍 Silent timing for custom logic

from smarttimer import TimingContext

with TimingContext() as timer:
    expensive_computation()

if timer.elapsed > 1.0:
    print(f"Slow operation detected: {timer.elapsed:.2f}s")

💾 Memory profiling (optional)

from smarttimer import profile_memory

@profile_memory
def load_large_dataset():
    return [i**2 for i in range(1_000_000)]

data = load_large_dataset()

[smarttimer] load_large_dataset took 0.1234s, memory: 45.2MB → 82.1MB (+36.9MB)

Requires pip install psutil for memory profiling

🛠️ Advanced Usage

Disable timing conditionally

DEBUG = False

with time_block("debug operation", enabled=DEBUG):
    debug_heavy_computation()  # Only timed when DEBUG=True

Custom output and precision

import sys
from smarttimer import benchmark

@benchmark(precision=6, output=sys.stderr)
def precise_operation():
    return sum(i**0.5 for i in range(10000))

Warmup runs for accurate benchmarks

# Skip first 3 runs to avoid cold start effects
result, time_taken = measure(
    compiled_function,
    args,
    repeats=20,
    warmup=3
)

🎨 Why smarttimer?

• Zero dependencies (except optional psutil for memory profiling)
• Minimal overhead - uses time.perf_counter() for precision
• Flexible - works as context manager, decorator, or function
• Clean output - consistent, readable timing reports
• Production ready - disable timing in production with enabled=False

📦 API Reference

Function	Purpose	Returns
time_block(name)	Time a code block	Context manager
@benchmark	Time a function call	Decorated function
measure(func, *args, repeats=1)	Benchmark with repeats	(result, elapsed)
compare(*funcs, args=(), repeats=5)	Compare functions	Statistics dict
TimingContext()	Silent timing	Context with .elapsed
@profile_memory	Time + memory usage	Decorated function

🤝 Contributing

Found a bug? Want a feature? Open an issue or submit a PR!

📄 License

MIT License - see LICENSE file for details.

---