executiontimer 0.1.0__tar.gz → 0.2.0__tar.gz

executiontimer-0.2.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-30
+
+### Changed
+
+- Decorating a generator function or an async generator function now raises `TypeError`.
+  Previously it silently timed only the creation of the generator object, which recorded
+  microseconds regardless of how long iteration took.
+- Python 3.11 is now supported; the minimum was 3.12 although nothing required it.
+
+### Fixed
+
+- `log_execution_times()` no longer logs an empty `INFO` record, after its warning, when
+  there are no timings.
+
+### Documentation
+
+- Explain that threads do not inherit the timing context, and how to nest thread work under
+  a section.
+- Explain how a section held open across a generator's `yield` absorbs the caller's sections.
+- Note that `flatten` has no effect on `get_total_time`.
+
+### Added
+
+- CI tests Python 3.11 and free-threaded Python 3.14t, and the package declares
+  free-threading support.
+- Workflows run with a read-only token by default and do not persist checkout credentials.
+
+## [0.1.1] - 2026-09-20
+
+### Fixed
+
+- Overlapping calls to the same section now accumulate each call's actual duration in
+  threads and asyncio tasks, including calls sharing one context or decorator.
+- Clearing active timings cannot add a discarded sample to a new entry at the same path.
+- JSON sections and totals now use one consistent snapshot, and category totals retain
+  categories that disappear when counter variants are merged.
+- Flattened categories follow the most recently entered section, including revisited counters.
+- Flattening preserves non-integer bracket suffixes such as `array[index]` and `empty[]`.
+- An out-of-order context exit raises `RuntimeError` without changing another section's
+  elapsed time or active stack.
+
+### Performance
+
+- Cache each active section's path and parent, and reuse decorator contexts to reduce
+  recording allocations and avoid rebuilding paths on exit.
+- Sum total time directly without copying and flattening the registry.
+- Calculate all JSON category totals in one pass over a shared snapshot.
+- Skip report generation when logging at `INFO` is disabled.
+
+### Added
+
+- Deterministic regression tests for concurrency, clearing, category attribution, and
+  snapshot consistency, plus coverage for recursion, cancellation, and deep nesting.
+- A repeatable benchmark for recording and reporting overhead in `benchmarks/overhead.py`.
+- Expanded the suite from 53 to 88 tests, achieving 100% statement and branch coverage.
+
+## [0.1.0] - 2026-08-20
+
+First public release on PyPI.
+
+### Added
+
+- `TimerContext` — context manager and decorator for timing a named section of code, with
+  optional `category` and `counter` arguments.
+- Automatic hierarchical nesting: section names reflect the enclosing timing contexts.
+- Native `async def` support — decorating a coroutine function times the whole `await`
+  rather than the creation of the coroutine object.
+- Per-task and per-thread context isolation via `contextvars`, so concurrently recorded
+  sections nest independently and merge into one process-wide report.
+- Reporting and export helpers: `get_execution_times_report`, `log_execution_times`,
+  `get_execution_timings`, `get_execution_times_json`, `save_execution_timings_json`,
+  `get_total_time`, `get_total_category_time`.
+- Optional nesting rules via `register_forbidden_nesting` / `clear_forbidden_nesting`.
+- `clear_execution_timings` to reset the registry.
+- Exported `TimingReport`, `SectionRecord` and `TimingsPayload` typed dictionaries, plus a
+  `py.typed` marker so type checkers use the inline annotations.
+- `__version__` attribute on the package.
+
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/seba2390/ExecutionTimer/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/seba2390/ExecutionTimer/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/seba2390/ExecutionTimer/releases/tag/v0.1.0

executiontimer-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thanks for taking the time to contribute.
+
+## Getting set up
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+git clone https://github.com/seba2390/ExecutionTimer.git
+cd ExecutionTimer
+uv sync
+```
+
+## Before opening a pull request
+
+Run the same checks CI runs:
+
+```bash
+uv run pytest --cov
+uv run ruff check --fix
+uv run ruff format
+uv run basedpyright
+```
+
+All four must pass. Coverage is enforced at 95%; the current suite has 100% statement
+and branch coverage. Preserve coverage when adding or changing behavior.
+
+The test suite is also run against Python 3.11, 3.12, 3.13, 3.14 and free-threaded 3.14t
+on Linux, macOS and Windows.
+To check another interpreter locally:
+
+```bash
+uv run --python 3.11 pytest
+```
+
+For changes to recording or reporting performance, compare the benchmark on the same
+machine and Python version, without coverage instrumentation:
+
+```bash
+uv run python benchmarks/overhead.py --number 100000 --repeat 9
+```
+
+See [benchmarks/README.md](benchmarks/README.md) for methodology and reference results.
+Timing results are advisory rather than CI pass/fail thresholds.
+
+## Guidelines
+
+- Tests exercise the **public API** only — import from `execution_timer`, not
+  `execution_timer._timer`. This keeps internals free to change.
+- Every behaviour change needs a test that fails before the fix and passes after it.
+- Public functions carry type annotations and a one-line docstring.
+- Add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md).
+
+## Releasing
+
+Maintainers only:
+
+1. Move the `## [Unreleased]` entries into a new version section in `CHANGELOG.md`, and
+   update the link definitions at the bottom.
+2. Bump `__version__` in `src/execution_timer/__init__.py`, then run `uv lock --check`
+   to verify the lockfile. Package metadata reads the version from `__version__`.
+3. Run the checks above, build with `uv build`, and validate metadata with
+   `uvx twine check --strict dist/*`. Use a clean output directory so old versions are
+   not included in release artifacts.
+4. Commit, then push to `main` and wait for CI to pass.
+5. Publish a GitHub release tagged `vX.Y.Z`, targeting the validated commit on `main`.
+   Use that version's changelog entries as release notes.
+
+The [Publish to PyPI workflow](.github/workflows/publish.yml) runs when a GitHub release
+is **published**. Pushing to `main`, pushing a tag alone, or saving a draft release does
+not trigger it. The workflow builds and validates the distributions, checks that the tag
+matches `__version__`, and uploads them to PyPI via Trusted Publishing. No manual
+`twine upload` or PyPI API token is needed. If the `pypi` GitHub environment requires
+approval, approve the publishing job there.
+
+After publishing the release, check that the workflow succeeds and the new version
+appears on [PyPI](https://pypi.org/project/executiontimer/).

{executiontimer-0.1.0 → executiontimer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.1.0
+Version: 0.2.0
 Summary: Hierarchical execution timing with user-defined categories.
 Project-URL: Homepage, https://github.com/seba2390/ExecutionTimer
 Project-URL: Documentation, https://github.com/seba2390/ExecutionTimer#readme
@@ -16,15 +16,17 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: System :: Benchmark
 Classifier: Typing :: Typed
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -55,7 +57,8 @@ Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
 - 🌳 **Automatic hierarchy** — nesting `with` blocks nests the report, no wiring required
 - 🏷️ **User-defined categories** — tag sections with any string (`"gpu"`, `"io"`, `"db"`) and get per-category totals
 - ⚡ **Native async** — decorating an `async def` times the whole `await`, not the coroutine object
-- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task
+- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task,
+  including on free-threaded Python builds
 - 🔢 **Loop counters** — time each iteration separately, then merge them back together
 - 📤 **JSON export** — structured output for dashboards, CI, or an LLM
 - 🚫 **Nesting rules** — optionally forbid one category inside another to catch mistakes early
@@ -71,7 +74,7 @@ pip install executiontimer
 uv add executiontimer
 ```
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 > **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
 >
@@ -131,6 +134,10 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+Generator functions (including `async` generators) cannot be decorated and raise a
+`TypeError`: the decorator would time only the creation of the generator object, not its
+iteration. Time the loop that consumes the generator with a `with` block instead.
+
 ### Counters
 
 Pass `counter=i` to time loop iterations separately. The report merges them by default
@@ -145,6 +152,10 @@ get_execution_timings(flatten=True)  # {("step",): {"time": 0.158, ...}}
 get_execution_timings(flatten=False)  # {("step[0]",): ..., ("step[1]",): ..., ...}
 ```
 
+Flattening removes the final integer suffix (including negative counters). Other
+bracketed names such as `array[index]` are preserved. If merged entries have different
+categories, the category from the most recently entered section is used.
+
 ### Categories
 
 Categories are plain strings — use whatever fits your domain:
@@ -161,6 +172,10 @@ get_total_category_time("gpu")
 `get_total_category_time` counts only the *top-most* section of a category, so a `gpu`
 section nested inside another `gpu` section is not double-counted.
 
+Repeated calls to the same path accumulate time. If its category changes, the latest
+category applies to that path's entire accumulated time. Use consistent categories per
+path when you need separate category totals.
+
 You can also forbid a category from appearing inside another, which raises a `ValueError`
 as soon as the invalid nesting happens:
 
@@ -198,6 +213,9 @@ save_execution_timings_json("timings.json")
 }
 ```
 
+Sections and totals come from one snapshot. Category totals use the original paths,
+even when flattening merges sections with different categories.
+
 ### Concurrency
 
 The recorded timings live in one process-wide registry guarded by a lock. The *active
@@ -213,9 +231,50 @@ async def worker(n: int) -> None:
 await asyncio.gather(worker(0), worker(1))
 ```
 
-Recording the *same* section path from overlapping threads or tasks is not meaningful —
-the elapsed times would overlap and sum to more than the wall-clock duration. Give
-concurrent sections distinct names (or use `counter=`).
+Overlapping calls to the same section path are supported: each call keeps its own start
+time, and their durations are added together. These totals measure accumulated elapsed
+time and can exceed wall-clock duration. Use distinct names (or `counter=`) to report
+concurrent calls separately.
+
+New asyncio tasks inherit the timing context in which they are created. Their sections
+nest under that parent; changes to each task's active stack remain independent. Await
+child tasks inside the parent section if you want the parent duration to include them.
+
+New threads do *not* inherit the timing context, so sections recorded in a thread
+appear at the top level of the report, and their time is added to the total alongside
+the section that started the thread. To nest thread work under the current section, run
+it with `contextvars.copy_context().run(...)` or `asyncio.to_thread(...)`. Either way,
+concurrent threads accumulate overlapping time. (Free-threaded builds of Python 3.14 make
+threads inherit the context by default.)
+
+Generators run in their caller's context. A `with TimerContext(...)` block that stays open
+across a `yield` therefore also contains whatever the caller times while the generator is
+paused, and its duration includes that paused time. Close sections before yielding, or
+time the loop that consumes the generator instead.
+
+### Reusing contexts and clearing timings
+
+A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
+For a tight loop, reuse a context to avoid constructing one on every iteration:
+
+```python
+step_timer = TimerContext("step")
+for item in items:
+    with step_timer:
+        process(item)
+```
+
+Timings accumulate until `clear_execution_timings()` is called. Clearing also discards
+samples from sections that were already active, without disturbing their nesting stack.
+Sections started after the clear are recorded normally. Reports include completed calls;
+an active section's current duration is added only when it exits.
+
+### Measuring overhead
+
+Run the repeatable benchmark with `uv run python benchmarks/overhead.py`. It measures
+fresh and reused contexts, sync and async decorators, nesting, and reporting. Compare
+results using the same interpreter and machine; see [benchmarks/README.md](benchmarks/README.md).
+`log_execution_times()` skips building a report when its logger has `INFO` disabled.
 
 ## API
 
@@ -227,7 +286,7 @@ concurrent sections distinct names (or use `counter=`).
 | `get_execution_timings(*, flatten=True)` | Timings as `dict[tuple[str, ...], TimingReport]`. |
 | `get_execution_times_json(*, flatten=True, indent=2)` | All timings as a JSON string. |
 | `save_execution_timings_json(path, *, flatten=True, indent=2)` | Write timings to a JSON file; returns the `Path`. |
-| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections. |
+| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections (`flatten` has no effect on the sum). |
 | `get_total_category_time(category)` | Total seconds in a category (top-most entries only). |
 | `clear_execution_timings()` | Reset all recorded timings. |
 | `register_forbidden_nesting(outer, inner)` | Forbid `inner` category directly inside `outer`. |

{executiontimer-0.1.0 → executiontimer-0.2.0}/README.md

@@ -26,7 +26,8 @@ Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
 - 🌳 **Automatic hierarchy** — nesting `with` blocks nests the report, no wiring required
 - 🏷️ **User-defined categories** — tag sections with any string (`"gpu"`, `"io"`, `"db"`) and get per-category totals
 - ⚡ **Native async** — decorating an `async def` times the whole `await`, not the coroutine object
-- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task
+- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task,
+  including on free-threaded Python builds
 - 🔢 **Loop counters** — time each iteration separately, then merge them back together
 - 📤 **JSON export** — structured output for dashboards, CI, or an LLM
 - 🚫 **Nesting rules** — optionally forbid one category inside another to catch mistakes early
@@ -42,7 +43,7 @@ pip install executiontimer
 uv add executiontimer
 ```
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 > **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
 >
@@ -102,6 +103,10 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+Generator functions (including `async` generators) cannot be decorated and raise a
+`TypeError`: the decorator would time only the creation of the generator object, not its
+iteration. Time the loop that consumes the generator with a `with` block instead.
+
 ### Counters
 
 Pass `counter=i` to time loop iterations separately. The report merges them by default
@@ -116,6 +121,10 @@ get_execution_timings(flatten=True)  # {("step",): {"time": 0.158, ...}}
 get_execution_timings(flatten=False)  # {("step[0]",): ..., ("step[1]",): ..., ...}
 ```
 
+Flattening removes the final integer suffix (including negative counters). Other
+bracketed names such as `array[index]` are preserved. If merged entries have different
+categories, the category from the most recently entered section is used.
+
 ### Categories
 
 Categories are plain strings — use whatever fits your domain:
@@ -132,6 +141,10 @@ get_total_category_time("gpu")
 `get_total_category_time` counts only the *top-most* section of a category, so a `gpu`
 section nested inside another `gpu` section is not double-counted.
 
+Repeated calls to the same path accumulate time. If its category changes, the latest
+category applies to that path's entire accumulated time. Use consistent categories per
+path when you need separate category totals.
+
 You can also forbid a category from appearing inside another, which raises a `ValueError`
 as soon as the invalid nesting happens:
 
@@ -169,6 +182,9 @@ save_execution_timings_json("timings.json")
 }
 ```
 
+Sections and totals come from one snapshot. Category totals use the original paths,
+even when flattening merges sections with different categories.
+
 ### Concurrency
 
 The recorded timings live in one process-wide registry guarded by a lock. The *active
@@ -184,9 +200,50 @@ async def worker(n: int) -> None:
 await asyncio.gather(worker(0), worker(1))
 ```
 
-Recording the *same* section path from overlapping threads or tasks is not meaningful —
-the elapsed times would overlap and sum to more than the wall-clock duration. Give
-concurrent sections distinct names (or use `counter=`).
+Overlapping calls to the same section path are supported: each call keeps its own start
+time, and their durations are added together. These totals measure accumulated elapsed
+time and can exceed wall-clock duration. Use distinct names (or `counter=`) to report
+concurrent calls separately.
+
+New asyncio tasks inherit the timing context in which they are created. Their sections
+nest under that parent; changes to each task's active stack remain independent. Await
+child tasks inside the parent section if you want the parent duration to include them.
+
+New threads do *not* inherit the timing context, so sections recorded in a thread
+appear at the top level of the report, and their time is added to the total alongside
+the section that started the thread. To nest thread work under the current section, run
+it with `contextvars.copy_context().run(...)` or `asyncio.to_thread(...)`. Either way,
+concurrent threads accumulate overlapping time. (Free-threaded builds of Python 3.14 make
+threads inherit the context by default.)
+
+Generators run in their caller's context. A `with TimerContext(...)` block that stays open
+across a `yield` therefore also contains whatever the caller times while the generator is
+paused, and its duration includes that paused time. Close sections before yielding, or
+time the loop that consumes the generator instead.
+
+### Reusing contexts and clearing timings
+
+A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
+For a tight loop, reuse a context to avoid constructing one on every iteration:
+
+```python
+step_timer = TimerContext("step")
+for item in items:
+    with step_timer:
+        process(item)
+```
+
+Timings accumulate until `clear_execution_timings()` is called. Clearing also discards
+samples from sections that were already active, without disturbing their nesting stack.
+Sections started after the clear are recorded normally. Reports include completed calls;
+an active section's current duration is added only when it exits.
+
+### Measuring overhead
+
+Run the repeatable benchmark with `uv run python benchmarks/overhead.py`. It measures
+fresh and reused contexts, sync and async decorators, nesting, and reporting. Compare
+results using the same interpreter and machine; see [benchmarks/README.md](benchmarks/README.md).
+`log_execution_times()` skips building a report when its logger has `INFO` disabled.
 
 ## API
 
@@ -198,7 +255,7 @@ concurrent sections distinct names (or use `counter=`).
 | `get_execution_timings(*, flatten=True)` | Timings as `dict[tuple[str, ...], TimingReport]`. |
 | `get_execution_times_json(*, flatten=True, indent=2)` | All timings as a JSON string. |
 | `save_execution_timings_json(path, *, flatten=True, indent=2)` | Write timings to a JSON file; returns the `Path`. |
-| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections. |
+| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections (`flatten` has no effect on the sum). |
 | `get_total_category_time(category)` | Total seconds in a category (top-most entries only). |
 | `clear_execution_timings()` | Reset all recorded timings. |
 | `register_forbidden_nesting(outer, inner)` | Forbid `inner` category directly inside `outer`. |

executiontimer-0.2.0/benchmarks/README.md

@@ -0,0 +1,40 @@
+# Overhead benchmarks
+
+From a repository checkout, run:
+
+```bash
+uv run python benchmarks/overhead.py --number 100000 --repeat 9
+```
+
+The script prints JSON with the Python version, platform, and median nanoseconds per
+operation. Recording cases run `--number` operations per repeat. Reporting cases run
+`max(1, number // 1000)` operations against 1,000 recorded counter variants with ten
+categories. Async calls run in one event loop, so loop startup is excluded.
+
+Compare the same interpreter and machine under similar load, without coverage or a
+profiler enabled. These are microbenchmarks, not CI timing thresholds. The no-op bodies
+make instrumentation costs visible; application speedups depend on the work being timed.
+
+## Local comparison
+
+Measured on macOS 26.6.2, ARM64, CPython 3.14.5, using 100,000 operations and nine repeats.
+The baseline is commit `008494c` (version 0.1.0); the updated column uses version 0.1.1.
+Both versions ran the same script. Values below are microseconds per operation and
+include the benchmark function call; plain calls cost approximately 0.017 µs and plain
+awaits 0.056 µs in both runs.
+
+| Operation | Baseline (µs) | Updated (µs) | Reduction |
+| --- | ---: | ---: | ---: |
+| New context | 1.550 | 1.028 | 34% |
+| Reused context | 1.425 | 0.947 | 34% |
+| Decorated call | 1.604 | 1.011 | 37% |
+| Decorated await | 1.696 | 1.093 | 36% |
+| Five nested contexts | 7.792 | 5.116 | 34% |
+| Total time, 1,000 sections | 524.809 | 43.068 | 92% |
+| JSON, 1,000 sections | 1,177.635 | 1,005.600 | 15% |
+| Disabled logging, 1,000 sections | 520.167 | 0.099 | >99.9% |
+
+Recording keeps each invocation's start time and cached path in a context-local frame.
+Decorators reuse their context instead of constructing one per call. Total-time queries
+avoid copying and flattening entries, JSON exports share one snapshot, and disabled
+logging returns before building a report.

executiontimer-0.2.0/benchmarks/overhead.py

@@ -0,0 +1,120 @@
+"""Measure recording and reporting costs; run with ``uv run python benchmarks/overhead.py``.
+
+Use the same interpreter, machine, iteration count, and repeat count for comparisons.
+Results are medians in nanoseconds per operation; they are not CI pass/fail thresholds.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import platform
+import statistics
+import time
+import timeit
+from collections.abc import Callable
+
+from execution_timer import (
+    TimerContext,
+    clear_execution_timings,
+    get_execution_times_json,
+    get_total_time,
+    log_execution_times,
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    _ = parser.add_argument("--number", type=int, default=100_000)
+    _ = parser.add_argument("--repeat", type=int, default=7)
+    args = parser.parse_args()
+    number = int(args.number)
+    repeat = int(args.repeat)
+    if number < 1 or repeat < 1:
+        parser.error("--number and --repeat must be positive")
+
+    results: dict[str, float] = {}
+
+    def measure(name: str, operation: Callable[[], object], count: int = number) -> None:
+        clear_execution_timings()
+        results[name] = statistics.median(timeit.repeat(operation, number=count, repeat=repeat)) * 1e9 / count
+
+    def plain() -> None:
+        pass
+
+    def context() -> None:
+        with TimerContext("section"):
+            pass
+
+    shared = TimerContext("section")
+
+    def reused_context() -> None:
+        with shared:
+            pass
+
+    @TimerContext("section")
+    def decorated() -> None:
+        pass
+
+    def nested() -> None:
+        with shared, shared, shared, shared, shared:
+            pass
+
+    measure("plain_call", plain)
+    measure("new_context", context)
+    measure("reused_context", reused_context)
+    measure("decorated_call", decorated)
+    measure("five_nested_contexts", nested)
+
+    async def plain_async() -> None:
+        pass
+
+    decorated_async = TimerContext("async_section")(plain_async)
+
+    async def measure_async() -> None:
+        for name, function in (("plain_await", plain_async), ("decorated_await", decorated_async)):
+            samples: list[float] = []
+            for _ in range(repeat):
+                clear_execution_timings()
+                started = time.perf_counter()
+                for _ in range(number):
+                    await function()
+                samples.append((time.perf_counter() - started) * 1e9 / number)
+            results[name] = statistics.median(samples)
+
+    asyncio.run(measure_async())
+
+    clear_execution_timings()
+    for index in range(1_000):
+        with TimerContext("section", category=f"category{index % 10}", counter=index):
+            pass
+    quiet_logger = logging.getLogger("executiontimer.benchmark")
+    quiet_logger.setLevel(logging.WARNING)
+    reporting_count = max(1, number // 1_000)
+    for name, operation in (
+        ("total_1000_sections", get_total_time),
+        ("json_1000_sections", get_execution_times_json),
+        ("disabled_logging_1000_sections", lambda: log_execution_times(logger=quiet_logger)),
+    ):
+        results[name] = (
+            statistics.median(timeit.repeat(operation, number=reporting_count, repeat=repeat)) * 1e9 / reporting_count
+        )
+
+    print(
+        json.dumps(
+            {
+                "python": platform.python_version(),
+                "platform": platform.platform(),
+                "number": number,
+                "repeat": repeat,
+                "nanoseconds_per_operation": {name: round(value, 1) for name, value in results.items()},
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

{executiontimer-0.1.0 → executiontimer-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ description = "Hierarchical execution timing with user-defined categories."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 authors = [{ name = "Sebastian Yde Madsen" }]
 keywords = [
     "timing",
@@ -23,9 +23,11 @@ classifiers = [
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Software Development",
     "Topic :: Software Development :: Testing",
@@ -52,7 +54,16 @@ path = "src/execution_timer/__init__.py"
 packages = ["src/execution_timer"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md", "/pyproject.toml"]
+include = [
+    "/src",
+    "/tests",
+    "/benchmarks",
+    "/README.md",
+    "/LICENSE",
+    "/CHANGELOG.md",
+    "/CONTRIBUTING.md",
+    "/pyproject.toml",
+]
 
 [dependency-groups]
 dev = [
@@ -76,7 +87,7 @@ fail_under = 95
 exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
 
 [tool.ruff]
-target-version = "py312"
+target-version = "py311"
 line-length = 120
 src = ["src", "tests"]
 
@@ -94,5 +105,5 @@ select = [
 
 [tool.basedpyright]
 typeCheckingMode = "recommended"
-pythonVersion = "3.12"
+pythonVersion = "3.11"
 include = ["src", "tests"]

{executiontimer-0.1.0 → executiontimer-0.2.0}/src/execution_timer/__init__.py

@@ -18,7 +18,7 @@ from execution_timer._timer import (
     save_execution_timings_json,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "DEFAULT_CATEGORY",