executiontimer 0.1.1__tar.gz → 1.0.0__tar.gz

executiontimer-1.0.0/CHANGELOG.md

@@ -0,0 +1,136 @@
+# 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]
+
+## [1.0.0] - 2026-09-30
+
+First stable release. The public API is now covered by semantic versioning: breaking
+changes will wait for 2.0. Three changes below are breaking; they clean up the API before
+it is frozen.
+
+### Changed
+
+- **Breaking:** the report from `get_execution_times_report()` no longer starts with a
+  blank line, and its header reads `Total time:` rather than `Total calculation time:`.
+  `log_execution_times()` still starts the report on its own line.
+- **Breaking:** `TimerContext.timer` is now private (`_timer`). It exposed the internal
+  registry, which is not part of the public API.
+- `get_execution_times_report()` no longer logs a warning when there are no timings; it
+  returns `""`. `log_execution_times()` warns instead, on the logger it was given, so
+  building an empty report no longer prints to stderr when logging is not configured.
+- The package is classified as `Development Status :: 5 - Production/Stable`.
+
+### Removed
+
+- **Breaking:** the `flatten` parameter of `get_total_time()`, which had no effect.
+
+### Documentation
+
+- README links to the changelog, contributing guide, benchmarks and license are absolute,
+  so they work on PyPI.
+- Note that each `counter=` value is kept as a separate section until the timings are
+  cleared.
+
+### Fixed
+
+- Exiting a section while an inner one is still active, typically because a paused
+  generator holds a section open, no longer raises `RuntimeError`. The raise replaced any
+  exception already propagating from the timed block and left the active stack corrupted
+  for the rest of the thread. The timer now emits a `RuntimeWarning`, records the exited
+  section, and discards the unfinished inner sections. Exiting a section that is no longer
+  active does nothing, so closing the paused generator later no longer raises either.
+
+### Security
+
+- Workflows pin every action to a full commit SHA, with the release as a comment that
+  Dependabot keeps current, and CI installs dependencies with `uv sync --locked` so a
+  stale lockfile fails the build.
+
+## [0.2.0] - 2026-09-30
+
+### Changed
+
+- Decorating a generator function or an async generator function now raises `TypeError`.
+  Previously it silently timed only the creation of the generator object, which recorded
+  microseconds regardless of how long iteration took.
+- Python 3.11 is now supported; the minimum was 3.12 although nothing required it.
+
+### Fixed
+
+- `log_execution_times()` no longer logs an empty `INFO` record, after its warning, when
+  there are no timings.
+
+### Documentation
+
+- Explain that threads do not inherit the timing context, and how to nest thread work under
+  a section.
+- Explain how a section held open across a generator's `yield` absorbs the caller's sections.
+- Note that `flatten` has no effect on `get_total_time`.
+
+### Added
+
+- CI tests Python 3.11 and free-threaded Python 3.14t, and the package declares
+  free-threading support.
+- Workflows run with a read-only token by default and do not persist checkout credentials.
+
+## [0.1.1] - 2026-09-20
+
+### Fixed
+
+- Overlapping calls to the same section now accumulate each call's actual duration in
+  threads and asyncio tasks, including calls sharing one context or decorator.
+- Clearing active timings cannot add a discarded sample to a new entry at the same path.
+- JSON sections and totals now use one consistent snapshot, and category totals retain
+  categories that disappear when counter variants are merged.
+- Flattened categories follow the most recently entered section, including revisited counters.
+- Flattening preserves non-integer bracket suffixes such as `array[index]` and `empty[]`.
+- An out-of-order context exit raises `RuntimeError` without changing another section's
+  elapsed time or active stack.
+
+### Performance
+
+- Cache each active section's path and parent, and reuse decorator contexts to reduce
+  recording allocations and avoid rebuilding paths on exit.
+- Sum total time directly without copying and flattening the registry.
+- Calculate all JSON category totals in one pass over a shared snapshot.
+- Skip report generation when logging at `INFO` is disabled.
+
+### Added
+
+- Deterministic regression tests for concurrency, clearing, category attribution, and
+  snapshot consistency, plus coverage for recursion, cancellation, and deep nesting.
+- A repeatable benchmark for recording and reporting overhead in `benchmarks/overhead.py`.
+- Expanded the suite from 53 to 88 tests, achieving 100% statement and branch coverage.
+
+## [0.1.0] - 2026-08-20
+
+First public release on PyPI.
+
+### Added
+
+- `TimerContext` — context manager and decorator for timing a named section of code, with
+  optional `category` and `counter` arguments.
+- Automatic hierarchical nesting: section names reflect the enclosing timing contexts.
+- Native `async def` support — decorating a coroutine function times the whole `await`
+  rather than the creation of the coroutine object.
+- Per-task and per-thread context isolation via `contextvars`, so concurrently recorded
+  sections nest independently and merge into one process-wide report.
+- Reporting and export helpers: `get_execution_times_report`, `log_execution_times`,
+  `get_execution_timings`, `get_execution_times_json`, `save_execution_timings_json`,
+  `get_total_time`, `get_total_category_time`.
+- Optional nesting rules via `register_forbidden_nesting` / `clear_forbidden_nesting`.
+- `clear_execution_timings` to reset the registry.
+- Exported `TimingReport`, `SectionRecord` and `TimingsPayload` typed dictionaries, plus a
+  `py.typed` marker so type checkers use the inline annotations.
+- `__version__` attribute on the package.
+
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.0...HEAD
+[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
+[0.1.0]: https://github.com/seba2390/ExecutionTimer/releases/tag/v0.1.0

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

@@ -26,11 +26,12 @@ 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.
+The test suite is also run against Python 3.11, 3.12, 3.13, 3.14 and free-threaded 3.14t
+on Linux, macOS and Windows.
 To check another interpreter locally:
 
 ```bash
-uv run --python 3.12 pytest
+uv run --python 3.11 pytest
 ```
 
 For changes to recording or reporting performance, compare the benchmark on the same

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.1.1
+Version: 1.0.0
 Summary: Hierarchical execution timing with user-defined categories.
 Project-URL: Homepage, https://github.com/seba2390/ExecutionTimer
 Project-URL: Documentation, https://github.com/seba2390/ExecutionTimer#readme
@@ -11,20 +11,22 @@ Author: Sebastian Yde Madsen
 License-Expression: MIT
 License-File: LICENSE
 Keywords: benchmark,context-manager,decorator,execution-time,instrumentation,performance,profiling,timing
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: System :: Benchmark
 Classifier: Typing :: Typed
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -55,7 +57,8 @@ Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
 - 🌳 **Automatic hierarchy** — nesting `with` blocks nests the report, no wiring required
 - 🏷️ **User-defined categories** — tag sections with any string (`"gpu"`, `"io"`, `"db"`) and get per-category totals
 - ⚡ **Native async** — decorating an `async def` times the whole `await`, not the coroutine object
-- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task
+- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task,
+  including on free-threaded Python builds
 - 🔢 **Loop counters** — time each iteration separately, then merge them back together
 - 📤 **JSON export** — structured output for dashboards, CI, or an LLM
 - 🚫 **Nesting rules** — optionally forbid one category inside another to catch mistakes early
@@ -71,7 +74,7 @@ pip install executiontimer
 uv add executiontimer
 ```
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 > **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
 >
@@ -100,7 +103,7 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total calculation time: 0.3156 s.
+Total time: 0.3156 s.
 
 load_data: 0.1219 s (38.62%)
 solve: 0.1937 s (61.38%)
@@ -131,6 +134,10 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+Generator functions (including `async` generators) cannot be decorated and raise a
+`TypeError`: the decorator would time only the creation of the generator object, not its
+iteration. Time the loop that consumes the generator with a `with` block instead.
+
 ### Counters
 
 Pass `counter=i` to time loop iterations separately. The report merges them by default
@@ -149,6 +156,11 @@ 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.
 
+Each counter value is stored as its own section until `clear_execution_timings()` is
+called, so a long-running process that times an unbounded loop with `counter=` keeps
+growing the registry. Clear it periodically, or drop `counter=` to accumulate into one
+section.
+
 ### Categories
 
 Categories are plain strings — use whatever fits your domain:
@@ -233,6 +245,23 @@ New asyncio tasks inherit the timing context in which they are created. Their se
 nest under that parent; changes to each task's active stack remain independent. Await
 child tasks inside the parent section if you want the parent duration to include them.
 
+New threads do *not* inherit the timing context, so sections recorded in a thread
+appear at the top level of the report, and their time is added to the total alongside
+the section that started the thread. To nest thread work under the current section, run
+it with `contextvars.copy_context().run(...)` or `asyncio.to_thread(...)`. Either way,
+concurrent threads accumulate overlapping time. (Free-threaded builds of Python 3.14 make
+threads inherit the context by default.)
+
+Generators run in their caller's context. A `with TimerContext(...)` block that stays open
+across a `yield` therefore also contains whatever the caller times while the generator is
+paused, and its duration includes that paused time. Close sections before yielding, or
+time the loop that consumes the generator instead.
+
+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.
+
 ### Reusing contexts and clearing timings
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -254,7 +283,7 @@ 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](benchmarks/README.md).
+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
@@ -262,12 +291,12 @@ results using the same interpreter and machine; see [benchmarks/README.md](bench
 | Function | Description |
 | --- | --- |
 | `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. |
-| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level. |
+| `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). |
 | `get_execution_timings(*, flatten=True)` | Timings as `dict[tuple[str, ...], TimingReport]`. |
 | `get_execution_times_json(*, flatten=True, indent=2)` | All timings as a JSON string. |
 | `save_execution_timings_json(path, *, flatten=True, indent=2)` | Write timings to a JSON file; returns the `Path`. |
-| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections. |
+| `get_total_time()` | Total seconds across all top-level sections. |
 | `get_total_category_time(category)` | Total seconds in a category (top-most entries only). |
 | `clear_execution_timings()` | Reset all recorded timings. |
 | `register_forbidden_nesting(outer, inner)` | Forbid `inner` category directly inside `outer`. |
@@ -290,9 +319,9 @@ uv run ruff check --fix && uv run ruff format
 uv run basedpyright
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, and
-[CHANGELOG.md](CHANGELOG.md) for release notes.
+See [CONTRIBUTING.md](https://github.com/seba2390/ExecutionTimer/blob/main/CONTRIBUTING.md) for the full workflow, and
+[CHANGELOG.md](https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md) for release notes.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE).

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

@@ -26,7 +26,8 @@ Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
 - 🌳 **Automatic hierarchy** — nesting `with` blocks nests the report, no wiring required
 - 🏷️ **User-defined categories** — tag sections with any string (`"gpu"`, `"io"`, `"db"`) and get per-category totals
 - ⚡ **Native async** — decorating an `async def` times the whole `await`, not the coroutine object
-- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task
+- 🧵 **Thread and task safe** — context stacks are isolated per thread and per asyncio task,
+  including on free-threaded Python builds
 - 🔢 **Loop counters** — time each iteration separately, then merge them back together
 - 📤 **JSON export** — structured output for dashboards, CI, or an LLM
 - 🚫 **Nesting rules** — optionally forbid one category inside another to catch mistakes early
@@ -42,7 +43,7 @@ pip install executiontimer
 uv add executiontimer
 ```
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 > **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
 >
@@ -71,7 +72,7 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total calculation time: 0.3156 s.
+Total time: 0.3156 s.
 
 load_data: 0.1219 s (38.62%)
 solve: 0.1937 s (61.38%)
@@ -102,6 +103,10 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+Generator functions (including `async` generators) cannot be decorated and raise a
+`TypeError`: the decorator would time only the creation of the generator object, not its
+iteration. Time the loop that consumes the generator with a `with` block instead.
+
 ### Counters
 
 Pass `counter=i` to time loop iterations separately. The report merges them by default
@@ -120,6 +125,11 @@ 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.
 
+Each counter value is stored as its own section until `clear_execution_timings()` is
+called, so a long-running process that times an unbounded loop with `counter=` keeps
+growing the registry. Clear it periodically, or drop `counter=` to accumulate into one
+section.
+
 ### Categories
 
 Categories are plain strings — use whatever fits your domain:
@@ -204,6 +214,23 @@ New asyncio tasks inherit the timing context in which they are created. Their se
 nest under that parent; changes to each task's active stack remain independent. Await
 child tasks inside the parent section if you want the parent duration to include them.
 
+New threads do *not* inherit the timing context, so sections recorded in a thread
+appear at the top level of the report, and their time is added to the total alongside
+the section that started the thread. To nest thread work under the current section, run
+it with `contextvars.copy_context().run(...)` or `asyncio.to_thread(...)`. Either way,
+concurrent threads accumulate overlapping time. (Free-threaded builds of Python 3.14 make
+threads inherit the context by default.)
+
+Generators run in their caller's context. A `with TimerContext(...)` block that stays open
+across a `yield` therefore also contains whatever the caller times while the generator is
+paused, and its duration includes that paused time. Close sections before yielding, or
+time the loop that consumes the generator instead.
+
+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.
+
 ### Reusing contexts and clearing timings
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -225,7 +252,7 @@ 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](benchmarks/README.md).
+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
@@ -233,12 +260,12 @@ results using the same interpreter and machine; see [benchmarks/README.md](bench
 | Function | Description |
 | --- | --- |
 | `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. |
-| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level. |
+| `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). |
 | `get_execution_timings(*, flatten=True)` | Timings as `dict[tuple[str, ...], TimingReport]`. |
 | `get_execution_times_json(*, flatten=True, indent=2)` | All timings as a JSON string. |
 | `save_execution_timings_json(path, *, flatten=True, indent=2)` | Write timings to a JSON file; returns the `Path`. |
-| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections. |
+| `get_total_time()` | Total seconds across all top-level sections. |
 | `get_total_category_time(category)` | Total seconds in a category (top-most entries only). |
 | `clear_execution_timings()` | Reset all recorded timings. |
 | `register_forbidden_nesting(outer, inner)` | Forbid `inner` category directly inside `outer`. |
@@ -261,9 +288,9 @@ uv run ruff check --fix && uv run ruff format
 uv run basedpyright
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow, and
-[CHANGELOG.md](CHANGELOG.md) for release notes.
+See [CONTRIBUTING.md](https://github.com/seba2390/ExecutionTimer/blob/main/CONTRIBUTING.md) for the full workflow, and
+[CHANGELOG.md](https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md) for release notes.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT — see [LICENSE](https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE).

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

@@ -5,7 +5,7 @@ description = "Hierarchical execution timing with user-defined categories."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 authors = [{ name = "Sebastian Yde Madsen" }]
 keywords = [
     "timing",
@@ -18,14 +18,16 @@ keywords = [
     "decorator",
 ]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Software Development",
     "Topic :: Software Development :: Testing",
@@ -85,7 +87,7 @@ fail_under = 95
 exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
 
 [tool.ruff]
-target-version = "py312"
+target-version = "py311"
 line-length = 120
 src = ["src", "tests"]
 
@@ -103,5 +105,5 @@ select = [
 
 [tool.basedpyright]
 typeCheckingMode = "recommended"
-pythonVersion = "3.12"
+pythonVersion = "3.11"
 include = ["src", "tests"]

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

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

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

@@ -14,6 +14,7 @@ import json
 import logging
 import threading
 import time
+import warnings
 from collections.abc import Callable, Coroutine, Iterable, Iterator
 from contextvars import ContextVar
 from itertools import count
@@ -134,13 +135,27 @@ class _ExecutionTimer:
         _ = _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."""
+        """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.
+        Exiting a section that is no longer active, such as one discarded that way when its
+        generator is finally closed, does nothing.
+        """
         end_time = time.perf_counter()
-        frame = _ACTIVE_CONTEXT.get()
+        active = _ACTIVE_CONTEXT.get()
+        frame = active
+        while frame is not None and frame.path[-1] != name:
+            frame = frame.parent
         if frame is None:
             return
-        if frame.path[-1] != name:
-            raise RuntimeError(f"Cannot stop '{name}' while '{frame.path[-1]}' is active.")
+        if frame is not active and active is not None:
+            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.
@@ -155,21 +170,19 @@ class _ExecutionTimer:
         """Build a report of all sections with duration and percentage of total time."""
         timings = self._resolve(flatten=flatten)
         if not timings:
-            _LOGGER.warning("No timings to report.")
             return ""
 
         total_time = sum(info["elapsed_time"] for key, info in timings.items() if len(key) == 1)
-        report = [f"\nTotal calculation time: {total_time:.4f} s.\n"]
+        report = [f"Total time: {total_time:.4f} s.\n"]
         for key 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}%)")
         return "\n".join(report)
 
-    def compute_total_time(self, *, flatten: bool = True) -> float:
+    def compute_total_time(self) -> float:
         """Compute total elapsed time across all top-level sections."""
-        # Counter merging cannot change the sum. Avoid allocating and flattening a snapshot.
-        _ = flatten
+        # 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)
 
@@ -232,23 +245,31 @@ 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 = _TIMER
+        self._timer: _ExecutionTimer = _TIMER
 
     def __enter__(self) -> TimerContext:
-        self.timer.start_timer(self.name, self.category)
+        self._timer.start_timer(self.name, self.category)
         return self
 
     def __exit__(
         self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
     ) -> None:
-        self.timer.stop_timer(self.name)
+        self._timer.stop_timer(self.name)
 
     def __call__(self, func: Callable[P, R]) -> Callable[P, R]:
         """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.
+        creation of the coroutine object. 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 = (
+                f"Cannot decorate generator function {func.__qualname__!r}: only creating the generator "
+                "would be timed. Time the loop that consumes it, or its body between yields, with a "
+                "'with TimerContext(...)' block instead."
+            )
+            raise TypeError(msg)
         if inspect.iscoroutinefunction(func):
             # ``iscoroutinefunction`` narrows nothing useful for the type checker, so bridge
             # through an explicitly typed helper instead of leaking ``Any`` into the signature.
@@ -291,15 +312,20 @@ def _basic_name_without_counter(name: str) -> str:
 
 
 def get_execution_times_report(*, flatten: bool = True) -> str:
-    """Get a formatted report of all recorded sections; flatten counters if requested."""
+    """Get a formatted report of all recorded sections (``""`` if none); flatten counters if requested."""
     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."""
+    """Log the execution-times report at INFO level, or a warning if there is nothing to report."""
     target = logger if logger is not None else _LOGGER
     if target.isEnabledFor(logging.INFO):
-        target.info(get_execution_times_report(flatten=flatten))
+        report = get_execution_times_report(flatten=flatten)
+        if report:
+            # Start the multi-line report on its own line, after the log record's prefix.
+            target.info("\n%s", report)
+        else:
+            target.warning("No timings to report.")
 
 
 def get_execution_timings(*, flatten: bool = True) -> dict[tuple[str, ...], TimingReport]:
@@ -344,9 +370,9 @@ def save_execution_timings_json(path: str | Path, *, flatten: bool = True, inden
     return out
 
 
-def get_total_time(*, flatten: bool = True) -> float:
+def get_total_time() -> float:
     """Get total elapsed seconds across all top-level sections."""
-    return _TIMER.compute_total_time(flatten=flatten)
+    return _TIMER.compute_total_time()
 
 
 def get_total_category_time(category: str) -> float:

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

@@ -7,7 +7,7 @@ import json
 import logging
 import threading
 import time
-from collections.abc import Iterator
+from collections.abc import AsyncIterator, Generator, Iterator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import ExitStack
 from pathlib import Path
@@ -191,15 +191,17 @@ class TestReporting:
 
         report = get_execution_times_report()
 
-        assert "Total calculation time" in report
+        assert report.startswith("Total time: ")
         assert "context_report:" in report
         assert "context_report_nested:" in report
         for i in range(3):
             assert f"..  context_sub_{i}:" in report
             assert f"..  ..  context_subsub_{i}:" in report
 
-    def test_report_empty_when_no_timings(self) -> None:
-        assert get_execution_times_report() == ""
+    def test_report_empty_when_no_timings(self, caplog: pytest.LogCaptureFixture) -> None:
+        with caplog.at_level(logging.DEBUG):
+            assert get_execution_times_report() == ""
+        assert caplog.records == []
 
     def test_report_flatten_flag(self) -> None:
         with patch.object(time, "perf_counter", side_effect=[0, 1, 1, 2]):
@@ -271,7 +273,7 @@ class TestOutput:
         with caplog.at_level(logging.INFO):
             log_execution_times()
 
-        assert "Total calculation time" in caplog.text
+        assert "Total time: " in caplog.text
         assert "logged:" in caplog.text
 
     def test_get_execution_times_json_is_valid_and_structured(self) -> None:
@@ -380,6 +382,32 @@ class TestTimerContextDecorator:
         assert ("outer",) in timings
         assert ("outer", "inner") in timings
 
+    def test_decorating_a_generator_function_raises(self) -> None:
+        def numbers() -> Generator[int]:
+            yield 1
+
+        with pytest.raises(TypeError, match=r"Cannot decorate generator function '.*numbers'"):
+            _ = TimerContext("gen")(numbers)
+        assert raw_timings() == {}
+
+    def test_decorating_an_async_generator_function_raises(self) -> None:
+        async def numbers() -> AsyncIterator[int]:
+            yield 1
+
+        with pytest.raises(TypeError, match=r"Cannot decorate generator function '.*numbers'"):
+            _ = TimerContext("agen")(numbers)
+        assert raw_timings() == {}
+
+    def test_decorator_accepts_a_function_returning_a_generator(self) -> None:
+        """Only generator *functions* are rejected; a plain function may return an iterator."""
+
+        @TimerContext("factory")
+        def factory() -> Iterator[int]:
+            return iter([1, 2])
+
+        assert list(factory()) == [1, 2]
+        assert ("factory",) in raw_timings()
+
 
 class TestExceptions:
     def test_timing_recorded_when_body_raises(self) -> None:
@@ -690,11 +718,19 @@ class TestRobustness:
         assert errors == []
 
     def test_logging_uses_the_package_logger_not_the_root_logger(self, caplog: pytest.LogCaptureFixture) -> None:
-        with caplog.at_level(logging.WARNING):
-            assert get_execution_times_report() == ""
+        with caplog.at_level(logging.INFO):
+            log_execution_times()
 
         assert [record.name for record in caplog.records] == ["execution_timer._timer"]
 
+    def test_logging_an_empty_registry_emits_only_the_warning(self, caplog: pytest.LogCaptureFixture) -> None:
+        with caplog.at_level(logging.INFO):
+            log_execution_times()
+
+        assert [(record.levelno, record.message) for record in caplog.records] == [
+            (logging.WARNING, "No timings to report.")
+        ]
+
 
 class TestRegressions:
     @pytest.mark.parametrize("clear_between_calls", [False, True])
@@ -869,18 +905,42 @@ class TestLifecycle:
             pass
         assert ("gpu", "io", "cpu") in raw_timings()
 
-    def test_out_of_order_exit_raises_without_changing_the_active_section(self) -> None:
+    def test_out_of_order_exit_unwinds_to_the_exited_section_and_warns(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
+        with patch.object(time, "perf_counter", side_effect=[0, 1, 3]):
+            _ = outer.__enter__()
+            _ = inner.__enter__()
+            with pytest.warns(RuntimeWarning, match="'outer' exited while 'inner' was still active"):
+                outer.__exit__(None, None, None)
+        with TimerContext("after"):
+            pass
+        assert raw_timings()["outer",]["time"] == 3.0
+        assert raw_timings()["outer", "inner"]["time"] == 0.0
+        assert ("after",) in raw_timings()
+
+    def test_abandoned_generator_section_does_not_break_the_caller(self) -> None:
+        def numbers() -> Generator[int]:
+            with TimerContext("generator"):
+                yield 1
+                yield 2
+
+        paused = numbers()
+        with pytest.warns(RuntimeWarning), pytest.raises(KeyError, match="from the body"), TimerContext("caller"):
+            _ = next(paused)
+            raise KeyError("from the body")
+        # Closing the generator later exits a section that is no longer active: a no-op.
+        paused.close()
+        with TimerContext("after"):
+            pass
+        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)
+            with TimerContext("inner"):
+                pass
+        assert list(raw_timings()) == [("outer",), ("outer", "inner")]
 
     def test_exit_without_an_active_section_is_a_noop(self) -> None:
         TimerContext("unused").__exit__(None, None, None)
@@ -902,7 +962,7 @@ class TestLifecycle:
         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
+        assert len(get_execution_times_report(flatten=False).splitlines()) == 1_102
 
     def test_async_cancellation_records_time_and_restores_parent(self) -> None:
         @TimerContext("cancelled")
@@ -962,7 +1022,7 @@ class TestSnapshotSemantics:
         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
+        assert get_total_time() == 5.0
 
     def test_empty_json(self) -> None:
         assert json.loads(get_execution_times_json(indent=None)) == {
@@ -990,5 +1050,5 @@ class TestSnapshotSemantics:
         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))
+            (logger.name, "\n" + get_execution_times_report(flatten=False))
         ]

executiontimer-0.1.1/CHANGELOG.md

@@ -1,63 +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.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