executiontimer 1.0.1__tar.gz → 1.0.2__tar.gz

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

@@ -7,6 +7,29 @@ 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
@@ -149,7 +172,8 @@ 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.1...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

{executiontimer-1.0.1 → 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.1 → executiontimer-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 1.0.1
+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
@@ -286,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
 
@@ -294,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.1 → 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
@@ -255,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
 
@@ -263,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.1 → 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.1 → executiontimer-1.0.2}/pyproject.toml

@@ -77,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"]
@@ -84,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.1 → 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.1"
+__version__ = "1.0.2"
 
 __all__ = [
     "DEFAULT_CATEGORY",

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

@@ -278,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 = (
@@ -297,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."""
 

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

@@ -2,17 +2,18 @@
 
 import asyncio
 import builtins
+import functools
 import inspect
 import json
 import logging
 import threading
 import time
 import warnings
-from collections.abc import AsyncIterator, Generator, Iterator
+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
@@ -34,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]:
@@ -642,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: