executiontimer 0.2.0__tar.gz → 1.0.0__tar.gz

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

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -85,7 +129,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/v0.2.0...HEAD
+[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.2.0 → executiontimer-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.2.0
+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,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,11 @@ 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.
+
 ### Reusing contexts and clearing timings
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -273,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
@@ -281,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 (`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 +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.2.0 → executiontimer-1.0.0}/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,11 @@ 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.
+
 ### Reusing contexts and clearing timings
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -242,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
@@ -250,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 (`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 +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.2.0 → executiontimer-1.0.0}/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",

{executiontimer-0.2.0 → executiontimer-1.0.0}/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.0"
 
 __all__ = [
     "DEFAULT_CATEGORY",

{executiontimer-0.2.0 → 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,16 +245,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 +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):
         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]:
@@ -355,13 +370,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.0}/tests/execution_timer_test.py

@@ -7,7 +7,7 @@ import json
 import logging
 import threading
 import time
-from collections.abc import AsyncIterator, 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:
@@ -381,7 +383,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 +718,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 +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)
@@ -936,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")
@@ -996,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)) == {
@@ -1024,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))
         ]