executiontimer 1.0.3__tar.gz → 1.1.1__tar.gz

{executiontimer-1.0.3 → executiontimer-1.1.1}/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-10-01
+
+### Documentation
+
+- The threads section of the concurrency guide was wrong for free-threaded Python 3.14.
+  There, a new thread starts in a copy of the context that started it, so its sections
+  nest under the section that was open at that moment. A thread pool reuses its workers,
+  so each worker keeps the section it started under: work submitted later from another
+  section was reported under the first one. The guide said pool work is always reported at
+  the top level, and that free-threaded builds nest thread work correctly with no extra
+  work. Neither was true on every build. The guide now explains the difference and shows
+  how to get the same report on every build: run each call in
+  `contextvars.copy_context().run` to nest it under the current section, or in
+  `contextvars.Context().run` to keep it at the top level. Behaviour is unchanged.
+- Tests cover how threads and reused pool workers nest on each kind of build, and both
+  recipes. The guide's examples assert their results on every build.
+
+## [1.1.0] - 2026-09-30
+
+### Changed
+
+- The text report, from `get_execution_times_report()` and `log_execution_times()`, shows
+  each time with three decimals in `µs`, `ms` or `s`, whichever keeps the number below
+  1000: `48.213 µs`, `315.612 ms`, `2.500 s`. It used to show seconds with four
+  decimals, so any section under 50 µs read `0.0000 s`, and fast sections, including a
+  whole recursive call tree, looked like zeros. Code that parses the report text needs
+  updating. `get_execution_timings()` and the JSON export are unchanged and still return
+  seconds.
+
 ## [1.0.3] - 2026-09-30
 
 ### Changed
@@ -194,7 +223,9 @@ 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/v1.0.3...HEAD
+[Unreleased]: https://github.com/seba2390/ExecutionTimer/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/seba2390/ExecutionTimer/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.3...v1.1.0
 [1.0.3]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/seba2390/ExecutionTimer/compare/v1.0.0...v1.0.1

{executiontimer-1.0.3 → executiontimer-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: executiontimer
-Version: 1.0.3
+Version: 1.1.1
 Summary: Hierarchical execution timing with user-defined categories.
 Project-URL: Homepage, https://github.com/seba2390/ExecutionTimer
 Project-URL: Documentation, https://seba2390.github.io/ExecutionTimer/
@@ -84,12 +84,12 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.3156 s.
+Total time: 312.838 ms.
 
-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%)
+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:

{executiontimer-1.0.3 → executiontimer-1.1.1}/README.md

@@ -53,12 +53,12 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.3156 s.
+Total time: 312.838 ms.
 
-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%)
+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:

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/getting-started.md

@@ -42,9 +42,9 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.1035 s.
+Total time: 104.727 ms.
 
-load_data: 0.1035 s (100.00%)
+load_data: 104.727 ms (100.00%)
 ```
 
 Timings are recorded in one registry for the whole process. Every section you time, in any
@@ -72,12 +72,12 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.0905 s.
+Total time: 89.826 ms.
 
-pipeline: 0.0905 s (100.00%)
-..  load: 0.0232 s (25.60%)
-..  transform: 0.0673 s (74.32%)
-..  ..  validate: 0.0126 s (13.88%)
+pipeline: 89.826 ms (100.00%)
+..  load: 22.073 ms (24.57%)
+..  transform: 67.726 ms (75.40%)
+..  ..  validate: 12.549 ms (13.97%)
 ```
 
 How to read the report:
@@ -86,8 +86,10 @@ How to read the report:
   `pipeline`.
 - **Total time** is the sum of the top-level sections. Nested sections are part of their
   parent's time, so they aren't added again.
-- **Percentages** are shares of the total, at every level. `validate` took 13.88% of the
-  whole run, not 13.88% of `transform`.
+- **Percentages** are shares of the total, at every level. `validate` took 13.97% of the
+  whole run, not 13.97% of `transform`.
+- **Times** have three decimals, in `µs`, `ms` or `s`, whichever keeps the number below
+  1000, so even very fast sections show a real value.
 
 Calling {func}`~execution_timer.clear_execution_timings` starts over with an empty
 registry.

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/guide/concurrency.md

@@ -57,11 +57,33 @@ the same.
 
 ## Threads
 
-New threads do **not** inherit the active stack. 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:
+Whether a new thread starts inside the section that started it depends on the Python build:
+
+- **Regular builds**, including Python 3.14, start each new thread with an empty stack.
+  Sections recorded in the thread appear at the top level of the report, and their time
+  is added to the total alongside the section that started the thread.
+- **Free-threaded builds of Python 3.14** start each new thread with a copy of the context
+  of the code that called {meth}`~threading.Thread.start`. Sections recorded in the thread
+  nest under the section that was open at that moment.
+
+Python's `-X thread_inherit_context` option switches between the two on any 3.14 build,
+and `sys.flags.thread_inherit_context` reports which one is in effect.
+
+### Thread pools
+
+The difference matters most for thread pools, because a pool reuses its threads.
+{class}`~concurrent.futures.ThreadPoolExecutor` starts a worker thread when work is
+submitted and keeps it for later work. On a free-threaded build, the worker keeps the
+stack it started with for as long as it lives, so work submitted later, from a different
+section or from none, still nests under the section that was open when the worker started.
+On a regular build, the same work is recorded at the top level.
+
+To get the same report on every build, pick the context for each call yourself. To nest
+thread work under the current section, run each call in a fresh copy of the current
+context from {func}`contextvars.copy_context`:
 
 ```python
+import contextvars
 from concurrent.futures import ThreadPoolExecutor
 
 from execution_timer import clear_execution_timings
@@ -74,28 +96,38 @@ def download(n: int) -> int:
     return n
 
 
-with TimerContext("batch"), ThreadPoolExecutor() as pool:
-    list(pool.map(download, range(4)))  # recorded as ("download",), not ("batch", "download")
+with ThreadPoolExecutor(max_workers=2) as pool:
+    with TimerContext("batch"):
+        futures = [pool.submit(contextvars.copy_context().run, download, n) for n in range(4)]
+        results = [future.result() for future in futures]
+    with TimerContext("retry"):
+        pool.submit(contextvars.copy_context().run, download, 0).result()
+
+timings = get_execution_timings()
+assert ("batch", "download") in timings
+assert ("retry", "download") in timings
+assert ("download",) not in timings
 ```
 
-To nest thread work under the current section, run it in a copy of the current context
-with {func}`contextvars.copy_context`, or use {func}`asyncio.to_thread`, which does that for
-you:
+Copy the context for every call rather than once per section: a context can't be entered
+by two threads at the same time. {func}`asyncio.to_thread` copies the context for you.
 
-```python
-import contextvars
+To keep thread work at the top level on every build, run each call in a new, empty
+{class}`~contextvars.Context` instead:
 
+```python
 clear_execution_timings()
 
-with TimerContext("batch"), ThreadPoolExecutor() as pool:
-    context = contextvars.copy_context()
-    pool.submit(context.run, download, 1).result()
+with ThreadPoolExecutor(max_workers=2) as pool, TimerContext("batch"):
+    pool.submit(contextvars.Context().run, download, 1).result()
 
-assert ("batch", "download") in get_execution_timings()
+timings = get_execution_timings()
+assert ("download",) in timings
+assert ("batch", "download") not in timings
 ```
 
-On free-threaded builds of Python 3.14, new threads inherit the context by default, so
-thread sections nest without extra work.
+The same works for a plain thread: pass `target=contextvars.copy_context().run` or
+`target=contextvars.Context().run`, followed by the function and its arguments in `args`.
 
 ## Overlapping calls add up
 

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/guide/counters.md

@@ -37,12 +37,12 @@ print(get_execution_times_report(flatten=False))
 ```
 
 ```text
-Total time: 0.0724 s.
+Total time: 67.003 ms.
 
-solve: 0.0724 s (100.00%)
-..  step[0]: 0.0125 s (17.31%)
-..  step[1]: 0.0250 s (34.60%)
-..  step[2]: 0.0347 s (47.97%)
+solve: 67.003 ms (100.00%)
+..  step[0]: 12.542 ms (18.72%)
+..  step[1]: 23.851 ms (35.60%)
+..  step[2]: 30.498 ms (45.52%)
 ```
 
 Use the separate view to find a slow iteration, and the merged view to see the loop's

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/guide/reports.md

@@ -32,16 +32,20 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.0499 s.
+Total time: 48.159 ms.
 
-load_data: 0.0249 s (49.92%)
-solve: 0.0250 s (50.08%)
-..  step: 0.0249 s (49.97%)
+load_data: 24.199 ms (50.25%)
+solve: 23.960 ms (49.75%)
+..  step: 23.904 ms (49.64%)
 ```
 
 Sections appear depth-first, each followed by its children, in the order they were first
 entered. Percentages are shares of the total time at every level.
 
+Times have three decimals, in `µs`, `ms` or `s`, whichever keeps the number below 1000.
+A 48 µs section reads `48.213 µs` rather than rounding to zero. The dictionary and JSON
+readers below return plain seconds.
+
 ## Logging
 
 {func}`~execution_timer.log_execution_times` logs the same report at `INFO` level, starting
@@ -58,11 +62,11 @@ log_execution_times()
 
 ```text
 INFO:execution_timer._timer:
-Total time: 0.0499 s.
+Total time: 48.159 ms.
 
-load_data: 0.0249 s (49.92%)
-solve: 0.0250 s (50.08%)
-..  step: 0.0249 s (49.97%)
+load_data: 24.199 ms (50.25%)
+solve: 23.960 ms (49.75%)
+..  step: 23.904 ms (49.64%)
 ```
 
 It logs to the `execution_timer._timer` logger unless you pass your own with

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/guide/timing-code.md

@@ -152,11 +152,11 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.0354 s.
+Total time: 34.704 ms.
 
-walk: 0.0354 s (100.00%)
-..  walk: 0.0247 s (69.77%)
-..  ..  walk: 0.0125 s (35.38%)
+walk: 34.704 ms (100.00%)
+..  walk: 24.161 ms (69.62%)
+..  ..  walk: 11.603 ms (33.44%)
 ```
 
 For deep recursion, time the top-level call only, for example with a `with` block around

{executiontimer-1.0.3 → executiontimer-1.1.1}/docs/index.md

@@ -23,12 +23,12 @@ print(get_execution_times_report())
 ```
 
 ```text
-Total time: 0.3156 s.
+Total time: 312.838 ms.
 
-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%)
+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%)
 ```
 
 ## Why executiontimer

{executiontimer-1.0.3 → executiontimer-1.1.1}/src/execution_timer/__init__.py

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

{executiontimer-1.0.3 → executiontimer-1.1.1}/src/execution_timer/_timer.py

@@ -198,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:
@@ -243,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():
@@ -378,8 +392,9 @@ def _basic_name_without_counter(name: str) -> str:
 def get_execution_times_report(*, flatten: bool = True) -> str:
     """Get a formatted, indented report of all recorded sections.
 
-    Each line shows a section's accumulated seconds and its share of the total time.
-    Indentation reflects nesting.
+    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``.

{executiontimer-1.0.3 → executiontimer-1.1.1}/tests/execution_timer_test.py

@@ -2,10 +2,12 @@
 
 import asyncio
 import builtins
+import contextvars
 import functools
 import inspect
 import json
 import logging
+import sys
 import threading
 import time
 import warnings
@@ -38,6 +40,10 @@ from execution_timer import (
 P = ParamSpec("P")
 R = TypeVar("R")
 
+# New threads start in a copy of the starting thread's context. The default on free-threaded
+# Python 3.14; the flag does not exist before 3.14.
+THREADS_INHERIT_CONTEXT = bool(getattr(sys.flags, "thread_inherit_context", False))
+
 
 @pytest.fixture(autouse=True)
 def reset_timer() -> Iterator[None]:
@@ -208,6 +214,25 @@ class TestReporting:
             assert get_execution_times_report() == ""
         assert caplog.records == []
 
+    @pytest.mark.parametrize(
+        ("seconds", "expected"),
+        [
+            (0.0000004, "0.400 µs"),
+            (0.0000482134, "48.213 µs"),
+            (0.0009999994, "999.999 µs"),
+            (0.0009999996, "1.000 ms"),
+            (0.3156, "315.600 ms"),
+            (0.9999996, "1.000 s"),
+            (2.5, "2.500 s"),
+            (3725.0, "3725.000 s"),
+        ],
+    )
+    def test_report_picks_a_unit_that_keeps_short_sections_visible(self, seconds: float, expected: str) -> None:
+        with patch.object(time, "perf_counter", side_effect=[0.0, seconds]), TimerContext("section"):
+            pass
+
+        assert get_execution_times_report() == f"Total time: {expected}.\n\nsection: {expected} (100.00%)"
+
     def test_report_flatten_flag(self) -> None:
         with patch.object(time, "perf_counter", side_effect=[0, 1, 1, 2]):
             for i in range(2):
@@ -571,6 +596,47 @@ class TestThreading:
         assert ("t0", "c1") not in timings
         assert ("t1", "c0") not in timings
 
+    def test_new_thread_nests_under_the_starting_section_only_where_threads_inherit_context(self) -> None:
+        thread = threading.Thread(target=TimerContext("work")(lambda: None))
+        with TimerContext("outer"):
+            thread.start()
+            thread.join()
+
+        expected = ("outer", "work") if THREADS_INHERIT_CONTEXT else ("work",)
+        assert set(raw_timings()) == {("outer",), expected}
+
+    def test_reused_pool_worker_keeps_the_section_it_started_in_where_threads_inherit_context(self) -> None:
+        """A pool worker inherits the context once, when it starts, and keeps it for later work."""
+        work = TimerContext("work")(lambda: None)
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            with TimerContext("phase_a"):
+                pool.submit(work).result()
+            with TimerContext("phase_b"):
+                pool.submit(work).result()
+
+        # Where threads inherit context, phase_b's call is misfiled under phase_a.
+        expected = {("phase_a", "work")} if THREADS_INHERIT_CONTEXT else {("work",)}
+        assert set(raw_timings()) == {("phase_a",), ("phase_b",), *expected}
+
+    def test_copying_the_context_per_call_nests_pool_work_on_every_build(self) -> None:
+        work = TimerContext("work")(lambda: None)
+        with ThreadPoolExecutor(max_workers=2) as pool:
+            with TimerContext("phase_a"):
+                futures = [pool.submit(contextvars.copy_context().run, work) for _ in range(4)]
+                _ = [future.result() for future in futures]
+            with TimerContext("phase_b"):
+                pool.submit(contextvars.copy_context().run, work).result()
+            pool.submit(contextvars.copy_context().run, work).result()
+
+        assert set(raw_timings()) == {("phase_a",), ("phase_a", "work"), ("phase_b",), ("phase_b", "work"), ("work",)}
+
+    def test_an_empty_context_per_call_keeps_pool_work_top_level_on_every_build(self) -> None:
+        work = TimerContext("work")(lambda: None)
+        with ThreadPoolExecutor(max_workers=1) as pool, TimerContext("outer"):
+            pool.submit(contextvars.Context().run, work).result()
+
+        assert set(raw_timings()) == {("outer",), ("work",)}
+
 
 class TestAsyncDecorator:
     def test_async_decorator_times_the_await_not_coroutine_creation(self) -> None:
@@ -757,7 +823,7 @@ class TestReportOrdering:
             pass
 
         report = get_execution_times_report()
-        assert "instant: 0.0000 s (0.00%)" in report
+        assert "instant: 0.000 µs (0.00%)" in report
 
 
 class TestRobustness:
@@ -1059,7 +1125,7 @@ class TestLifecycle:
         assert list(raw_timings()) == [("parent", "child")]
         # The cleared parent is gone, so its child is top-level: it counts toward the total
         # and is not indented beneath an unrelated section.
-        assert get_execution_times_report() == "Total time: 2.0000 s.\n\nchild: 2.0000 s (100.00%)"
+        assert get_execution_times_report() == "Total time: 2.000 s.\n\nchild: 2.000 s (100.00%)"
         assert get_total_time() == 2.0
         payload = cast(TimingsPayload, json.loads(get_execution_times_json()))
         assert payload["total_time"] == 2.0
@@ -1078,7 +1144,7 @@ class TestLifecycle:
             with TimerContext("after"):
                 pass
         assert get_execution_times_report() == (
-            "Total time: 5.0000 s.\n\nload: 4.0000 s (80.00%)\n..  parse: 1.0000 s (20.00%)\nafter: 1.0000 s (20.00%)"
+            "Total time: 5.000 s.\n\nload: 4.000 s (80.00%)\n..  parse: 1.000 s (20.00%)\nafter: 1.000 s (20.00%)"
         )
         assert get_total_time() == 5.0