executiontimer 0.2.0__tar.gz → 1.0.1__tar.gz

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

@@ -7,6 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+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
@@ -85,7 +149,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/v0.2.0...HEAD
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.1...HEAD
+[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
 [0.1.0]: https://github.com/seba2390/ExecutionTimer/releases/tag/v0.1.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.2.0
+Version: 1.0.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
@@ -11,7 +11,7 @@ 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
@@ -103,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%)
@@ -156,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:
@@ -252,6 +257,12 @@ across a `yield` therefore also contains whatever the caller times while the gen
 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. 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
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -266,14 +277,15 @@ 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
 
 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
@@ -281,12 +293,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 (`flatten` has no effect on the sum). |
+| `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`. |
@@ -309,9 +321,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.2.0 → executiontimer-1.0.1}/README.md

@@ -72,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%)
@@ -125,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:
@@ -221,6 +226,12 @@ across a `yield` therefore also contains whatever the caller times while the gen
 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. 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
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -235,14 +246,15 @@ 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
 
 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
@@ -250,12 +262,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 (`flatten` has no effect on the sum). |
+| `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`. |
@@ -278,9 +290,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.2.0 → executiontimer-1.0.1}/pyproject.toml

@@ -18,7 +18,7 @@ keywords = [
     "decorator",
 ]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
@@ -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]

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

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

{executiontimer-0.2.0 → executiontimer-1.0.1}/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
@@ -73,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)
@@ -91,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``."""
 
@@ -134,18 +149,34 @@ 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, 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.
+        """
         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.")
         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)
 
     def _resolve(self, *, flatten: bool) -> dict[tuple[str, ...], _TimesDict]:
         snapshot = self.snapshot()
@@ -153,25 +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:
-            _LOGGER.warning("No timings to report.")
+        snapshot = self.snapshot()
+        if not snapshot:
             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"]
-        for key in _ordered_by_hierarchy(timings):
+        # 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, 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, *, 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)
+            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."""
@@ -232,16 +263,16 @@ 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.
@@ -299,18 +330,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):
         report = get_execution_times_report(flatten=flatten)
-        # An empty report has already been warned about; logging it would add a blank record.
         if report:
-            target.info(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]:
@@ -329,7 +362,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():
@@ -337,7 +370,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,
     }
@@ -355,13 +388,9 @@ def save_execution_timings_json(path: str | Path, *, flatten: bool = True, inden
     return out
 
 
-def get_total_time(*, flatten: bool = True) -> float:
-    """Get total elapsed seconds across all top-level sections.
-
-    ``flatten`` has no effect, because merging counter variants cannot change the total. It is
-    accepted for symmetry with the other reporting functions.
-    """
-    return _TIMER.compute_total_time(flatten=flatten)
+def get_total_time() -> float:
+    """Get total elapsed seconds across all top-level sections."""
+    return _TIMER.compute_total_time()
 
 
 def get_total_category_time(category: str) -> float:

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

@@ -7,7 +7,8 @@ import json
 import logging
 import threading
 import time
-from collections.abc import AsyncIterator, Iterator
+import warnings
+from collections.abc import AsyncIterator, Generator, Iterator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import ExitStack
 from pathlib import Path
@@ -191,15 +192,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 +274,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:
@@ -381,7 +384,7 @@ class TestTimerContextDecorator:
         assert ("outer", "inner") in timings
 
     def test_decorating_a_generator_function_raises(self) -> None:
-        def numbers() -> Iterator[int]:
+        def numbers() -> Generator[int]:
             yield 1
 
         with pytest.raises(TypeError, match=r"Cannot decorate generator function '.*numbers'"):
@@ -716,8 +719,8 @@ 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"]
 
@@ -903,18 +906,59 @@ 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_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)
+            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)
@@ -926,17 +970,36 @@ 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):
                 _ = 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")
@@ -996,7 +1059,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)) == {
@@ -1024,5 +1087,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))
         ]