executiontimer 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

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",

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.dist-info → executiontimer-1.0.0.dist-info}/METADATA

@@ -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-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+execution_timer/__init__.py,sha256=gv9IbtkZkesfgWFh1oDSJ5DDr2BJFVxmKtY32jcUzbI,959
+execution_timer/_timer.py,sha256=iylgfJ1vBeKimsW5A3NVN5KSUvZs75Km-N4guoHKFPo,15932
+execution_timer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+executiontimer-1.0.0.dist-info/METADATA,sha256=ZtN7WHMrB8gTaGIy0VQLHDtu2ySFvd8oZx56KmA5F8s,13386
+executiontimer-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+executiontimer-1.0.0.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
+executiontimer-1.0.0.dist-info/RECORD,,

executiontimer-0.2.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-execution_timer/__init__.py,sha256=9A5FYIrOvXbohuQMyIis651hYdNmzvNLQxfR02pk92w,959
-execution_timer/_timer.py,sha256=4PSyP501arREnqOKtXEMwjbsb5sFISVYFRc1EXOXGP0,15366
-execution_timer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-executiontimer-0.2.0.dist-info/METADATA,sha256=B6G1utu8t7BPwVh8KFID_pPr-c9z2bW0M6hd8-eiPWg,12631
-executiontimer-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-executiontimer-0.2.0.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
-executiontimer-0.2.0.dist-info/RECORD,,