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

execution_timer/__init__.py

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

execution_timer/_timer.py

@@ -74,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)
@@ -92,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``."""
 
@@ -137,9 +151,10 @@ class _ExecutionTimer:
     def stop_timer(self, name: str) -> None:
         """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.
+        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.
         """
@@ -150,17 +165,18 @@ class _ExecutionTimer:
             frame = frame.parent
         if frame is None:
             return
+        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)
-        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)
 
     def _resolve(self, *, flatten: bool) -> dict[tuple[str, ...], _TimesDict]:
         snapshot = self.snapshot()
@@ -168,23 +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:
+        snapshot = self.snapshot()
+        if not snapshot:
             return ""
 
-        total_time = sum(info["elapsed_time"] for key, info in timings.items() if len(key) == 1)
+        # 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 in _ordered_by_hierarchy(timings):
+        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) -> float:
         """Compute total elapsed time across all top-level sections."""
         # 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."""
@@ -260,8 +278,9 @@ class TimerContext:
         """Decorate a function to time its execution under this context.
 
         Coroutine functions are wrapped so the timing spans the entire ``await``, not just
-        creation of the coroutine object. Generator functions are rejected: a wrapper would
-        time only creation of the generator object, not its iteration.
+        creation of the coroutine object. So is a coroutine returned by a plain function,
+        typically another decorator stacked on an ``async def``. Generator functions are
+        rejected: a wrapper would time only creation of the generator object, not its iteration.
         """
         if inspect.isgeneratorfunction(func) or inspect.isasyncgenfunction(func):
             msg = (
@@ -279,10 +298,20 @@ class TimerContext:
         @functools.wraps(func)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             with self:
-                return func(*args, **kwargs)
+                result = func(*args, **kwargs)
+            if inspect.iscoroutine(result):
+                # A decorator between this one and an ``async def`` hides the coroutine function,
+                # so the call above only created the coroutine. Time awaiting it as well.
+                return cast("R", self._time_await(result))
+            return result
 
         return wrapper
 
+    async def _time_await(self, coroutine: Coroutine[object, object, T]) -> T:
+        """Await a coroutine that was created outside this context, timing the whole await."""
+        with self:
+            return await coroutine
+
     def _wrap_async(self, func: Callable[P, Coroutine[object, object, T]]) -> Callable[P, Coroutine[object, object, T]]:
         """Wrap a coroutine function so the timing spans the whole await."""
 
@@ -344,7 +373,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():
@@ -352,7 +381,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,
     }

{executiontimer-1.0.0.dist-info → executiontimer-1.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 1.0.0
+Version: 1.0.2
 Summary: Hierarchical execution timing with user-defined categories.
 Project-URL: Homepage, https://github.com/seba2390/ExecutionTimer
 Project-URL: Documentation, https://github.com/seba2390/ExecutionTimer#readme
@@ -134,6 +134,9 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+This also holds when another decorator sits between `TimerContext` and the `async def`
+and returns its coroutine: the section covers both the call and the `await`.
+
 Generator functions (including `async` generators) cannot be decorated and raise a
 `TypeError`: the decorator would time only the creation of the generator object, not its
 iteration. Time the loop that consumes the generator with a `with` block instead.
@@ -153,7 +156,9 @@ get_execution_timings(flatten=False)  # {("step[0]",): ..., ("step[1]",): ..., .
 ```
 
 Flattening removes the final integer suffix (including negative counters). Other
-bracketed names such as `array[index]` are preserved. If merged entries have different
+bracketed names such as `array[index]` are preserved. Flattening cannot tell a counter
+from a name you wrote yourself, so sections named `"row[1]"` and `"row[2]"` are also merged
+into `row`; use `flatten=False` to keep them apart. If merged entries have different
 categories, the category from the most recently entered section is used.
 
 Each counter value is stored as its own section until `clear_execution_timings()` is
@@ -260,7 +265,8 @@ 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.
+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
 
@@ -276,7 +282,8 @@ 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
@@ -284,7 +291,6 @@ an active section's current duration is added only when it exits.
 Run the repeatable benchmark with `uv run python benchmarks/overhead.py`. It measures
 fresh and reused contexts, sync and async decorators, nesting, and reporting. Compare
 results using the same interpreter and machine; see [benchmarks/README.md](https://github.com/seba2390/ExecutionTimer/blob/main/benchmarks/README.md).
-`log_execution_times()` skips building a report when its logger has `INFO` disabled.
 
 ## API
 
@@ -292,7 +298,7 @@ results using the same interpreter and machine; see [benchmarks/README.md](https
 | --- | --- |
 | `TimerContext(name, category=DEFAULT_CATEGORY, counter=None)` | Context manager **and** decorator for timing a section. |
 | `get_execution_times_report(*, flatten=True)` | Formatted, indented report of all sections (`""` if none). |
-| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty). |
+| `log_execution_times(*, flatten=True, logger=None)` | Log that report at `INFO` level (a warning if empty); a no-op if `INFO` is disabled. |
 | `get_execution_timings(*, flatten=True)` | Timings as `dict[tuple[str, ...], TimingReport]`. |
 | `get_execution_times_json(*, flatten=True, indent=2)` | All timings as a JSON string. |
 | `save_execution_timings_json(path, *, flatten=True, indent=2)` | Write timings to a JSON file; returns the `Path`. |

executiontimer-1.0.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+execution_timer/__init__.py,sha256=WBDnG2RxhKZmuhb5U4wgVV4WNgvZehegtfBuSh7AA6I,959
+execution_timer/_timer.py,sha256=ermOhB2xWM4acsGgkHuN3MyeA9uqpa9FgNuoAABdGjY,17439
+execution_timer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+executiontimer-1.0.2.dist-info/METADATA,sha256=7hk9S89FJ0b9H-O2IAWak-c_ef55RS1Vq1pJPh4gCGY,13900
+executiontimer-1.0.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+executiontimer-1.0.2.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
+executiontimer-1.0.2.dist-info/RECORD,,

executiontimer-1.0.0.dist-info/RECORD

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