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

execution_timer/__init__.py

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

execution_timer/_timer.py

@@ -247,8 +247,16 @@ 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.
+        creation of the coroutine object. 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 = (
+                f"Cannot decorate generator function {func.__qualname__!r}: only creating the generator "
+                "would be timed. Time the loop that consumes it, or its body between yields, with a "
+                "'with TimerContext(...)' block instead."
+            )
+            raise TypeError(msg)
         if inspect.iscoroutinefunction(func):
             # ``iscoroutinefunction`` narrows nothing useful for the type checker, so bridge
             # through an explicitly typed helper instead of leaking ``Any`` into the signature.
@@ -299,7 +307,10 @@ def log_execution_times(*, flatten: bool = True, logger: logging.Logger | None =
     """Log the execution-times report at INFO level; flatten counters if requested."""
     target = logger if logger is not None else _LOGGER
     if target.isEnabledFor(logging.INFO):
-        target.info(get_execution_times_report(flatten=flatten))
+        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)
 
 
 def get_execution_timings(*, flatten: bool = True) -> dict[tuple[str, ...], TimingReport]:
@@ -345,7 +356,11 @@ def save_execution_timings_json(path: str | Path, *, flatten: bool = True, inden
 
 
 def get_total_time(*, flatten: bool = True) -> float:
-    """Get total elapsed seconds across all top-level sections."""
+    """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)
 
 

{executiontimer-0.1.1.dist-info → executiontimer-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 0.1.1
+Version: 0.2.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
@@ -16,15 +16,17 @@ 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.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -55,7 +57,8 @@ Zero dependencies. Fully type annotated. Works with threads and `asyncio`.
 - 🌳 **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
+- 🧵 **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
@@ -71,7 +74,7 @@ pip install executiontimer
 uv add executiontimer
 ```
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 > **Note** — the install name is `executiontimer`, the import name is `execution_timer`:
 >
@@ -131,6 +134,10 @@ Coroutine functions are supported natively — the timing spans the entire `awai
 async def fetch(url: str) -> bytes: ...
 ```
 
+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
@@ -233,6 +240,18 @@ New asyncio tasks inherit the timing context in which they are created. Their se
 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.
+
 ### Reusing contexts and clearing timings
 
 A `TimerContext` can be reused, nested within itself, or shared by concurrent calls.
@@ -267,7 +286,7 @@ results using the same interpreter and machine; see [benchmarks/README.md](bench
 | `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. |
+| `get_total_time(*, flatten=True)` | Total seconds across all top-level sections (`flatten` has no effect on the sum). |
 | `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`. |

executiontimer-0.2.0.dist-info/RECORD

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

{executiontimer-0.1.1.dist-info → executiontimer-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.3
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

executiontimer-0.1.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-execution_timer/__init__.py,sha256=WC6Cn6-mGTEHh1386OJ--hrAFaa9Z6eSBFze21brEfw,959
-execution_timer/_timer.py,sha256=RbLD7HshcDBlcz0II7JiLZduuNr6Dao0D_d0gs9cuww,14526
-execution_timer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-executiontimer-0.1.1.dist-info/METADATA,sha256=sAJT1E9gFJHlfd2oVwAwcrWYebEhq3xhgmjMIvv3NS4,11374
-executiontimer-0.1.1.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
-executiontimer-0.1.1.dist-info/licenses/LICENSE,sha256=rkJbDOYRrUX8k3S55pPiEquJXZGh07KvD01F1sBBppw,1077
-executiontimer-0.1.1.dist-info/RECORD,,