executiontimer 1.0.0__tar.gz → 1.0.2__tar.gz

{executiontimer-1.0.0 → executiontimer-1.0.2}/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-09-30
+
+### Fixed
+
+- Decorating a function that returns a coroutine, typically because another decorator
+  sits between `TimerContext` and an `async def`, now times the `await`. Previously the
+  section recorded only the call that created the coroutine, a few microseconds however
+  long the coroutine ran. Other awaitables, such as futures and tasks, are returned
+  unchanged.
+
+### Changed
+
+- The test suite fails on any warning, and CI requires 100% statement and branch coverage
+  rather than 95%.
+
+### Documentation
+
+- Note that flattening also merges sections whose own names end in an integer, such as
+  `"row[1]"` and `"row[2]"`.
+- The release steps in the contributing guide describe the pull-request flow that the
+  protected `main` branch requires.
+- Refresh the overhead benchmark against version 1.0.2.
+
+## [1.0.1] - 2026-09-30
+
+### Fixed
+
+- Exiting a section while an inner one is still active no longer leaves the active stack
+  corrupted when warnings are configured as errors (for example pytest's
+  `filterwarnings = ["error"]`). The `RuntimeWarning` was emitted before the exit was
+  recorded, so raising it skipped the cleanup that 1.0.0 introduced. The section is now
+  recorded and the stack unwound before the warning is emitted.
+- Sections whose parent was cleared while active now count as top-level. Previously,
+  clearing timings inside an outer section, such as a periodic clear in a long-running
+  loop, made `get_total_time()`, the report and the JSON `total_time` read `0`, every
+  percentage `0.00%`, and indented the sections beneath an unrelated one in the report.
+
+### Changed
+
+- The build requires `hatchling>=1.27`, the first release that supports the PEP 639
+  `license-files` metadata the project declares.
+- Dependabot groups its monthly updates into one pull request per ecosystem.
+
 ## [1.0.0] - 2026-09-30
 
 First stable release. The public API is now covered by semantic versioning: breaking
@@ -129,7 +172,9 @@ First public release on PyPI.
   `py.typed` marker so type checkers use the inline annotations.
 - `__version__` attribute on the package.
 
-[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/seba2390/ExecutionTimer/compare/v0.2.0...v1.0.0
 [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

{executiontimer-1.0.0 → executiontimer-1.0.2}/CONTRIBUTING.md

@@ -23,8 +23,8 @@ 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.
+All four must pass. The suite has 100% statement and branch coverage, and CI enforces it.
+Any warning raised during the tests fails them.
 
 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.
@@ -63,8 +63,9 @@ Maintainers only:
 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`.
+4. Commit on a branch and open a pull request. `main` is protected: it only accepts
+   pull requests whose `CI passed` check succeeds. Squash-merge once CI is green.
+5. Publish a GitHub release tagged `vX.Y.Z`, targeting the merged 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

{executiontimer-1.0.0 → executiontimer-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -134,6 +134,9 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+This also holds when another decorator sits between `TimerContext` and the `async def`
+and returns its coroutine: the section covers both the call and the `await`.
+
 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.
@@ -153,7 +156,9 @@ 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
+bracketed names such as `array[index]` are preserved. Flattening cannot tell a counter
+from a name you wrote yourself, so sections named `"row[1]"` and `"row[2]"` are also merged
+into `row`; use `flatten=False` to keep them apart. If merged entries have different
 categories, the category from the most recently entered section is used.
 
 Each counter value is stored as its own section until `clear_execution_timings()` is
@@ -260,7 +265,8 @@ time the loop that consumes the generator instead.
 If the caller's section exits while a paused generator's section is still open, the
 timer never raises: it emits a `RuntimeWarning`, records the caller's section, and
 discards the generator's unfinished one, so later sections nest correctly. Closing that
-generator afterwards does nothing.
+generator afterwards does nothing. If warnings are configured as errors, the warning is
+raised only after that cleanup, so the timings and nesting stay consistent.
 
 ### Reusing contexts and clearing timings
 
@@ -276,7 +282,8 @@ for item in items:
 
 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;
+Sections started after the clear are recorded normally; if their parent was cleared, they
+are reported as top-level sections and count toward the total. Reports include completed calls;
 an active section's current duration is added only when it exits.
 
 ### Measuring overhead
@@ -284,7 +291,6 @@ an active section's current duration is added only when it exits.
 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](https://github.com/seba2390/ExecutionTimer/blob/main/benchmarks/README.md).
-`log_execution_times()` skips building a report when its logger has `INFO` disabled.
 
 ## API
 
@@ -292,7 +298,7 @@ results using the same interpreter and machine; see [benchmarks/README.md](https
 | --- | --- |
 | `TimerContext(name, category=DEFAULT_CATEGORY, counter=None)` | Context manager **and** decorator for timing a section. |
 | `get_execution_times_report(*, flatten=True)` | Formatted, indented report of all sections (`""` if none). |
-| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty). |
+| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty); a no-op if `INFO` is disabled. |
 | `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`. |

{executiontimer-1.0.0 → executiontimer-1.0.2}/README.md

@@ -103,6 +103,9 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+This also holds when another decorator sits between `TimerContext` and the `async def`
+and returns its coroutine: the section covers both the call and the `await`.
+
 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.
@@ -122,7 +125,9 @@ 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
+bracketed names such as `array[index]` are preserved. Flattening cannot tell a counter
+from a name you wrote yourself, so sections named `"row[1]"` and `"row[2]"` are also merged
+into `row`; use `flatten=False` to keep them apart. If merged entries have different
 categories, the category from the most recently entered section is used.
 
 Each counter value is stored as its own section until `clear_execution_timings()` is
@@ -229,7 +234,8 @@ time the loop that consumes the generator instead.
 If the caller's section exits while a paused generator's section is still open, the
 timer never raises: it emits a `RuntimeWarning`, records the caller's section, and
 discards the generator's unfinished one, so later sections nest correctly. Closing that
-generator afterwards does nothing.
+generator afterwards does nothing. If warnings are configured as errors, the warning is
+raised only after that cleanup, so the timings and nesting stay consistent.
 
 ### Reusing contexts and clearing timings
 
@@ -245,7 +251,8 @@ for item in items:
 
 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;
+Sections started after the clear are recorded normally; if their parent was cleared, they
+are reported as top-level sections and count toward the total. Reports include completed calls;
 an active section's current duration is added only when it exits.
 
 ### Measuring overhead
@@ -253,7 +260,6 @@ an active section's current duration is added only when it exits.
 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](https://github.com/seba2390/ExecutionTimer/blob/main/benchmarks/README.md).
-`log_execution_times()` skips building a report when its logger has `INFO` disabled.
 
 ## API
 
@@ -261,7 +267,7 @@ results using the same interpreter and machine; see [benchmarks/README.md](https
 | --- | --- |
 | `TimerContext(name, category=DEFAULT_CATEGORY, counter=None)` | Context manager **and** decorator for timing a section. |
 | `get_execution_times_report(*, flatten=True)` | Formatted, indented report of all sections (`""` if none). |
-| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty). |
+| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty); a no-op if `INFO` is disabled. |
 | `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`. |

{executiontimer-1.0.0 → executiontimer-1.0.2}/benchmarks/README.md

@@ -18,21 +18,21 @@ make instrumentation costs visible; application speedups depend on the work bein
 ## 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.
+The baseline is commit `008494c` (version 0.1.0); the updated column is version 1.0.2.
+Both versions ran the same script, one after the other. Values below are microseconds per
+operation and include the benchmark function call; plain calls cost approximately
+0.02 µs and plain awaits 0.06 µ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% |
+| New context | 1.558 | 1.101 | 29% |
+| Reused context | 1.390 | 1.039 | 25% |
+| Decorated call | 1.623 | 1.129 | 30% |
+| Decorated await | 1.711 | 1.133 | 34% |
+| Five nested contexts | 7.961 | 5.380 | 32% |
+| Total time, 1,000 sections | 519.131 | 43.188 | 92% |
+| JSON, 1,000 sections | 1,235.188 | 1,064.559 | 14% |
+| Disabled logging, 1,000 sections | 572.003 | 0.098 | >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

{executiontimer-1.0.0 → executiontimer-1.0.2}/pyproject.toml

@@ -44,7 +44,8 @@ Issues = "https://github.com/seba2390/ExecutionTimer/issues"
 Changelog = "https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md"
 
 [build-system]
-requires = ["hatchling"]
+# 1.27 is the first release that supports PEP 639 license metadata (license-files).
+requires = ["hatchling>=1.27"]
 build-backend = "hatchling.build"
 
 [tool.hatch.version]
@@ -76,6 +77,9 @@ dev = [
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "--strict-markers --strict-config"
+# Any warning fails the suite, so code paths that warn are tested as they behave under
+# warnings-as-errors, a common configuration in projects that use this package.
+filterwarnings = ["error"]
 
 [tool.coverage.run]
 source = ["src/execution_timer"]
@@ -83,7 +87,7 @@ branch = true
 
 [tool.coverage.report]
 show_missing = true
-fail_under = 95
+fail_under = 100
 exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
 
 [tool.ruff]

{executiontimer-1.0.0 → executiontimer-1.0.2}/src/execution_timer/__init__.py

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

{executiontimer-1.0.0 → executiontimer-1.0.2}/src/execution_timer/_timer.py

@@ -74,11 +74,13 @@ class _Frame(NamedTuple):
 _ACTIVE_CONTEXT: ContextVar[_Frame | None] = ContextVar("execution_timer_context", default=None)
 
 
-def _ordered_by_hierarchy(keys: Iterable[tuple[str, ...]]) -> list[tuple[str, ...]]:
+def _ordered_by_hierarchy(keys: Iterable[tuple[str, ...]]) -> list[tuple[tuple[str, ...], int]]:
     """Order section paths depth-first so children always follow their parent.
 
-    Insertion order is preserved within each level, so a parent revisited after an unrelated
-    sibling still renders with its own children rather than beneath the sibling.
+    Returns each path with its depth in the recorded tree, which is shallower than the path
+    length when an ancestor is missing. Insertion order is preserved within each level, so a
+    parent revisited after an unrelated sibling still renders with its own children rather
+    than beneath the sibling.
     """
     keys = list(keys)
     known = set(keys)
@@ -92,16 +94,28 @@ def _ordered_by_hierarchy(keys: Iterable[tuple[str, ...]]) -> list[tuple[str, ..
         else:
             roots.append(key)
 
-    ordered: list[tuple[str, ...]] = []
+    ordered: list[tuple[tuple[str, ...], int]] = []
     # Explicit stack rather than recursion: nesting depth is user-controlled.
-    stack = list(reversed(roots))
+    stack = [(key, 0) for key in reversed(roots)]
     while stack:
-        key = stack.pop()
-        ordered.append(key)
-        stack.extend(reversed(children.get(key, [])))
+        key, depth = stack.pop()
+        ordered.append((key, depth))
+        stack.extend((child, depth + 1) for child in reversed(children.get(key, [])))
     return ordered
 
 
+def _top_level_time(timings: dict[tuple[str, ...], _TimesDict]) -> float:
+    """Sum the sections with no recorded parent, matching the roots of ``_ordered_by_hierarchy``.
+
+    A parent goes missing when timings are cleared while it is active; its children that
+    finish afterwards are then top-level and must count toward the total.
+    """
+    return sum(
+        (info["elapsed_time"] for key, info in timings.items() if len(key) == 1 or key[:-1] not in timings),
+        0.0,
+    )
+
+
 class _ExecutionTimer:
     """Registry of named, nestable timing sections, shared through ``_TIMER``."""
 
@@ -137,9 +151,10 @@ class _ExecutionTimer:
     def stop_timer(self, name: str) -> None:
         """Stop timing a section and accumulate its elapsed time.
 
-        Never raises: an exception here would replace one already propagating from the timed
-        block. Exiting past still-active inner sections (typically a suspended generator that
-        holds one open) discards them with a warning, so the stack cannot stay corrupted.
+        Never raises, unless warnings are configured as errors: an exception here would replace
+        one already propagating from the timed block. Exiting past still-active inner sections
+        (typically a suspended generator that holds one open) discards them with a warning,
+        after recording the exit, so the stack cannot stay corrupted.
         Exiting a section that is no longer active, such as one discarded that way when its
         generator is finally closed, does nothing.
         """
@@ -150,17 +165,18 @@ class _ExecutionTimer:
             frame = frame.parent
         if frame is None:
             return
+        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)
         if frame is not active and active is not None:
+            # Warn only once the state is consistent: warnings configured as errors raise here.
             msg = (
                 f"Section '{name}' exited while '{active.path[-1]}' was still active; discarding the "
                 "unfinished inner sections. Close sections before a generator yields."
             )
             warnings.warn(msg, RuntimeWarning, stacklevel=3)
-        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()
@@ -168,23 +184,25 @@ class _ExecutionTimer:
 
     def report_timings(self, *, flatten: bool = True) -> str:
         """Build a report of all sections with duration and percentage of total time."""
-        timings = self._resolve(flatten=flatten)
-        if not timings:
+        snapshot = self.snapshot()
+        if not snapshot:
             return ""
 
-        total_time = sum(info["elapsed_time"] for key, info in timings.items() if len(key) == 1)
+        # Total the unflattened paths, like get_total_time and the JSON export.
+        total_time = _top_level_time(snapshot)
+        timings = _flatten(snapshot) if flatten else snapshot
         report = [f"Total time: {total_time:.4f} s.\n"]
-        for key in _ordered_by_hierarchy(timings):
+        for key, depth in _ordered_by_hierarchy(timings):
             elapsed_time = timings[key]["elapsed_time"]
             percentage = (elapsed_time / total_time) * 100 if total_time else 0.0
-            report.append(f"{'..  ' * (len(key) - 1)}{key[-1]}: {elapsed_time:.4f} s ({percentage:.2f}%)")
+            report.append(f"{'..  ' * depth}{key[-1]}: {elapsed_time:.4f} s ({percentage:.2f}%)")
         return "\n".join(report)
 
     def compute_total_time(self) -> float:
         """Compute total elapsed time across all top-level sections."""
         # Counter merging cannot change the sum, so there is no snapshot to copy or flatten.
         with self._lock:
-            return sum((info["elapsed_time"] for key, info in self.timings.items() if len(key) == 1), 0.0)
+            return _top_level_time(self.timings)
 
     def compute_total_category_time(self, category: str) -> float:
         """Compute total elapsed time in a category, counting only top-most entries of that category."""
@@ -260,8 +278,9 @@ class TimerContext:
         """Decorate a function to time its execution under this context.
 
         Coroutine functions are wrapped so the timing spans the entire ``await``, not just
-        creation of the coroutine object. Generator functions are rejected: a wrapper would
-        time only creation of the generator object, not its iteration.
+        creation of the coroutine object. So is a coroutine returned by a plain function,
+        typically another decorator stacked on an ``async def``. Generator functions are
+        rejected: a wrapper would time only creation of the generator object, not its iteration.
         """
         if inspect.isgeneratorfunction(func) or inspect.isasyncgenfunction(func):
             msg = (
@@ -279,10 +298,20 @@ class TimerContext:
         @functools.wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             with self:
-                return func(*args, **kwargs)
+                result = func(*args, **kwargs)
+            if inspect.iscoroutine(result):
+                # A decorator between this one and an ``async def`` hides the coroutine function,
+                # so the call above only created the coroutine. Time awaiting it as well.
+                return cast("R", self._time_await(result))
+            return result
 
         return wrapper
 
+    async def _time_await(self, coroutine: Coroutine[object, object, T]) -> T:
+        """Await a coroutine that was created outside this context, timing the whole await."""
+        with self:
+            return await coroutine
+
     def _wrap_async(self, func: Callable[P, Coroutine[object, object, T]]) -> Callable[P, Coroutine[object, object, T]]:
         """Wrap a coroutine function so the timing spans the whole await."""
 
@@ -344,7 +373,7 @@ def _build_payload(*, flatten: bool = True) -> TimingsPayload:
             "time": round(timings[key]["elapsed_time"], 6),
             "category": timings[key]["category"],
         }
-        for key in _ordered_by_hierarchy(timings)
+        for key, _ in _ordered_by_hierarchy(timings)
     ]
     category_totals: dict[str, float] = {}
     for key, info in snapshot.items():
@@ -352,7 +381,7 @@ def _build_payload(*, flatten: bool = True) -> TimingsPayload:
         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(sum((info["elapsed_time"] for key, info in snapshot.items() if len(key) == 1), 0.0), 6),
+        "total_time": round(_top_level_time(snapshot), 6),
         "total_category_time": {cat: round(category_totals[cat], 6) for cat in sorted(category_totals)},
         "sections": sections,
     }

{executiontimer-1.0.0 → executiontimer-1.0.2}/tests/execution_timer_test.py

@@ -2,16 +2,18 @@
 
 import asyncio
 import builtins
+import functools
 import inspect
 import json
 import logging
 import threading
 import time
-from collections.abc import AsyncIterator, Generator, Iterator
+import warnings
+from collections.abc import AsyncIterator, Callable, Generator, Iterator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import ExitStack
 from pathlib import Path
-from typing import cast
+from typing import ParamSpec, TypeVar, cast
 from unittest.mock import patch
 
 import pytest
@@ -33,6 +35,9 @@ from execution_timer import (
     save_execution_timings_json,
 )
 
+P = ParamSpec("P")
+R = TypeVar("R")
+
 
 @pytest.fixture(autouse=True)
 def reset_timer() -> Iterator[None]:
@@ -641,6 +646,89 @@ class TestAsyncDecorator:
         assert ("child",) not in timings
 
 
+def passthrough(func: Callable[P, R]) -> Callable[P, R]:
+    """A plain decorator that hides whether ``func`` is a coroutine function."""
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+class TestStackedAsyncDecorator:
+    """A plain decorator between ``TimerContext`` and an ``async def`` returns its coroutine."""
+
+    def test_times_the_await_not_just_the_call(self) -> None:
+        @TimerContext("stacked")
+        @passthrough
+        async def work() -> None:
+            await asyncio.sleep(0)
+
+        # The call that creates the coroutine takes 1 s, and awaiting it takes 4 s.
+        with patch.object(time, "perf_counter", side_effect=[0, 1, 1, 5]):
+            asyncio.run(work())
+
+        assert raw_timings() == {("stacked",): {"time": 5, "category": DEFAULT_CATEGORY}}
+
+    def test_real_await_is_covered(self) -> None:
+        @TimerContext("stacked")
+        @passthrough
+        async def work() -> None:
+            await asyncio.sleep(0.05)
+
+        asyncio.run(work())
+
+        # Same threshold rationale as the plain async decorator test above.
+        assert raw_timings()["stacked",]["time"] >= 0.01
+
+    def test_sections_inside_the_coroutine_nest_under_it(self) -> None:
+        @TimerContext("stacked")
+        @passthrough
+        async def work() -> None:
+            with TimerContext("inner"):
+                await asyncio.sleep(0)
+
+        async def main() -> None:
+            with TimerContext("outer"):
+                await work()
+
+        asyncio.run(main())
+
+        assert set(raw_timings()) == {("outer",), ("outer", "stacked"), ("outer", "stacked", "inner")}
+
+    def test_preserves_return_value_and_exceptions(self) -> None:
+        @TimerContext("compute")
+        @passthrough
+        async def compute() -> int:
+            await asyncio.sleep(0)
+            return 42
+
+        @TimerContext("failing")
+        @passthrough
+        async def failing() -> None:
+            await asyncio.sleep(0)
+            raise ValueError("bad")
+
+        assert asyncio.run(compute()) == 42
+        with pytest.raises(ValueError, match="bad"):
+            asyncio.run(failing())
+        assert set(raw_timings()) == {("compute",), ("failing",)}
+
+    def test_other_awaitables_are_returned_unchanged(self) -> None:
+        loop = asyncio.new_event_loop()
+        try:
+            future: asyncio.Future[int] = loop.create_future()
+
+            @TimerContext("returns_future")
+            def get_future() -> asyncio.Future[int]:
+                return future
+
+            assert get_future() is future
+        finally:
+            loop.close()
+
+
 class TestContextManagerProtocol:
     def test_enter_returns_the_context(self) -> None:
         with TimerContext("named", category="gpu", counter=2) as ctx:
@@ -935,6 +1023,23 @@ class TestLifecycle:
             pass
         assert list(raw_timings()) == [("caller",), ("caller", "generator"), ("after",)]
 
+    def test_warnings_as_errors_still_record_and_unwind_before_raising(self) -> None:
+        def numbers() -> Generator[int]:
+            with TimerContext("generator"):
+                yield 1
+
+        paused = numbers()
+        with patch.object(time, "perf_counter", side_effect=[0, 1, 3]), warnings.catch_warnings():
+            warnings.simplefilter("error", RuntimeWarning)
+            with pytest.raises(RuntimeWarning), TimerContext("caller"):
+                _ = next(paused)
+                raise KeyError("from the body")
+        paused.close()
+        with TimerContext("after"):
+            pass
+        assert raw_timings()["caller",]["time"] == 3.0
+        assert list(raw_timings()) == [("caller",), ("caller", "generator"), ("after",)]
+
     def test_exiting_a_section_that_is_not_active_leaves_the_stack_intact(self) -> None:
         with TimerContext("outer"):
             TimerContext("stranger").__exit__(None, None, None)
@@ -952,12 +1057,31 @@ class TestLifecycle:
             with TimerContext("child", category="cpu"):
                 pass
         assert list(raw_timings()) == [("parent", "child")]
-        assert "child: 2.0000 s (0.00%)" in get_execution_times_report()
+        # The cleared parent is gone, so its child is top-level: it counts toward the total
+        # and is not indented beneath an unrelated section.
+        assert get_execution_times_report() == "Total time: 2.0000 s.\n\nchild: 2.0000 s (100.00%)"
+        assert get_total_time() == 2.0
         payload = cast(TimingsPayload, json.loads(get_execution_times_json()))
-        assert payload["total_time"] == 0.0
+        assert payload["total_time"] == 2.0
         assert payload["total_category_time"] == {"cpu": 2.0}
         assert payload["sections"][0]["path"] == ["parent", "child"]
 
+    def test_periodic_clear_inside_an_outer_section_reports_each_interval(self) -> None:
+        clock = [0, 1, 2, 3, 4, 10, 11, 12, 14, 20, 30, 31]
+        with patch.object(time, "perf_counter", side_effect=clock):
+            with TimerContext("main"):
+                for batch in range(2):
+                    with TimerContext("load"), TimerContext("parse"):
+                        pass
+                    if batch == 0:
+                        clear_execution_timings()
+            with TimerContext("after"):
+                pass
+        assert get_execution_times_report() == (
+            "Total time: 5.0000 s.\n\nload: 4.0000 s (80.00%)\n..  parse: 1.0000 s (20.00%)\nafter: 1.0000 s (20.00%)"
+        )
+        assert get_total_time() == 5.0
+
     def test_deep_reports_do_not_depend_on_python_recursion_limit(self) -> None:
         with ExitStack() as stack:
             for _ in range(1_100):