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

execution_timer/__init__.py

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

execution_timer/_timer.py

@@ -20,39 +20,49 @@ from contextvars import ContextVar
 from itertools import count
 from pathlib import Path
 from types import TracebackType
-from typing import Final, NamedTuple, ParamSpec, TypedDict, TypeVar, cast
+from typing import Final, ParamSpec, TypeAlias, TypedDict, TypeVar, cast
 
 P = ParamSpec("P")
 R = TypeVar("R")
 T = TypeVar("T")
 
 DEFAULT_CATEGORY: Final = "default"
+"""The category of sections created without one."""
 
 _LOGGER: Final = logging.getLogger(__name__)
 
 
 class TimingReport(TypedDict):
-    """Timing entry for one section: elapsed seconds and its category."""
+    """Timing entry for one section, as returned by :func:`get_execution_timings`."""
 
     time: float
+    """Accumulated elapsed seconds."""
     category: str
+    """The section's category."""
 
 
 class SectionRecord(TypedDict):
-    """One section in the JSON export."""
+    """One section in the JSON export, see :class:`TimingsPayload`."""
 
     name: str
+    """The section's own name, the last element of :attr:`path`."""
     path: list[str]
+    """Names from the top-level section down to this one."""
     time: float
+    """Accumulated elapsed seconds, rounded to microseconds."""
     category: str
+    """The section's category."""
 
 
 class TimingsPayload(TypedDict):
-    """Top-level JSON export payload."""
+    """Top-level object of the JSON export from :func:`get_execution_times_json`."""
 
     total_time: float
+    """Seconds across all top-level sections, as returned by :func:`get_total_time`."""
     total_category_time: dict[str, float]
+    """Seconds per category, counting only the top-most section of each category."""
     sections: list[SectionRecord]
+    """Every section, ordered depth-first so children follow their parent."""
 
 
 class _TimesDict(TypedDict):
@@ -61,14 +71,10 @@ class _TimesDict(TypedDict):
     category: str
 
 
-class _Frame(NamedTuple):
-    """Per-invocation state, with a cached path and an immutable parent link."""
-
-    path: tuple[str, ...]
-    category: str
-    start_time: float
-    entry: _TimesDict
-    parent: _Frame | None
+# Per-invocation state, with a cached path and an immutable parent link:
+# ``(path, category, start_time, entry, parent)``. A plain tuple rather than a NamedTuple,
+# whose constructor runs in Python and costs more than the rest of section entry combined.
+_Frame: TypeAlias = "tuple[tuple[str, ...], str, float, _TimesDict, _Frame | None]"
 
 
 _ACTIVE_CONTEXT: ContextVar[_Frame | None] = ContextVar("execution_timer_context", default=None)
@@ -133,10 +139,10 @@ class _ExecutionTimer:
     def start_timer(self, name: str, category: str) -> None:
         """Start timing a section under the given name within the active context."""
         parent = _ACTIVE_CONTEXT.get()
-        full_name = (*parent.path, name) if parent is not None else (name,)
+        full_name = (*parent[0], name) if parent is not None else (name,)
         with self._lock:
-            if parent is not None and (parent.category, category) in self.forbidden_nesting:
-                msg = f"Category '{category}' is not allowed inside category '{parent.category}'."
+            if parent is not None and (parent[1], category) in self.forbidden_nesting:
+                msg = f"Category '{category}' is not allowed inside category '{parent[1]}'."
                 raise ValueError(msg)
             sequence = next(self._sequence)
             entry: _TimesDict | None = self.timings.get(full_name)
@@ -146,7 +152,7 @@ class _ExecutionTimer:
             else:
                 entry["sequence"] = sequence
                 entry["category"] = category
-        _ = _ACTIVE_CONTEXT.set(_Frame(full_name, category, time.perf_counter(), entry, parent))
+        _ = _ACTIVE_CONTEXT.set((full_name, category, time.perf_counter(), entry, parent))
 
     def stop_timer(self, name: str) -> None:
         """Stop timing a section and accumulate its elapsed time.
@@ -161,19 +167,20 @@ class _ExecutionTimer:
         end_time = time.perf_counter()
         active = _ACTIVE_CONTEXT.get()
         frame = active
-        while frame is not None and frame.path[-1] != name:
-            frame = frame.parent
+        while frame is not None and frame[0][-1] != name:
+            frame = frame[4]
         if frame is None:
             return
+        _, _, start_time, entry, parent = frame
         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)
+            entry["elapsed_time"] += end_time - start_time
+        _ = _ACTIVE_CONTEXT.set(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 "
+                f"Section '{name}' exited while '{active[0][-1]}' was still active; discarding the "
                 "unfinished inner sections. Close sections before a generator yields."
             )
             warnings.warn(msg, RuntimeWarning, stacklevel=3)
@@ -191,11 +198,11 @@ class _ExecutionTimer:
         # 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"]
+        report = [f"Total time: {_format_duration(total_time)}.\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"{'..  ' * depth}{key[-1]}: {elapsed_time:.4f} s ({percentage:.2f}%)")
+            report.append(f"{'..  ' * depth}{key[-1]}: {_format_duration(elapsed_time)} ({percentage:.2f}%)")
         return "\n".join(report)
 
     def compute_total_time(self) -> float:
@@ -236,6 +243,20 @@ class _ExecutionTimer:
 _TIMER: Final = _ExecutionTimer()
 
 
+def _format_duration(seconds: float) -> str:
+    """Format seconds with three decimals in the largest of µs, ms and s that stays below 1000.
+
+    The unit is chosen after rounding, so 999.9996 µs reads ``1.000 ms`` rather than
+    ``1000.000 µs``. Sections of any length stay readable, where fixed seconds would show a
+    fast section as zero.
+    """
+    for scale, unit in ((1e6, "µs"), (1e3, "ms")):
+        scaled = seconds * scale
+        if round(scaled, 3) < 1000:
+            return f"{scaled:.3f} {unit}"
+    return f"{seconds:.3f} s"
+
+
 def _flatten(timings: dict[tuple[str, ...], _TimesDict]) -> dict[tuple[str, ...], _TimesDict]:
     flat_map: dict[tuple[str, ...], _TimesDict] = {}
     for key, info in timings.items():
@@ -258,7 +279,32 @@ def _has_ancestor_with_category(
 
 
 class TimerContext:
-    """Context manager and decorator for timing a named section of code."""
+    """Context manager and decorator for timing a named section of code.
+
+    Sections entered inside another section are recorded beneath it, so nesting ``with``
+    blocks or decorated calls builds the hierarchy shown in reports. Repeated entries of the
+    same section accumulate their durations. A context can be reused, re-entered while it is
+    active, and shared between threads and asyncio tasks.
+
+    Args:
+        name: The section's name within its parent.
+        category: Any string used to group sections, for example ``"io"`` or ``"gpu"``.
+        counter: Records the section as ``name[counter]``, typically a loop index. Reports
+            merge these variants unless you pass ``flatten=False``.
+
+    Raises:
+        ValueError: On entry, if a rule from :func:`register_forbidden_nesting` forbids this
+            category directly inside the enclosing section's category.
+
+    Example:
+        .. code-block:: python
+
+            with TimerContext("load", category="io"):
+                data = load()
+
+            @TimerContext("solve")
+            def solve(data): ...
+    """
 
     def __init__(self, name: str, category: str = DEFAULT_CATEGORY, counter: int | None = None) -> None:
         self.name: str = _build_name_with_counter(name, counter)
@@ -279,8 +325,11 @@ class TimerContext:
 
         Coroutine functions are wrapped so the timing spans the entire ``await``, not just
         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.
+        typically another decorator stacked on an ``async def``.
+
+        Raises:
+            TypeError: If ``func`` is a generator or async generator function. A wrapper
+                would time only creation of the generator object, not its iteration.
         """
         if inspect.isgeneratorfunction(func) or inspect.isasyncgenfunction(func):
             msg = (
@@ -341,12 +390,31 @@ 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 (``""`` if none); flatten counters if requested."""
+    """Get a formatted, indented report of all recorded sections.
+
+    Each line shows a section's accumulated time and its share of the total time.
+    Indentation reflects nesting. Times have three decimals, in ``µs``, ``ms`` or ``s``,
+    whichever keeps the number below 1000.
+
+    Args:
+        flatten: Merge ``counter`` variants such as ``step[0]`` and ``step[1]`` into ``step``.
+
+    Returns:
+        The report, or ``""`` if nothing has been recorded.
+    """
     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, or a warning if there is nothing to report."""
+    """Log the report from :func:`get_execution_times_report` at ``INFO`` level.
+
+    Logs a warning instead if nothing has been recorded. Does nothing, and skips building
+    the report, if the logger has ``INFO`` disabled.
+
+    Args:
+        flatten: Merge ``counter`` variants of a section.
+        logger: The logger to use. Defaults to the ``execution_timer._timer`` logger.
+    """
     target = logger if logger is not None else _LOGGER
     if target.isEnabledFor(logging.INFO):
         report = get_execution_times_report(flatten=flatten)
@@ -358,7 +426,15 @@ def log_execution_times(*, flatten: bool = True, logger: logging.Logger | None =
 
 
 def get_execution_timings(*, flatten: bool = True) -> dict[tuple[str, ...], TimingReport]:
-    """Get elapsed seconds and category for every recorded section; flatten counters if requested."""
+    """Get elapsed seconds and category for every recorded section.
+
+    Args:
+        flatten: Merge ``counter`` variants of a section.
+
+    Returns:
+        A new dictionary keyed by section path, such as ``("solve", "step")``. Changing it
+        does not affect the recorded timings.
+    """
     return _TIMER.get_execution_timings(flatten=flatten)
 
 
@@ -388,34 +464,79 @@ def _build_payload(*, flatten: bool = True) -> TimingsPayload:
 
 
 def get_execution_times_json(*, flatten: bool = True, indent: int | None = 2) -> str:
-    """Get all timings as a JSON string (LLM-friendly); flatten counters if requested."""
+    """Get all timings as a JSON document shaped like :class:`TimingsPayload`.
+
+    Args:
+        flatten: Merge ``counter`` variants of a section.
+        indent: Passed to :func:`json.dumps`; ``None`` gives the most compact output.
+
+    Returns:
+        The JSON text.
+    """
     return json.dumps(_build_payload(flatten=flatten), indent=indent)
 
 
 def save_execution_timings_json(path: str | Path, *, flatten: bool = True, indent: int | None = 2) -> Path:
-    """Write all timings to a JSON file and return its path; flatten counters if requested."""
+    """Write the JSON from :func:`get_execution_times_json` to a UTF-8 file.
+
+    Args:
+        path: The file to write, replacing it if it exists. Its directory must exist.
+        flatten: Merge ``counter`` variants of a section.
+        indent: Passed to :func:`json.dumps`.
+
+    Returns:
+        The path written to.
+    """
     out = Path(path)
     _ = out.write_text(get_execution_times_json(flatten=flatten, indent=indent) + "\n", encoding="utf-8")
     return out
 
 
 def get_total_time() -> float:
-    """Get total elapsed seconds across all top-level sections."""
+    """Get total elapsed seconds across all top-level sections.
+
+    Nested sections are part of their parent's time, so they are not added again.
+
+    Returns:
+        The total, or ``0.0`` if nothing has been recorded.
+    """
     return _TIMER.compute_total_time()
 
 
 def get_total_category_time(category: str) -> float:
-    """Get total elapsed seconds in a category, counting only top-most entries of that category."""
+    """Get total elapsed seconds in a category.
+
+    Only the top-most section of the category counts: a section nested inside another of
+    the same category is part of that section's time and is not added again.
+
+    Args:
+        category: The category to total.
+
+    Returns:
+        The total, or ``0.0`` for a category with no sections.
+    """
     return _TIMER.compute_total_category_time(category)
 
 
 def clear_execution_timings() -> None:
-    """Reset all recorded timings."""
+    """Discard all recorded timings.
+
+    A section that is active during the clear is not recorded when it exits. Sections
+    started inside it afterwards are recorded as top-level sections. Nesting rules are kept;
+    see :func:`clear_forbidden_nesting`.
+    """
     _TIMER.clear()
 
 
 def register_forbidden_nesting(outer: str, inner: str) -> None:
-    """Forbid timing sections of category ``inner`` directly inside sections of category ``outer``."""
+    """Forbid sections of category ``inner`` directly inside sections of category ``outer``.
+
+    Entering such a section raises :class:`ValueError`. Only the direct parent is checked.
+
+    Args:
+        outer: The enclosing section's category.
+        inner: The category that may not appear directly inside it.
+    """
     _TIMER.register_forbidden_nesting(outer, inner)
 
 

executiontimer-1.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: executiontimer
+Version: 1.1.0
+Summary: Hierarchical execution timing with user-defined categories.
+Project-URL: Homepage, https://github.com/seba2390/ExecutionTimer
+Project-URL: Documentation, https://seba2390.github.io/ExecutionTimer/
+Project-URL: Repository, https://github.com/seba2390/ExecutionTimer
+Project-URL: Issues, https://github.com/seba2390/ExecutionTimer/issues
+Project-URL: Changelog, https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md
+Author: Sebastian Yde Madsen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: benchmark,context-manager,decorator,execution-time,instrumentation,performance,profiling,timing
+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.11
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-light.svg">
+    <img src="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-light.svg" alt="executiontimer" width="520">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/executiontimer/"><img src="https://img.shields.io/pypi/v/executiontimer?color=blue" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/executiontimer/"><img src="https://img.shields.io/pypi/pyversions/executiontimer" alt="Python versions"></a>
+  <a href="https://github.com/seba2390/ExecutionTimer/actions/workflows/ci.yml"><img src="https://github.com/seba2390/ExecutionTimer/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://seba2390.github.io/ExecutionTimer/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-4F46E5" alt="Documentation"></a>
+</p>
+
+Time named sections of your code with a `with` block or a decorator. Sections nested inside
+each other form a tree, so you see where the time actually went, not just one number at the
+end.
+
+Zero dependencies. Fully typed. Works with threads and `asyncio`.
+
+## Documentation 
+[seba2390.github.io/ExecutionTimer](https://seba2390.github.io/ExecutionTimer/)
+
+## Installation
+
+```bash
+pip install executiontimer
+```
+
+Requires Python 3.11+. The install name is `executiontimer`; the import name is
+`execution_timer`.
+
+## Quick start
+
+```python
+import time
+
+from execution_timer import TimerContext, get_execution_times_report
+
+with TimerContext("load_data"):
+    time.sleep(0.12)
+
+with TimerContext("solve"):
+    for i in range(3):
+        with TimerContext("step", category="gpu", counter=i):
+            time.sleep(0.05)
+    with TimerContext("postprocess", category="cpu"):
+        time.sleep(0.03)
+
+print(get_execution_times_report())
+```
+
+```text
+Total time: 312.838 ms.
+
+load_data: 124.682 ms (39.85%)
+solve: 188.157 ms (60.15%)
+..  step: 154.718 ms (49.46%)
+..  postprocess: 33.295 ms (10.64%)
+```
+
+`TimerContext` also works as a decorator, including on `async def` functions:
+
+```python
+@TimerContext("preprocess")
+def preprocess(rows: list[str]) -> list[str]:
+    return [row.strip() for row in rows]
+```
+
+## Learn more
+
+- [Getting started](https://seba2390.github.io/ExecutionTimer/getting-started.html)
+- User guide: [timing code](https://seba2390.github.io/ExecutionTimer/guide/timing-code.html),
+  [counters](https://seba2390.github.io/ExecutionTimer/guide/counters.html),
+  [categories](https://seba2390.github.io/ExecutionTimer/guide/categories.html),
+  [reports and JSON export](https://seba2390.github.io/ExecutionTimer/guide/reports.html),
+  [threads, asyncio and generators](https://seba2390.github.io/ExecutionTimer/guide/concurrency.html)
+- [API reference](https://seba2390.github.io/ExecutionTimer/api.html)
+- [Changelog](https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md) and
+  [contributing guide](https://github.com/seba2390/ExecutionTimer/blob/main/CONTRIBUTING.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE).

executiontimer-1.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+execution_timer/__init__.py,sha256=HrXnAPwlQzzTpSRBVk_j-OLc-RNRS3WluU9XpUxLRh4,959
+execution_timer/_timer.py,sha256=oLbiDVmmojeijwPMy99wVFwCLTGQ8ND2Gck3wh_SVRs,22043
+execution_timer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+executiontimer-1.1.0.dist-info/METADATA,sha256=YAEpYJjuaKvtbdKyyhje1lLgqyKlkYKYb-7hYoDt7q0,4966
+executiontimer-1.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+executiontimer-1.1.0.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
+executiontimer-1.1.0.dist-info/RECORD,,

executiontimer-1.0.2.dist-info/METADATA

@@ -1,333 +0,0 @@
-Metadata-Version: 2.5
-Name: executiontimer
-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
-Project-URL: Repository, https://github.com/seba2390/ExecutionTimer
-Project-URL: Issues, https://github.com/seba2390/ExecutionTimer/issues
-Project-URL: Changelog, https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md
-Author: Sebastian Yde Madsen
-License-Expression: MIT
-License-File: LICENSE
-Keywords: benchmark,context-manager,decorator,execution-time,instrumentation,performance,profiling,timing
-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.11
-Description-Content-Type: text/markdown
-
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-light.svg">
-    <img src="https://raw.githubusercontent.com/seba2390/ExecutionTimer/main/assets/logo-light.svg" alt="executiontimer" width="520">
-  </picture>
-</p>
-
-<p align="center">
-  <a href="https://pypi.org/project/executiontimer/"><img src="https://img.shields.io/pypi/v/executiontimer?color=blue" alt="PyPI version"></a>
-  <a href="https://pypi.org/project/executiontimer/"><img src="https://img.shields.io/pypi/pyversions/executiontimer" alt="Python versions"></a>
-  <a href="https://github.com/seba2390/ExecutionTimer/actions/workflows/ci.yml"><img src="https://github.com/seba2390/ExecutionTimer/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
-  <img src="https://img.shields.io/badge/types-py.typed-blue" alt="Typed">
-</p>
-
-Time named sections of your code with a `with` block or a decorator. Nested sections
-automatically form a hierarchy, so you get a breakdown of where time actually went — not
-just a single number.
-
-Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
-
-## Features
-
-- ⏱️ **One primitive** — `TimerContext` is both a context manager and a decorator
-- 🌳 **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,
-  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
-- 📦 **Zero dependencies**
-
-## Installation
-
-```bash
-pip install executiontimer
-```
-
-```bash
-uv add executiontimer
-```
-
-Requires Python 3.11+.
-
-> **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
->
-> ```python
-> from execution_timer import TimerContext
-> ```
-
-## Quick start
-
-```python
-import time
-
-from execution_timer import TimerContext, get_execution_times_report
-
-with TimerContext("load_data"):
-    time.sleep(0.12)
-
-with TimerContext("solve"):
-    for i in range(3):
-        with TimerContext("step", category="gpu", counter=i):
-            time.sleep(0.05)
-    with TimerContext("postprocess", category="cpu"):
-        time.sleep(0.03)
-
-print(get_execution_times_report())
-```
-
-```text
-Total time: 0.3156 s.
-
-load_data: 0.1219 s (38.62%)
-solve: 0.1937 s (61.38%)
-..  step: 0.1585 s (50.24%)
-..  postprocess: 0.0350 s (11.10%)
-```
-
-Indentation reflects nesting. Percentages are relative to the total of all top-level
-sections, so nested entries show their share of the whole run.
-
-## Usage
-
-### As a decorator
-
-```python
-from execution_timer import TimerContext
-
-
-@TimerContext("preprocess")
-def preprocess(rows: list[str]) -> list[str]:
-    return [row.strip() for row in rows]
-```
-
-Coroutine functions are supported natively — the timing spans the entire `await`:
-
-```python
-@TimerContext("fetch", category="io")
-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.
-
-### Counters
-
-Pass `counter=i` to time loop iterations separately. The report merges them by default
-(`flatten=True`) and keeps them apart when you ask for it:
-
-```python
-for i in range(3):
-    with TimerContext("step", counter=i):
-        ...
-
-get_execution_timings(flatten=True)  # {("step",): {"time": 0.158, ...}}
-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. 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
-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:
-
-```python
-from execution_timer import get_total_category_time
-
-with TimerContext("matmul", category="gpu"):
-    ...
-
-get_total_category_time("gpu")
-```
-
-`get_total_category_time` counts only the *top-most* section of a category, so a `gpu`
-section nested inside another `gpu` section is not double-counted.
-
-Repeated calls to the same path accumulate time. If its category changes, the latest
-category applies to that path's entire accumulated time. Use consistent categories per
-path when you need separate category totals.
-
-You can also forbid a category from appearing inside another, which raises a `ValueError`
-as soon as the invalid nesting happens:
-
-```python
-from execution_timer import register_forbidden_nesting
-
-register_forbidden_nesting(outer="gpu", inner="cpu")
-
-with TimerContext("kernel", category="gpu"):
-    with TimerContext("reduce", category="cpu"):  # ValueError
-        ...
-```
-
-### JSON export
-
-`get_execution_times_json` and `save_execution_timings_json` emit a structured snapshot —
-convenient for dashboards, CI artifacts, or handing to a language model:
-
-```python
-from execution_timer import save_execution_timings_json
-
-save_execution_timings_json("timings.json")
-```
-
-```json
-{
-  "total_time": 0.31556,
-  "total_category_time": { "cpu": 0.035024, "default": 0.31556, "gpu": 0.158528 },
-  "sections": [
-    { "name": "load_data", "path": ["load_data"], "time": 0.121869, "category": "default" },
-    { "name": "solve", "path": ["solve"], "time": 0.193691, "category": "default" },
-    { "name": "step", "path": ["solve", "step"], "time": 0.158528, "category": "gpu" },
-    { "name": "postprocess", "path": ["solve", "postprocess"], "time": 0.035024, "category": "cpu" }
-  ]
-}
-```
-
-Sections and totals come from one snapshot. Category totals use the original paths,
-even when flattening merges sections with different categories.
-
-### Concurrency
-
-The recorded timings live in one process-wide registry guarded by a lock. The *active
-context stack* is stored in a `ContextVar`, so it is isolated per thread and per asyncio
-task: concurrently recorded sections nest independently and merge into a single report.
-
-```python
-async def worker(n: int) -> None:
-    with TimerContext(f"task{n}"):
-        await fetch(...)  # recorded as ("task{n}", "fetch")
-
-
-await asyncio.gather(worker(0), worker(1))
-```
-
-Overlapping calls to the same section path are supported: each call keeps its own start
-time, and their durations are added together. These totals measure accumulated elapsed
-time and can exceed wall-clock duration. Use distinct names (or `counter=`) to report
-concurrent calls separately.
-
-New asyncio tasks inherit the timing context in which they are created. Their sections
-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. 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.
-For a tight loop, reuse a context to avoid constructing one on every iteration:
-
-```python
-step_timer = TimerContext("step")
-for item in items:
-    with step_timer:
-        process(item)
-```
-
-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; 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](https://github.com/seba2390/ExecutionTimer/blob/main/benchmarks/README.md).
-
-## API
-
-| 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 (`""` if none). |
-| `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`. |
-| `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`. |
-| `clear_forbidden_nesting()` | Remove all nesting rules. |
-
-`flatten=True` merges `counter` variants of a section back together; `flatten=False`
-keeps each `name[i]` separate.
-
-Exported types: `TimingReport`, `SectionRecord`, `TimingsPayload`, and `DEFAULT_CATEGORY`.
-The package ships a `py.typed` marker, so type checkers use the inline annotations.
-
-## Development
-
-Requires [uv](https://docs.astral.sh/uv/).
-
-```bash
-uv sync
-uv run pytest --cov
-uv run ruff check --fix && uv run ruff format
-uv run basedpyright
-```
-
-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](https://github.com/seba2390/ExecutionTimer/blob/main/LICENSE).

executiontimer-1.0.2.dist-info/RECORD

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