executiontimer 0.1.1__tar.gz → 0.2.0__tar.gz

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

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-30
+
+### Changed
+
+- Decorating a generator function or an async generator function now raises `TypeError`.
+  Previously it silently timed only the creation of the generator object, which recorded
+  microseconds regardless of how long iteration took.
+- Python 3.11 is now supported; the minimum was 3.12 although nothing required it.
+
+### Fixed
+
+- `log_execution_times()` no longer logs an empty `INFO` record, after its warning, when
+  there are no timings.
+
+### Documentation
+
+- Explain that threads do not inherit the timing context, and how to nest thread work under
+  a section.
+- Explain how a section held open across a generator's `yield` absorbs the caller's sections.
+- Note that `flatten` has no effect on `get_total_time`.
+
+### Added
+
+- CI tests Python 3.11 and free-threaded Python 3.14t, and the package declares
+  free-threading support.
+- Workflows run with a read-only token by default and do not persist checkout credentials.
+
 ## [0.1.1] - 2026-09-20
 
 ### Fixed
@@ -58,6 +85,7 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v0.2.0...HEAD
+[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.1.1 → executiontimer-0.2.0}/CONTRIBUTING.md

@@ -26,11 +26,12 @@ uv run basedpyright
 All four must pass. Coverage is enforced at 95%; the current suite has 100% statement
 and branch coverage. Preserve coverage when adding or changing behavior.
 
-The test suite is also run against Python 3.12, 3.13 and 3.14 on Linux, macOS and Windows.
+The test suite is also run against Python 3.11, 3.12, 3.13, 3.14 and free-threaded 3.14t
+on Linux, macOS and Windows.
 To check another interpreter locally:
 
 ```bash
-uv run --python 3.12 pytest
+uv run --python 3.11 pytest
 ```
 
 For changes to recording or reporting performance, compare the benchmark on the same

{executiontimer-0.1.1 → executiontimer-0.2.0}/PKG-INFO

@@ -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.1.1 → executiontimer-0.2.0}/README.md

@@ -26,7 +26,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
@@ -42,7 +43,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`:
 >
@@ -102,6 +103,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
@@ -204,6 +209,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.
@@ -238,7 +255,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.1.1 → executiontimer-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ description = "Hierarchical execution timing with user-defined categories."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 authors = [{ name = "Sebastian Yde Madsen" }]
 keywords = [
     "timing",
@@ -23,9 +23,11 @@ classifiers = [
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Free Threading :: 3 - Stable",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Software Development",
     "Topic :: Software Development :: Testing",
@@ -85,7 +87,7 @@ fail_under = 95
 exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
 
 [tool.ruff]
-target-version = "py312"
+target-version = "py311"
 line-length = 120
 src = ["src", "tests"]
 
@@ -103,5 +105,5 @@ select = [
 
 [tool.basedpyright]
 typeCheckingMode = "recommended"
-pythonVersion = "3.12"
+pythonVersion = "3.11"
 include = ["src", "tests"]

{executiontimer-0.1.1 → executiontimer-0.2.0}/src/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",

{executiontimer-0.1.1 → executiontimer-0.2.0}/src/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 → executiontimer-0.2.0}/tests/execution_timer_test.py

@@ -7,7 +7,7 @@ import json
 import logging
 import threading
 import time
-from collections.abc import Iterator
+from collections.abc import AsyncIterator, Iterator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import ExitStack
 from pathlib import Path
@@ -380,6 +380,32 @@ class TestTimerContextDecorator:
         assert ("outer",) in timings
         assert ("outer", "inner") in timings
 
+    def test_decorating_a_generator_function_raises(self) -> None:
+        def numbers() -> Iterator[int]:
+            yield 1
+
+        with pytest.raises(TypeError, match=r"Cannot decorate generator function '.*numbers'"):
+            _ = TimerContext("gen")(numbers)
+        assert raw_timings() == {}
+
+    def test_decorating_an_async_generator_function_raises(self) -> None:
+        async def numbers() -> AsyncIterator[int]:
+            yield 1
+
+        with pytest.raises(TypeError, match=r"Cannot decorate generator function '.*numbers'"):
+            _ = TimerContext("agen")(numbers)
+        assert raw_timings() == {}
+
+    def test_decorator_accepts_a_function_returning_a_generator(self) -> None:
+        """Only generator *functions* are rejected; a plain function may return an iterator."""
+
+        @TimerContext("factory")
+        def factory() -> Iterator[int]:
+            return iter([1, 2])
+
+        assert list(factory()) == [1, 2]
+        assert ("factory",) in raw_timings()
+
 
 class TestExceptions:
     def test_timing_recorded_when_body_raises(self) -> None:
@@ -695,6 +721,14 @@ class TestRobustness:
 
         assert [record.name for record in caplog.records] == ["execution_timer._timer"]
 
+    def test_logging_an_empty_registry_emits_only_the_warning(self, caplog: pytest.LogCaptureFixture) -> None:
+        with caplog.at_level(logging.INFO):
+            log_execution_times()
+
+        assert [(record.levelno, record.message) for record in caplog.records] == [
+            (logging.WARNING, "No timings to report.")
+        ]
+
 
 class TestRegressions:
     @pytest.mark.parametrize("clear_between_calls", [False, True])