v0.5.0

[HH-MWB]

Release v0.5.0: New Data Model and BDD Test Suite

🎉 Overview

This release evolves the existing Timer with a new data model. Each run now produces a Measurement with both wall-clock and CPU time (as TimeSpan), plus optional metadata.

ElapsedTime, Stopwatch, and related options (count_sleep, custom storage, Timer.duration/durations) are removed. Tests move from pytest to Behave BDD.

This is a breaking release — migration to the new API is required.

✨ Key Features

🚀 Dual Time per Run (Major Change)

• v0.4 recorded one kind of time per run: wall-clock or CPU, chosen via count_sleep.
• v0.5 records both wall-clock and CPU time for every run. Use m.wall_time and m.cpu_time (or measurement.cpu_time for process-only semantics similar to v0.4’s count_sleep=False).

📐 Measurement and TimeSpan

• Context manager: with Timer() as m: or async with Timer() as m: yields a Measurement; on exit, m.wall_time and m.cpu_time are TimeSpan instances (with .duration in nanoseconds and .timedelta).
• Decorator: @Timer() appends one Measurement per call to the wrapped callable’s measurements deque. Access via func.measurements[-1].wall_time / .cpu_time.
• TimeSpan: Immutable interval with start, end, duration (nanoseconds), and .timedelta.
• Measurement: Holds wall_time, cpu_time (both TimeSpan), and optional metadata.

Example Usage:

# Block timing
from timerun import Timer
with Timer() as m:
    pass  # code block to be measured
print(m.wall_time.timedelta, m.cpu_time.timedelta)

# Function timing
@Timer()
def func():
    return
func()
print(func.measurements[-1].wall_time.timedelta)

🔧 Improvements

CI/CD

• ✅ CI workflow updated for Behave-based test suite
• ✅ Pre-commit and project config aligned with new structure

Code Quality

• ✅ Single-file, stdlib-only implementation (no runtime dependencies)
• ✅ Wall-clock via perf_counter_ns, CPU time via process_time_ns
• ✅ Thread-safe; supports async; one Measurement per block or per call
• ✅ Strict mypy, ruff, bandit, pylint; type hints throughout

Testing

• ✅ BDD with Behave: Gherkin features and step implementations replace pytest
• ✅ Features: block timing, function timing, measurement, time span, version
• ✅ Legacy pytest tests removed (test_elapsedtime, test_stopwatch, test_timer)

Documentation

• ✅ README Quickstart and prerequisites (Python 3.10+) updated to match new API
• ✅ Docstrings and examples aligned with Quickstart and current API

📊 Statistics

• Files changed: 27
• Additions: +1,600 lines
• Deletions: -1,555 lines
• Net change: +45 lines

🧪 Testing

All behavior is covered by Behave, including:

• ✅ Code block timing (sync and async context manager)
• ✅ Function timing (sync/async functions and generators)
• ✅ Measurement and TimeSpan behavior

🔄 Breaking Changes

Yes — Previous API is removed or changed.

Removed: ElapsedTime, Stopwatch, Timer.duration / Timer.durations, count_sleep, storage, max_len on Timer (replaced by maxlen on decorator only), NoDurationCapturedError, TimeRunError, AppendableSequence protocol.

New: Context manager yields Measurement (with wall_time, cpu_time, metadata). Decorator adds measurements deque on the wrapped callable. Public types Measurement, TimeSpan. Timer parameters: metadata, maxlen (decorator only).

📝 Migration Guide

• Block timing: Replace with Timer() as timer with with Timer() as m. Use m.wall_time.timedelta / m.cpu_time.timedelta (or m.wall_time.duration / m.cpu_time.duration for nanoseconds) instead of timer.duration.
• Multiple block runs: In v0.4, repeated with timer: blocks filled timer.durations. In v0.5 each with Timer() as m yields one Measurement; collect them yourself (e.g. append to a list) if you need a history.
• Function timing: Replace timer = Timer(); @timer and timer.duration with @Timer() and func.measurements[-1].wall_time / func.measurements[-1].cpu_time (use .timedelta or .duration on those for the value).
• Exclude sleep (v0.4 count_sleep=False): v0.5 always records both times; use measurement.cpu_time for process-only time.
• Custom storage / Stopwatch / ElapsedTime: There is no direct replacement; these are removed. Use Measurement and TimeSpan (and the measurements deque on decorated callables) for the new workflow.

See README Quickstart for full examples.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (24add9e) to head (8f4eb12).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main        #5   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         1           
  Lines           88       101   +13     
  Branches         5         0    -5     
=========================================
+ Hits            88       101   +13     

Flag	Coverage Δ
python3.10	100.00% <100.00%> (ø)
python3.11	100.00% <100.00%> (ø)
python3.12	100.00% <100.00%> (ø)
python3.13	100.00% <100.00%> (ø)
python3.14	100.00% <100.00%> (ø)
python3.9	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.