executiontimer 0.1.0__tar.gz → 0.1.1__tar.gz

executiontimer-0.1.1/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 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.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.1.1...HEAD
+[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.1.1/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# 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.12, 3.13 and 3.14 on Linux, macOS and Windows.
+To check another interpreter locally:
+
+```bash
+uv run --python 3.12 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.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -145,6 +145,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 +165,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 +206,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 +224,38 @@ 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.
+
+### 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
 

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

@@ -116,6 +116,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 +136,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 +177,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 +195,38 @@ 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.
+
+### 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
 

executiontimer-0.1.1/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.1.1/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.1.1}/pyproject.toml

@@ -52,7 +52,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 = [

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

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

{executiontimer-0.1.0 → executiontimer-0.1.1}/src/execution_timer/_timer.py

@@ -3,7 +3,7 @@
 Timings are stored in a process-wide registry guarded by a lock. The active-context stack
 lives in a :class:`~contextvars.ContextVar`, so it is isolated per thread *and* per asyncio
 task: sections recorded concurrently nest independently and merge into one report.
-Recording the *same* section path from overlapping threads or tasks is not meaningful.
+Overlapping calls to the same section accumulate their individual durations.
 """
 
 from __future__ import annotations
@@ -14,11 +14,12 @@ import json
 import logging
 import threading
 import time
-from collections.abc import Callable, Coroutine, Iterable
+from collections.abc import Callable, Coroutine, Iterable, Iterator
 from contextvars import ContextVar
+from itertools import count
 from pathlib import Path
 from types import TracebackType
-from typing import ClassVar, Final, ParamSpec, TypedDict, TypeVar, cast
+from typing import Final, NamedTuple, ParamSpec, TypedDict, TypeVar, cast
 
 P = ParamSpec("P")
 R = TypeVar("R")
@@ -28,9 +29,6 @@ DEFAULT_CATEGORY: Final = "default"
 
 _LOGGER: Final = logging.getLogger(__name__)
 
-# Stack of (name, category) frames for the current thread / asyncio task.
-_ACTIVE_CONTEXT: ContextVar[tuple[tuple[str, str], ...]] = ContextVar("execution_timer_context", default=())
-
 
 class TimingReport(TypedDict):
     """Timing entry for one section: elapsed seconds and its category."""
@@ -57,11 +55,24 @@ class TimingsPayload(TypedDict):
 
 
 class _TimesDict(TypedDict):
-    start_time: float
+    sequence: int
     elapsed_time: float
     category: str
 
 
+class _Frame(NamedTuple):
+    """Per-invocation state, with a cached path and an immutable parent link."""
+
+    path: tuple[str, ...]
+    category: str
+    start_time: float
+    entry: _TimesDict
+    parent: _Frame | None
+
+
+_ACTIVE_CONTEXT: ContextVar[_Frame | None] = ContextVar("execution_timer_context", default=None)
+
+
 def _ordered_by_hierarchy(keys: Iterable[tuple[str, ...]]) -> list[tuple[str, ...]]:
     """Order section paths depth-first so children always follow their parent.
 
@@ -91,81 +102,53 @@ def _ordered_by_hierarchy(keys: Iterable[tuple[str, ...]]) -> list[tuple[str, ..
 
 
 class _ExecutionTimer:
-    """Singleton registry of named, nestable timing sections."""
-
-    _instance: ClassVar[_ExecutionTimer | None] = None
-    _lock: ClassVar[threading.Lock] = threading.Lock()
-    timings: ClassVar[dict[tuple[str, ...], _TimesDict]] = {}
-    forbidden_nesting: ClassVar[set[tuple[str, str]]] = set()
-
-    def __new__(cls) -> _ExecutionTimer:
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
+    """Registry of named, nestable timing sections, shared through ``_TIMER``."""
 
-    @property
-    def _full_name(self) -> tuple[str, ...]:
-        return tuple(frame[0] for frame in _ACTIVE_CONTEXT.get())
+    def __init__(self) -> None:
+        self._lock: threading.Lock = threading.Lock()
+        self.timings: dict[tuple[str, ...], _TimesDict] = {}
+        self.forbidden_nesting: set[tuple[str, str]] = set()
+        self._sequence: Iterator[int] = count()
 
-    def _snapshot(self) -> dict[tuple[str, ...], _TimesDict]:
+    def snapshot(self) -> dict[tuple[str, ...], _TimesDict]:
         """Copy the registry under the lock so readers never iterate a mutating dict."""
         with self._lock:
             return {key: info.copy() for key, info in self.timings.items()}
 
     def start_timer(self, name: str, category: str) -> None:
         """Start timing a section under the given name within the active context."""
-        self._add_context(name, category)
-        full_name = self._full_name
-        start_time = time.perf_counter()
+        parent = _ACTIVE_CONTEXT.get()
+        full_name = (*parent.path, name) if parent is not None else (name,)
         with self._lock:
-            entry = self.timings.get(full_name)
+            if parent is not None and (parent.category, category) in self.forbidden_nesting:
+                msg = f"Category '{category}' is not allowed inside category '{parent.category}'."
+                raise ValueError(msg)
+            sequence = next(self._sequence)
+            entry: _TimesDict | None = self.timings.get(full_name)
             if entry is None:
-                self.timings[full_name] = {"start_time": start_time, "elapsed_time": 0.0, "category": category}
+                entry = {"sequence": sequence, "elapsed_time": 0.0, "category": category}
+                self.timings[full_name] = entry
             else:
-                entry["start_time"] = start_time
+                entry["sequence"] = sequence
                 entry["category"] = category
+        _ = _ACTIVE_CONTEXT.set(_Frame(full_name, category, time.perf_counter(), entry, parent))
 
     def stop_timer(self, name: str) -> None:
         """Stop timing a section and accumulate its elapsed time."""
         end_time = time.perf_counter()
-        full_name = self._full_name
-        with self._lock:
-            entry = self.timings.get(full_name)
-            # The entry is gone if the registry was cleared while this section was running;
-            # dropping the sample is preferable to raising out of a ``with`` block.
-            if entry is not None:
-                entry["elapsed_time"] += end_time - entry["start_time"]
-        self._remove_context(name)
-
-    def _add_context(self, name: str, category: str) -> None:
-        stack = _ACTIVE_CONTEXT.get()
-        if stack and (stack[-1][1], category) in self.forbidden_nesting:
-            msg = f"Category '{category}' is not allowed inside category '{stack[-1][1]}'."
-            raise ValueError(msg)
-        _ = _ACTIVE_CONTEXT.set((*stack, (name, category)))
-
-    def _remove_context(self, name: str) -> None:
-        """Pop the innermost context, restoring the stack to its state before ``name`` was entered."""
-        stack = _ACTIVE_CONTEXT.get()
-        if not stack:
+        frame = _ACTIVE_CONTEXT.get()
+        if frame is None:
             return
-        # Cut back through the matching frame so a mismatched or out-of-order exit cannot corrupt the stack.
-        for index in range(len(stack) - 1, -1, -1):
-            if stack[index][0] == name:
-                _ = _ACTIVE_CONTEXT.set(stack[:index])
-                return
-        _ = _ACTIVE_CONTEXT.set(stack[:-1])
-
-    def compute_flattened_timings(self) -> dict[tuple[str, ...], _TimesDict]:
-        """Aggregate elapsed times with counter suffixes removed from section names.
-
-        When counter variants of one section are merged, elapsed times are summed and the
-        most recently recorded category is kept.
-        """
-        return _flatten(self._snapshot())
+        if frame.path[-1] != name:
+            raise RuntimeError(f"Cannot stop '{name}' while '{frame.path[-1]}' is active.")
+        with self._lock:
+            # A clear detaches this entry from the registry. Updating the detached object
+            # cannot resurrect an old sample or add it to a replacement at the same path.
+            frame.entry["elapsed_time"] += end_time - frame.start_time
+        _ = _ACTIVE_CONTEXT.set(frame.parent)
 
     def _resolve(self, *, flatten: bool) -> dict[tuple[str, ...], _TimesDict]:
-        snapshot = self._snapshot()
+        snapshot = self.snapshot()
         return _flatten(snapshot) if flatten else snapshot
 
     def report_timings(self, *, flatten: bool = True) -> str:
@@ -185,12 +168,14 @@ class _ExecutionTimer:
 
     def compute_total_time(self, *, flatten: bool = True) -> float:
         """Compute total elapsed time across all top-level sections."""
-        timings = self._resolve(flatten=flatten)
-        return sum(info["elapsed_time"] for key, info in timings.items() if len(key) == 1)
+        # Counter merging cannot change the sum. Avoid allocating and flattening a snapshot.
+        _ = flatten
+        with self._lock:
+            return sum((info["elapsed_time"] for key, info in self.timings.items() if len(key) == 1), 0.0)
 
     def compute_total_category_time(self, category: str) -> float:
         """Compute total elapsed time in a category, counting only top-most entries of that category."""
-        timings = self._snapshot()
+        timings = self.snapshot()
         total_time = 0.0
         for key, info in timings.items():
             if info["category"] != category or _has_ancestor_with_category(timings, key, category):
@@ -208,6 +193,17 @@ class _ExecutionTimer:
         with self._lock:
             self.timings.clear()
 
+    def register_forbidden_nesting(self, outer: str, inner: str) -> None:
+        with self._lock:
+            self.forbidden_nesting.add((outer, inner))
+
+    def clear_forbidden_nesting(self) -> None:
+        with self._lock:
+            self.forbidden_nesting.clear()
+
+
+_TIMER: Final = _ExecutionTimer()
+
 
 def _flatten(timings: dict[tuple[str, ...], _TimesDict]) -> dict[tuple[str, ...], _TimesDict]:
     flat_map: dict[tuple[str, ...], _TimesDict] = {}
@@ -218,7 +214,9 @@ def _flatten(timings: dict[tuple[str, ...], _TimesDict]) -> dict[tuple[str, ...]
             flat_map[flat_key] = info.copy()
         else:
             existing["elapsed_time"] += info["elapsed_time"]
-            existing["category"] = info["category"]
+            if info["sequence"] > existing["sequence"]:
+                existing["category"] = info["category"]
+                existing["sequence"] = info["sequence"]
     return flat_map
 
 
@@ -234,7 +232,7 @@ class TimerContext:
     def __init__(self, name: str, category: str = DEFAULT_CATEGORY, counter: int | None = None) -> None:
         self.name: str = _build_name_with_counter(name, counter)
         self.category: str = category
-        self.timer: _ExecutionTimer = _ExecutionTimer()
+        self.timer: _ExecutionTimer = _TIMER
 
     def __enter__(self) -> TimerContext:
         self.timer.start_timer(self.name, self.category)
@@ -259,7 +257,7 @@ class TimerContext:
 
         @functools.wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-            with TimerContext(self.name, self.category):
+            with self:
                 return func(*args, **kwargs)
 
         return wrapper
@@ -269,7 +267,7 @@ class TimerContext:
 
         @functools.wraps(func)
         async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
-            with TimerContext(self.name, self.category):
+            with self:
                 return await func(*args, **kwargs)
 
         return async_wrapper
@@ -285,42 +283,51 @@ def _build_name_with_counter(name: str, counter: int | None = None) -> str:
 def _basic_name_without_counter(name: str) -> str:
     """Strip a trailing ``[counter]`` from a section name if present."""
     if "[" in name and name.endswith("]"):
-        return name[: name.rfind("[")]
+        prefix, _, suffix = name.rpartition("[")
+        digits = suffix[:-1].removeprefix("-")
+        if digits.isascii() and digits.isdecimal():
+            return prefix
     return name
 
 
 def get_execution_times_report(*, flatten: bool = True) -> str:
     """Get a formatted report of all recorded sections; flatten counters if requested."""
-    return _ExecutionTimer().report_timings(flatten=flatten)
+    return _TIMER.report_timings(flatten=flatten)
 
 
 def log_execution_times(*, flatten: bool = True, logger: logging.Logger | None = None) -> None:
     """Log the execution-times report at INFO level; flatten counters if requested."""
-    (logger or _LOGGER).info(get_execution_times_report(flatten=flatten))
+    target = logger if logger is not None else _LOGGER
+    if target.isEnabledFor(logging.INFO):
+        target.info(get_execution_times_report(flatten=flatten))
 
 
 def get_execution_timings(*, flatten: bool = True) -> dict[tuple[str, ...], TimingReport]:
     """Get elapsed seconds and category for every recorded section; flatten counters if requested."""
-    return _ExecutionTimer().get_execution_timings(flatten=flatten)
+    return _TIMER.get_execution_timings(flatten=flatten)
 
 
 def _build_payload(*, flatten: bool = True) -> TimingsPayload:
     """Build a JSON-serializable snapshot of all timings, including totals and per-category sums."""
-    timer = _ExecutionTimer()
-    timings = timer.get_execution_timings(flatten=flatten)
+    snapshot = _TIMER.snapshot()
+    timings = _flatten(snapshot) if flatten else snapshot
     sections: list[SectionRecord] = [
         {
             "name": key[-1],
             "path": list(key),
-            "time": round(timings[key]["time"], 6),
+            "time": round(timings[key]["elapsed_time"], 6),
             "category": timings[key]["category"],
         }
         for key in _ordered_by_hierarchy(timings)
     ]
-    categories = sorted({info["category"] for info in timings.values()})
+    category_totals: dict[str, float] = {}
+    for key, info in snapshot.items():
+        category = info["category"]
+        if not _has_ancestor_with_category(snapshot, key, category):
+            category_totals[category] = category_totals.get(category, 0.0) + info["elapsed_time"]
     return {
-        "total_time": round(timer.compute_total_time(flatten=flatten), 6),
-        "total_category_time": {cat: round(timer.compute_total_category_time(cat), 6) for cat in categories},
+        "total_time": round(sum((info["elapsed_time"] for key, info in snapshot.items() if len(key) == 1), 0.0), 6),
+        "total_category_time": {cat: round(category_totals[cat], 6) for cat in sorted(category_totals)},
         "sections": sections,
     }
 
@@ -339,24 +346,24 @@ def save_execution_timings_json(path: str | Path, *, flatten: bool = True, inden
 
 def get_total_time(*, flatten: bool = True) -> float:
     """Get total elapsed seconds across all top-level sections."""
-    return _ExecutionTimer().compute_total_time(flatten=flatten)
+    return _TIMER.compute_total_time(flatten=flatten)
 
 
 def get_total_category_time(category: str) -> float:
     """Get total elapsed seconds in a category, counting only top-most entries of that category."""
-    return _ExecutionTimer().compute_total_category_time(category)
+    return _TIMER.compute_total_category_time(category)
 
 
 def clear_execution_timings() -> None:
     """Reset all recorded timings."""
-    _ExecutionTimer().clear()
+    _TIMER.clear()
 
 
 def register_forbidden_nesting(outer: str, inner: str) -> None:
     """Forbid timing sections of category ``inner`` directly inside sections of category ``outer``."""
-    _ExecutionTimer.forbidden_nesting.add((outer, inner))
+    _TIMER.register_forbidden_nesting(outer, inner)
 
 
 def clear_forbidden_nesting() -> None:
     """Remove all forbidden-nesting rules."""
-    _ExecutionTimer.forbidden_nesting = set()
+    _TIMER.clear_forbidden_nesting()

{executiontimer-0.1.0 → executiontimer-0.1.1}/tests/execution_timer_test.py

@@ -1,11 +1,15 @@
 """Tests for the execution timer, using only the public API."""
 
 import asyncio
+import builtins
 import inspect
 import json
 import logging
+import threading
 import time
 from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import ExitStack
 from pathlib import Path
 from typing import cast
 from unittest.mock import patch
@@ -543,7 +547,11 @@ class TestAsyncDecorator:
 
         asyncio.run(work())
 
-        assert raw_timings()["async_work",]["time"] >= 0.04
+        # Timing only the coroutine object's creation records ~1e-06 s, so any threshold
+        # orders of magnitude above that proves the await was covered. Kept well below the
+        # sleep duration because Windows' ~15.6 ms timer granularity lets short sleeps
+        # return early -- a threshold near 0.05 makes this test flaky rather than stricter.
+        assert raw_timings()["async_work",]["time"] >= 0.01
 
     def test_async_decorator_preserves_return_value(self) -> None:
         @TimerContext("async_compute")
@@ -686,3 +694,301 @@ class TestRobustness:
             assert get_execution_times_report() == ""
 
         assert [record.name for record in caplog.records] == ["execution_timer._timer"]
+
+
+class TestRegressions:
+    @pytest.mark.parametrize("clear_between_calls", [False, True])
+    def test_overlapping_tasks_keep_independent_start_times(self, clear_between_calls: bool) -> None:
+        now = 0.0
+        shared = TimerContext("shared")
+
+        async def main() -> None:
+            nonlocal now
+            started = [asyncio.Event(), asyncio.Event()]
+            release = [asyncio.Event(), asyncio.Event()]
+
+            async def worker(index: int) -> None:
+                with shared:
+                    started[index].set()
+                    _ = await release[index].wait()
+
+            first = asyncio.create_task(worker(0))
+            _ = await started[0].wait()
+            if clear_between_calls:
+                clear_execution_timings()
+            now = 2.0
+            second = asyncio.create_task(worker(1))
+            _ = await started[1].wait()
+            now = 5.0
+            release[0].set()
+            await first
+            now = 9.0
+            release[1].set()
+            await second
+
+        with patch.object(time, "perf_counter", side_effect=lambda: now):
+            asyncio.run(main())
+
+        assert raw_timings() == {("shared",): {"time": 7.0 if clear_between_calls else 12.0, "category": "default"}}
+
+    def test_overlapping_thread_decorator_calls_accumulate_each_duration(self) -> None:
+        now = 0.0
+        started = [threading.Event(), threading.Event()]
+        release = [threading.Event(), threading.Event()]
+
+        @TimerContext("shared")
+        def worker(index: int) -> None:
+            started[index].set()
+            assert release[index].wait(timeout=5)
+
+        with patch.object(time, "perf_counter", side_effect=lambda: now), ThreadPoolExecutor(max_workers=2) as pool:
+            first = pool.submit(worker, 0)
+            try:
+                assert started[0].wait(timeout=5)
+                now = 2.0
+                second = pool.submit(worker, 1)
+                assert started[1].wait(timeout=5)
+                now = 5.0
+                release[0].set()
+                first.result(timeout=5)
+                now = 9.0
+                release[1].set()
+                second.result(timeout=5)
+            finally:
+                for event in release:
+                    event.set()
+
+        assert raw_timings()["shared",]["time"] == 12.0
+
+    def test_flatten_category_follows_latest_revisit_even_with_equal_clock_readings(self) -> None:
+        with patch.object(time, "perf_counter", return_value=0.0):
+            for counter, category in [(0, "gpu"), (1, "cpu"), (0, "io")]:
+                with TimerContext("step", counter=counter, category=category):
+                    pass
+
+        assert get_execution_timings()["step",]["category"] == "io"
+
+    @pytest.mark.parametrize("name", ["array[index]", "empty[]", "label[+1]", "label[1.5]", "label[\uff11\uff12]"])
+    def test_flatten_preserves_non_counter_brackets(self, name: str) -> None:
+        with TimerContext(name):
+            pass
+        assert list(get_execution_timings()) == [(name,)]
+
+    @pytest.mark.parametrize("counter", [-12, 0, 12])
+    def test_signed_counters_flatten_only_the_last_suffix(self, counter: int) -> None:
+        with TimerContext("array[index]", counter=counter):
+            pass
+        assert list(get_execution_timings()) == [("array[index]",)]
+
+    @pytest.mark.parametrize("flatten", [False, True])
+    def test_json_keeps_categories_hidden_by_flattening(self, flatten: bool) -> None:
+        with patch.object(time, "perf_counter", side_effect=[0, 2, 3, 6]):
+            with TimerContext("step", counter=0, category="gpu"):
+                pass
+            with TimerContext("step", counter=1, category="cpu"):
+                pass
+
+        payload = cast(TimingsPayload, json.loads(get_execution_times_json(flatten=flatten)))
+        assert payload["total_category_time"] == {"gpu": 2.0, "cpu": 3.0}
+        assert payload["total_time"] == 5.0
+
+    @pytest.mark.parametrize("flatten", [False, True])
+    def test_json_uses_one_snapshot_for_sections_and_totals(self, flatten: bool) -> None:
+        with patch.object(time, "perf_counter", side_effect=[0, 2]), TimerContext("section", category="cpu"):
+            pass
+
+        original_round = round
+
+        def clear_while_formatting(value: float, digits: int) -> float:
+            # Deterministically simulate another thread clearing the registry after the
+            # sections were read but before totals are formatted, through the public API.
+            clear_execution_timings()
+            return original_round(value, digits)
+
+        with patch.object(builtins, "round", side_effect=clear_while_formatting):
+            payload = cast(TimingsPayload, json.loads(get_execution_times_json(flatten=flatten)))
+
+        assert payload["sections"] == [{"name": "section", "path": ["section"], "time": 2.0, "category": "cpu"}]
+        assert payload["total_time"] == 2.0
+        assert payload["total_category_time"] == {"cpu": 2.0}
+
+    def test_disabled_logging_does_not_warn_about_empty_report(self, caplog: pytest.LogCaptureFixture) -> None:
+        logger = logging.getLogger("executiontimer.test.disabled")
+        with caplog.at_level(logging.WARNING), patch.object(logger, "isEnabledFor", return_value=False):
+            log_execution_times(logger=logger)
+        assert caplog.records == []
+
+
+class TestLifecycle:
+    def test_reusing_one_context_accumulates_exact_durations(self) -> None:
+        context = TimerContext("reused")
+        with patch.object(time, "perf_counter", side_effect=[0, 2, 5, 8]):
+            with context:
+                pass
+            with context:
+                pass
+        assert raw_timings()["reused",]["time"] == 5.0
+
+    def test_one_context_can_be_reentered(self) -> None:
+        context = TimerContext("recursive")
+        with patch.object(time, "perf_counter", side_effect=[0, 1, 3, 7]), context, context:
+            pass
+        assert raw_timings() == {
+            ("recursive",): {"time": 7.0, "category": "default"},
+            ("recursive", "recursive"): {"time": 2.0, "category": "default"},
+        }
+
+    def test_recursive_decorator_preserves_arguments_and_hierarchy(self) -> None:
+        @TimerContext("recursive", category="cpu", counter=0)
+        def recurse(depth: int, *, value: int) -> int:
+            return recurse(depth - 1, value=value + 1) if depth else value
+
+        with patch.object(time, "perf_counter", side_effect=range(6)):
+            assert recurse(2, value=40) == 42
+        assert [info["time"] for info in raw_timings().values()] == [5.0, 3.0, 1.0]
+        assert list(raw_timings()) == [("recursive[0]",) * depth for depth in range(1, 4)]
+
+    def test_failed_entry_leaves_parent_and_its_next_child_intact(self) -> None:
+        register_forbidden_nesting("gpu", "cpu")
+        with TimerContext("parent", category="gpu"):
+            with pytest.raises(ValueError), TimerContext("forbidden", category="cpu"):
+                pytest.fail("A forbidden section must not be entered")
+            with TimerContext("allowed", category="io"):
+                pass
+        with TimerContext("after"):
+            pass
+        assert list(raw_timings()) == [("parent",), ("parent", "allowed"), ("after",)]
+
+    def test_nesting_rules_only_apply_to_the_direct_parent(self) -> None:
+        register_forbidden_nesting("gpu", "cpu")
+        with (
+            TimerContext("gpu", category="gpu"),
+            TimerContext("io", category="io"),
+            TimerContext("cpu", category="cpu"),
+        ):
+            pass
+        assert ("gpu", "io", "cpu") in raw_timings()
+
+    def test_out_of_order_exit_raises_without_changing_the_active_section(self) -> None:
+        outer = TimerContext("outer")
+        inner = TimerContext("inner")
+        with (
+            patch.object(time, "perf_counter", side_effect=[0, 1, 2, 3, 4]),
+            outer,
+            inner,
+            pytest.raises(RuntimeError, match="Cannot stop 'outer' while 'inner' is active"),
+        ):
+            outer.__exit__(None, None, None)
+        assert raw_timings()["outer",]["time"] == 4.0
+        assert raw_timings()["outer", "inner"]["time"] == 2.0
+
+    def test_exit_without_an_active_section_is_a_noop(self) -> None:
+        TimerContext("unused").__exit__(None, None, None)
+        assert raw_timings() == {}
+
+    def test_reports_preserve_orphaned_children_after_clear(self) -> None:
+        with patch.object(time, "perf_counter", side_effect=[0, 1, 3, 5]), TimerContext("parent"):
+            clear_execution_timings()
+            with TimerContext("child", category="cpu"):
+                pass
+        assert list(raw_timings()) == [("parent", "child")]
+        assert "child: 2.0000 s (0.00%)" in get_execution_times_report()
+        payload = cast(TimingsPayload, json.loads(get_execution_times_json()))
+        assert payload["total_time"] == 0.0
+        assert payload["total_category_time"] == {"cpu": 2.0}
+        assert payload["sections"][0]["path"] == ["parent", "child"]
+
+    def test_deep_reports_do_not_depend_on_python_recursion_limit(self) -> None:
+        with ExitStack() as stack:
+            for _ in range(1_100):
+                _ = stack.enter_context(TimerContext("level"))
+        assert len(get_execution_times_report(flatten=False).splitlines()) == 1_103
+
+    def test_async_cancellation_records_time_and_restores_parent(self) -> None:
+        @TimerContext("cancelled")
+        async def work(*, value: int) -> int:
+            assert value == 42
+            await asyncio.sleep(0)
+            raise asyncio.CancelledError
+
+        async def main() -> None:
+            with TimerContext("parent"):
+                with pytest.raises(asyncio.CancelledError):
+                    _ = await work(value=42)
+                with TimerContext("after"):
+                    pass
+
+        with patch.object(time, "perf_counter", side_effect=range(6)):
+            asyncio.run(main())
+        assert raw_timings()["parent", "cancelled"]["time"] == 1.0
+        assert list(raw_timings()) == [("parent",), ("parent", "cancelled"), ("parent", "after")]
+
+    def test_child_tasks_inherit_the_parent_without_modifying_its_context(self) -> None:
+        @TimerContext("child")
+        async def child(value: int, *, increment: int) -> int:
+            await asyncio.sleep(0)
+            return value + increment
+
+        async def main() -> None:
+            with TimerContext("parent"):
+                assert await asyncio.gather(child(1, increment=1), child(2, increment=1)) == [2, 3]
+                with TimerContext("after"):
+                    pass
+
+        asyncio.run(main())
+        assert list(raw_timings()) == [("parent",), ("parent", "child"), ("parent", "after")]
+
+
+class TestSnapshotSemantics:
+    @pytest.mark.parametrize("flatten", [False, True])
+    def test_mutating_a_returned_report_does_not_change_the_registry(self, flatten: bool) -> None:
+        with patch.object(time, "perf_counter", side_effect=[0, 2]), TimerContext("section"):
+            pass
+        report = get_execution_timings(flatten=flatten)
+        report["section",]["time"] = -1
+        report["section",]["category"] = "changed"
+        report.clear()
+        assert raw_timings() == {("section",): {"time": 2.0, "category": "default"}}
+
+    @pytest.mark.parametrize("flatten", [False, True])
+    def test_json_category_totals_exclude_matching_ancestors_across_other_categories(self, flatten: bool) -> None:
+        with (
+            patch.object(time, "perf_counter", side_effect=range(6)),
+            TimerContext("outer", category="cpu", counter=1),
+            TimerContext("middle", category="io"),
+            TimerContext("inner", category="cpu"),
+        ):
+            pass
+        payload = cast(TimingsPayload, json.loads(get_execution_times_json(flatten=flatten)))
+        assert payload["total_category_time"] == {"cpu": 5.0, "io": 3.0}
+        assert get_total_category_time("cpu") == 5.0
+        assert get_total_time(flatten=flatten) == 5.0
+
+    def test_empty_json(self) -> None:
+        assert json.loads(get_execution_times_json(indent=None)) == {
+            "total_time": 0.0,
+            "total_category_time": {},
+            "sections": [],
+        }
+
+    def test_unicode_json_file_round_trip(self, tmp_path: Path) -> None:
+        with TimerContext("计算", category="数据"):
+            pass
+        out = tmp_path / "timings.json"
+        assert save_execution_timings_json(str(out), indent=None) == out
+        text = out.read_text(encoding="utf-8")
+        assert text.endswith("\n")
+        assert len(text.splitlines()) == 1
+        payload = cast(TimingsPayload, json.loads(text))
+        assert payload["sections"][0]["name"] == "计算"
+        assert payload["sections"][0]["category"] == "数据"
+
+    def test_custom_logger_receives_the_requested_report(self, caplog: pytest.LogCaptureFixture) -> None:
+        with TimerContext("section", counter=0):
+            pass
+        logger = logging.getLogger("executiontimer.test.custom")
+        with caplog.at_level(logging.INFO, logger=logger.name):
+            log_execution_times(flatten=False, logger=logger)
+        assert [(record.name, record.message) for record in caplog.records] == [
+            (logger.name, get_execution_times_report(flatten=False))
+        ]

executiontimer-0.1.0/CHANGELOG.md

@@ -1,33 +0,0 @@
-# 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.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.1.0...HEAD
-[0.1.0]: https://github.com/seba2390/ExecutionTimer/releases/tag/v0.1.0