v0.6.0

[HH-MWB]

Release v0.6.0: Callbacks, Docs Site, and Project Health

🎉 Overview

This release adds observability hooks to the Timer: optional on_start and on_end callbacks so each measurement can be logged, sent to OpenTelemetry, or enqueued to a metrics pipeline. It also ships a documentation site (Zensical, deployed to GitHub Pages), community and repo policy (Code of Conduct, SECURITY, issue/PR templates), CI improvements (pip-audit, 100% coverage enforcement, standardized workflows), and a restructured Makefile with clearer init/clean and contributing docs.

API change: Timer constructor is keyword-only (Timer(metadata=..., maxlen=...)). Existing Timer() and Timer(metadata=...) usage is unchanged; positional Timer(some_dict) is no longer valid.

✨ Key Features

🚀 Callbacks on Start and End (New)

• on_start(measurement) — Called once per measurement when timing is about to start. The Measurement has metadata set (deep copy of the Timer’s metadata); wall_time and cpu_time are None. Can be use for logging, setting span context, or enriching metadata from context variables.
• on_end(measurement) — Called once per measurement when timing has just ended. The Measurement has wall_time and cpu_time set. Can be use for logging duration, sending to OpenTelemetry, or enqueueing to a metrics pipeline.

Note: Callbacks are synchronous only. For async exporters, schedule work from the callback (e.g. asyncio.create_task(export(m)) in an async context, or use a thread/queue).

Example:

from timerun import Timer

with Timer(on_end=lambda m: print(m.wall_time.timedelta)):
    pass  # code block to be measured

See the Callbacks guide and Share results recipe for patterns (logging, file, OpenTelemetry).

🔧 Improvements

Documentation

• ✅ Docs site — Zensical-based site with guide (Timer, Measurement, TimeSpan, metadata, callbacks, block/function timing), recipes (analyze results, metadata, share results), and “Why TimeRun” about page. Deployed to GitHub Pages on push to main.
• ✅ README — Trimmed setup copy; added callbacks quick example; link to docs site for value proposition and installation from source.

CI/CD

• ✅ CI workflow — Lint job (pre-commit on 3.10); Test job with pip-audit, 100% coverage enforced (coverage report + fail_under = 100), matrix Python 3.10–3.14; Build job. Workflow names and job names standardized.
• ✅ Release workflow — Trigger on release events (published / edited); conditional publish step; clearer structure.
• ✅ Pages workflow — New workflow to build and deploy the docs site to GitHub Pages (push to main or workflow_dispatch).

Code Quality

• ✅ Timer — All constructor arguments are keyword-only (*, metadata=..., on_start=..., on_end=..., maxlen=...) for clearer API and future extensibility.
• ✅ __version__ removed from __all__ (still available as timerun.__version__).
• ✅ pyproject.toml — Development status set to Beta; optional dependency groups: dev (adds pip-audit), docs (zensical); coverage fail_under = 100.

Community and Repo

• ✅ CODE_OF_CONDUCT.md — Contributor Covenant 3.0.
• ✅ SECURITY.md — How to report vulnerabilities.
• ✅ .editorconfig — Indent style, trim trailing whitespace, charset.
• ✅ GitHub templates — Bug report and feature request issue templates; pull request template.

Developer Experience

• ✅ Makefile — Restructured with init/clean (prompt for Python or PYTHON=, clean removes paths from .gitignore); make help; make test / make test-verbose / make docs / make docs-build / make lint; CONTRIBUTING aligned.
• ✅ CONTRIBUTING.md — Updated setup (e.g. make init), development commands, testing (Behave), code style, project structure, PR process, releasing.
• ✅ Pre-commit — Config and hooks updated for current tooling.

Testing

• ✅ Block timing feature — New Behave feature and step definitions for block timing: sync/async/CPU-bound blocks, multi-thread and sequential/nested blocks, metadata isolation, on_start/on_end callback scenarios, and edge cases (block that raises, exit without enter).

📊 Statistics

• Files changed: 32
• Additions: +1,542 lines
• Deletions: -158 lines
• Net change: +1,383 lines

🧪 Testing

All behavior is covered by Behave, including:

• ✅ Block timing (sync/async, callbacks, metadata, nested/sequential/threaded)
• ✅ Function timing (existing features)
• ✅ Callbacks: on_start and on_end invoked once per measurement with the same Measurement instance

🔄 Breaking Changes

Minor — Constructor is keyword-only; __all__ no longer exports __version__.

• Timer(...) — All arguments are keyword-only. Use Timer(), Timer(metadata={...}), Timer(on_end=...), etc. Positional Timer(some_dict) is invalid and will raise.
• from timerun import * — __version__ is no longer in __all__. Use import timerun and timerun.__version__, or from timerun import __version__ (still works; only star-import is affected).

📝 Migration Guide

• Existing Timer() or Timer(metadata=...) — No change.
• Positional Timer(x) — Replace with Timer(metadata=x) (or the appropriate keyword).
• Star-import of version — Prefer import timerun and timerun.__version__, or from timerun import __version__.

See the documentation site for full guides and recipes.

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##              main        #6   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         1           
  Lines          101       107    +6     
=========================================
+ Hits           101       107    +6     

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%> (ø)

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.