nano-dev-utils 0.5.8__tar.gz → 1.0.0__tar.gz

{nano_dev_utils-0.5.8 → nano_dev_utils-1.0.0}/.idea/workspace.xml

@@ -4,12 +4,7 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="1859e23b-7665-4b92-98cc-65e07a208923" name="Changes" comment="corrected return types - complete">
-      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/pyproject.toml" beforeDir="false" afterPath="$PROJECT_DIR$/pyproject.toml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/nano_dev_utils/timers.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/nano_dev_utils/timers.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/tests/test_timer.py" beforeDir="false" afterPath="$PROJECT_DIR$/tests/test_timer.py" afterDir="false" />
-    </list>
+    <list default="true" id="1859e23b-7665-4b92-98cc-65e07a208923" name="Changes" comment="timers, test_timer - improved overall" />
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
     <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
@@ -41,12 +36,18 @@
     "RunOnceActivity.ShowReadmeOnStart": "true",
     "git-widget-placeholder": "master",
     "ignore.virus.scanning.warn.message": "true",
-    "last_opened_file_path": "C:/GitHubWS/nano_dev_utils",
+    "last_opened_file_path": "C:/GitHubWS/nano_dev_utils/tests",
     "settings.editor.selected.configurable": "com.jetbrains.python.configuration.PyActiveSdkModuleConfigurable"
   }
 }]]></component>
   <component name="RecentsManager">
     <key name="CopyFile.RECENT_KEYS">
+      <recent name="C:\GitHubWS\nano_dev_utils\tests" />
+      <recent name="C:\GitHubWS\nano_dev_utils" />
+    </key>
+    <key name="MoveFile.RECENT_KEYS">
+      <recent name="C:\GitHubWS\nano_dev_utils\tests" />
+      <recent name="C:\GitHubWS\nano_dev_utils\src\nano_dev_utils" />
       <recent name="C:\GitHubWS\nano_dev_utils" />
     </key>
   </component>
@@ -105,9 +106,9 @@
     </configuration>
     <recent_temporary>
       <list>
-        <item itemvalue="Python tests.Python tests in tests" />
         <item itemvalue="Python tests.Python tests in tests" />
         <item itemvalue="Python tests.Python tests in test_timer.py" />
+        <item itemvalue="Python tests.Python tests in tests" />
         <item itemvalue="Python.test_timer" />
       </list>
     </recent_temporary>
@@ -216,7 +217,71 @@
       <option name="project" value="LOCAL" />
       <updated>1747666293914</updated>
     </task>
-    <option name="localTasksCounter" value="12" />
+    <task id="LOCAL-00012" summary="+iterations&#10;+version update">
+      <option name="closed" value="true" />
+      <created>1747666696203</created>
+      <option name="number" value="00012" />
+      <option name="presentableId" value="LOCAL-00012" />
+      <option name="project" value="LOCAL" />
+      <updated>1747666696203</updated>
+    </task>
+    <task id="LOCAL-00013" summary="+pre-commit, ruff &#10;+type-hinting update for Timer">
+      <option name="closed" value="true" />
+      <created>1747819871928</created>
+      <option name="number" value="00013" />
+      <option name="presentableId" value="LOCAL-00013" />
+      <option name="project" value="LOCAL" />
+      <updated>1747819871928</updated>
+    </task>
+    <task id="LOCAL-00014" summary="+timeout support">
+      <option name="closed" value="true" />
+      <created>1748164800940</created>
+      <option name="number" value="00014" />
+      <option name="presentableId" value="LOCAL-00014" />
+      <option name="project" value="LOCAL" />
+      <updated>1748164800940</updated>
+    </task>
+    <task id="LOCAL-00015" summary="+updates related to timeout functionality - WIP">
+      <option name="closed" value="true" />
+      <created>1748164866417</created>
+      <option name="number" value="00015" />
+      <option name="presentableId" value="LOCAL-00015" />
+      <option name="project" value="LOCAL" />
+      <updated>1748164866417</updated>
+    </task>
+    <task id="LOCAL-00016" summary="using self.precision instead of hardcoded value&#10;ongoing unit tests update">
+      <option name="closed" value="true" />
+      <created>1748165510054</created>
+      <option name="number" value="00016" />
+      <option name="presentableId" value="LOCAL-00016" />
+      <option name="project" value="LOCAL" />
+      <updated>1748165510054</updated>
+    </task>
+    <task id="LOCAL-00017" summary="timer unittests complete">
+      <option name="closed" value="true" />
+      <created>1748186783462</created>
+      <option name="number" value="00017" />
+      <option name="presentableId" value="LOCAL-00017" />
+      <option name="project" value="LOCAL" />
+      <updated>1748186783462</updated>
+    </task>
+    <task id="LOCAL-00018" summary="timers - only work with perf_counter_ns&#10;test_timer - improved overall">
+      <option name="closed" value="true" />
+      <created>1748198255817</created>
+      <option name="number" value="00018" />
+      <option name="presentableId" value="LOCAL-00018" />
+      <option name="project" value="LOCAL" />
+      <updated>1748198255817</updated>
+    </task>
+    <task id="LOCAL-00019" summary="timers, test_timer - improved overall">
+      <option name="closed" value="true" />
+      <created>1748199166818</created>
+      <option name="number" value="00019" />
+      <option name="presentableId" value="LOCAL-00019" />
+      <option name="project" value="LOCAL" />
+      <updated>1748199166818</updated>
+    </task>
+    <option name="localTasksCounter" value="20" />
     <servers />
   </component>
   <component name="Vcs.Log.Tabs.Properties">
@@ -242,6 +307,14 @@
     <MESSAGE value="minor update" />
     <MESSAGE value="corrected return type" />
     <MESSAGE value="corrected return types - complete" />
-    <option name="LAST_COMMIT_MESSAGE" value="corrected return types - complete" />
+    <MESSAGE value="+iterations&#10;+version update" />
+    <MESSAGE value="+pre-commit, ruff &#10;+type-hinting update for Timer" />
+    <MESSAGE value="+timeout support" />
+    <MESSAGE value="+updates related to timeout functionality - WIP" />
+    <MESSAGE value="using self.precision instead of hardcoded value&#10;ongoing unit tests update" />
+    <MESSAGE value="timer unittests complete" />
+    <MESSAGE value="timers - only work with perf_counter_ns&#10;test_timer - improved overall" />
+    <MESSAGE value="timers, test_timer - improved overall" />
+    <option name="LAST_COMMIT_MESSAGE" value="timers, test_timer - improved overall" />
   </component>
 </project>

{nano_dev_utils-0.5.8 → nano_dev_utils-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nano_dev_utils
-Version: 0.5.8
+Version: 1.0.0
 Summary: A collection of small Python utilities for developers.
 Project-URL: Homepage, https://github.com/yaronday/nano_utils
 Project-URL: Issues, https://github.com/yaronday/nano_utils/issues
@@ -24,23 +24,33 @@ A collection of small Python utilities for developers.
 
 ### `timers.py`
 
-This module provides a `Timer` class for measuring the execution time of code blocks and functions.
+This module provides a `Timer` class for measuring the execution time of code blocks and functions with additional features like timeout control and multi-iteration averaging.
 
 #### `Timer` Class
 
 * **`__init__(self, precision: int = 4, verbose: bool = False)`**: Initializes a `Timer` instance.
-    * `precision`: The number of decimal places to record and    
-       display time durations. Defaults to 4.
-    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs).       
-       Defaults to `False`.
+    * `precision`: The number of decimal places to record and display time durations. Defaults to 4.
+    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs). Defaults to `False`.
 
 * **`timeit(
-        self, iterations: int = 1
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False
     ) -> Callable[[Callable[P, R]], Callable[P, R | None]]`**:   
-      Decorator that times function execution with automatic unit scaling.   
-    * When the decorated function is called, this decorator records the start and end times,   
-      calculates the average execution time, prints the function name and execution    
-      time (optionally including arguments), and returns the result of the original function.
+      Decorator that times function execution with advanced features:
+    * `iterations`: Number of times to run the function (for averaging). Defaults to 1.
+    * `timeout`: Maximum allowed execution time in seconds. When exceeded:
+        * Raises `TimeoutError` immediately
+        * **Warning:** The function execution will be aborted mid-operation
+        * No return value will be available if timeout occurs
+    * `per_iteration`: If True, applies timeout check to each iteration; otherwise checks total time across all iterations.
+    * Features:
+        * Records execution times
+        * Handles timeout conditions
+        * Calculates average execution time across iterations
+        * Prints the function name and execution time (with optional arguments)
+        * Returns the result of the original function (unless timeout occurs)
 
 #### Example Usage:
 
@@ -50,16 +60,22 @@ from nano_dev_utils.timers import Timer
 
 timer = Timer(precision=6, verbose=True)
 
-
+# Basic timing
 @timer.timeit()
 def my_function(a, b=10):
-  """A sample function."""
-  time.sleep(0.1)
-  return a + b
-
-
-result = my_function(5, b=20)
-print(f"Result: {result}")
+    """A sample function."""
+    time.sleep(0.1)
+    return a + b
+
+# Advanced usage with timeout and iterations
+@timer.timeit(iterations=5, timeout=0.5, per_iteration=True)
+def critical_function(x):
+    """Function with timeout check per iteration."""
+    time.sleep(0.08)
+    return x * 2
+
+result1 = my_function(5, b=20)  # Shows args/kwargs and timing
+result2 = critical_function(10)  # Runs 5 times with per-iteration timeout
 ```
 
 ### `dynamic_importer.py`

{nano_dev_utils-0.5.8 → nano_dev_utils-1.0.0}/README.md

@@ -6,23 +6,33 @@ A collection of small Python utilities for developers.
 
 ### `timers.py`
 
-This module provides a `Timer` class for measuring the execution time of code blocks and functions.
+This module provides a `Timer` class for measuring the execution time of code blocks and functions with additional features like timeout control and multi-iteration averaging.
 
 #### `Timer` Class
 
 * **`__init__(self, precision: int = 4, verbose: bool = False)`**: Initializes a `Timer` instance.
-    * `precision`: The number of decimal places to record and    
-       display time durations. Defaults to 4.
-    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs).       
-       Defaults to `False`.
+    * `precision`: The number of decimal places to record and display time durations. Defaults to 4.
+    * `verbose`: Optionally displays the function's positional arguments (args) and keyword arguments (kwargs). Defaults to `False`.
 
 * **`timeit(
-        self, iterations: int = 1
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False
     ) -> Callable[[Callable[P, R]], Callable[P, R | None]]`**:   
-      Decorator that times function execution with automatic unit scaling.   
-    * When the decorated function is called, this decorator records the start and end times,   
-      calculates the average execution time, prints the function name and execution    
-      time (optionally including arguments), and returns the result of the original function.
+      Decorator that times function execution with advanced features:
+    * `iterations`: Number of times to run the function (for averaging). Defaults to 1.
+    * `timeout`: Maximum allowed execution time in seconds. When exceeded:
+        * Raises `TimeoutError` immediately
+        * **Warning:** The function execution will be aborted mid-operation
+        * No return value will be available if timeout occurs
+    * `per_iteration`: If True, applies timeout check to each iteration; otherwise checks total time across all iterations.
+    * Features:
+        * Records execution times
+        * Handles timeout conditions
+        * Calculates average execution time across iterations
+        * Prints the function name and execution time (with optional arguments)
+        * Returns the result of the original function (unless timeout occurs)
 
 #### Example Usage:
 
@@ -32,16 +42,22 @@ from nano_dev_utils.timers import Timer
 
 timer = Timer(precision=6, verbose=True)
 
-
+# Basic timing
 @timer.timeit()
 def my_function(a, b=10):
-  """A sample function."""
-  time.sleep(0.1)
-  return a + b
-
-
-result = my_function(5, b=20)
-print(f"Result: {result}")
+    """A sample function."""
+    time.sleep(0.1)
+    return a + b
+
+# Advanced usage with timeout and iterations
+@timer.timeit(iterations=5, timeout=0.5, per_iteration=True)
+def critical_function(x):
+    """Function with timeout check per iteration."""
+    time.sleep(0.08)
+    return x * 2
+
+result1 = my_function(5, b=20)  # Shows args/kwargs and timing
+result2 = critical_function(10)  # Runs 5 times with per-iteration timeout
 ```
 
 ### `dynamic_importer.py`

{nano_dev_utils-0.5.8 → nano_dev_utils-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nano_dev_utils"
-version = "0.5.8"
+version = "1.0.0"
 
 authors = [
   { name="Yaron Dayan", email="yaronday77@gmail.com" },

nano_dev_utils-1.0.0/src/nano_dev_utils/timers.py

@@ -0,0 +1,68 @@
+from functools import wraps
+import time
+from typing import Callable, ParamSpec, TypeVar
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+class Timer:
+    def __init__(self, precision: int = 4, verbose: bool = False):
+        self.precision = precision
+        self.verbose = verbose
+        self.units = [(1e9, 's'), (1e6, 'ms'), (1e3, 'μs'), (1.0, 'ns')]
+
+    def timeit(
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
+    ) -> Callable[[Callable[P, R]], Callable[P, R | None]]:
+        """Decorator that times function execution with optional timeout support."""
+
+        def decorator(func: Callable[P, R]) -> Callable[P, R | None]:
+            @wraps(func)
+            def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | None:
+                total_elapsed_ns = 0
+                result: R | None = None
+
+                for i in range(1, iterations + 1):
+                    start_ns = time.perf_counter_ns()
+                    result = func(*args, **kwargs)
+                    duration_ns = time.perf_counter_ns() - start_ns
+                    total_elapsed_ns += duration_ns
+
+                    if timeout is not None:
+                        if per_iteration:
+                            duration_s = duration_ns / 1e9
+                            if duration_s > timeout:
+                                raise TimeoutError(
+                                    f'{func.__name__} exceeded '
+                                    f'{timeout:.{self.precision}f}s on '
+                                    f'iteration {i} (took '
+                                    f'{duration_s:.{self.precision}f}s)'
+                                )
+                        else:
+                            total_duration_s = total_elapsed_ns / 1e9
+                            if total_duration_s > timeout:
+                                raise TimeoutError(
+                                    f'{func.__name__} exceeded {timeout:.{self.precision}f}s '
+                                    f'after {i} iterations (took {total_duration_s:.{self.precision}f}s)'
+                                )
+
+                avg_elapsed_ns = total_elapsed_ns / iterations
+                value, unit = next(
+                    (avg_elapsed_ns / div, u)
+                    for div, u in self.units
+                    if avg_elapsed_ns >= div or u == 'ns'
+                )
+                extra_info = f'{args} {kwargs} ' if self.verbose else ''
+                iter_info = f' (avg. over {iterations} runs)' if iterations > 1 else ''
+                print(
+                    f'{func.__name__} {extra_info}took {value:.{self.precision}f} [{unit}]{iter_info}'
+                )
+                return result
+
+            return wrapper
+
+        return decorator

nano_dev_utils-1.0.0/tests/test_timer.py

@@ -0,0 +1,313 @@
+import threading
+import pytest
+from src.nano_dev_utils.timers import Timer
+
+
+def test_initialization():
+    timer = Timer()
+    assert timer.precision == 4
+    assert not timer.verbose
+
+    timer_custom = Timer(precision=6, verbose=True)
+    assert timer_custom.precision == 6
+    assert timer_custom.verbose
+
+
+def test_timeit_simple(mocker):
+    mock_print = mocker.patch('builtins.print')
+    mock_time = mocker.patch('time.perf_counter_ns', side_effect=[0, 9.23467e5])
+    timer = Timer(precision=2)
+
+    @timer.timeit()
+    def sample_function():
+        return 'result'
+
+    result = sample_function()
+    assert result == 'result'
+    mock_time.assert_any_call()
+    mock_print.assert_called_once_with('sample_function took 923.47 [μs]')
+
+
+def test_timeit_no_args_kwargs(mocker):
+    mock_print = mocker.patch('builtins.print')
+    mock_time = mocker.patch('time.perf_counter_ns', side_effect=[1.0, 1.5])
+    timer = Timer(precision=2, verbose=True)
+
+    @timer.timeit()
+    def yet_another_function():
+        return 'yet another result'
+
+    result = yet_another_function()
+    assert result == 'yet another result'
+    mock_time.assert_any_call()
+    mock_print.assert_called_once_with('yet_another_function () {} took 0.50 [ns]')
+
+
+def test_multithreaded_timing(mocker):
+    """Test timer works correctly across threads"""
+    mock_print = mocker.patch('builtins.print')
+    sim_time_us = 1  # μs
+    sim_time_ns = sim_time_us * 1e3
+    num_of_threads = 4
+    mocker.patch(
+        'time.perf_counter_ns',
+        side_effect=[0, sim_time_ns] * num_of_threads,
+        autospec=True,
+    )
+
+    timer = Timer()
+    results = []
+
+    @timer.timeit()
+    def threaded_operation():
+        return threading.get_ident()
+
+    def run_in_thread():
+        results.append(threaded_operation())
+
+    threads = [threading.Thread(target=run_in_thread) for _ in range(num_of_threads)]
+
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    assert mock_print.call_count == num_of_threads
+    assert len(set(results)) == num_of_threads
+
+    for call_args in mock_print.call_args_list:
+        assert f'took {sim_time_us:.{timer.precision}f} [μs]' in call_args[0][0]
+
+
+def test_verbose_mode(mocker):
+    """Test that verbose mode includes positional and
+    keyword arguments in output and preserves the wrapped func result"""
+    mock_print = mocker.patch('builtins.print')
+    mocker.patch('time.perf_counter_ns', side_effect=[1e4, 5.23456e4])
+    verbose_timer = Timer(verbose=True)
+
+    @verbose_timer.timeit()
+    def func_with_args(a, b, c=3):
+        return a + b + c
+
+    res = func_with_args(1, 2, c=4)
+    output = mock_print.call_args[0][0]
+    assert '(1, 2)' in output  # checking positional args
+    assert "'c': 4" in output  # checking kwargs
+    mock_print.assert_called_once_with(
+        "func_with_args (1, 2) {'c': 4} took 42.3456 [μs]"
+    )
+    assert res == 7  # checking returned value preservation
+
+
+def test_nested_timers(mocker):
+    """Test that nested timers work correctly"""
+    outer_start = 1000
+    inner_start = 1100
+    inner_end = 1200
+    outer_end = 1300
+    mocker.patch(
+        'time.perf_counter_ns',
+        side_effect=[
+            outer_start,
+            inner_start,
+            inner_end,
+            outer_end,
+        ],
+    )
+
+    mock_print = mocker.patch('builtins.print')
+    timer = Timer()
+
+    @timer.timeit()
+    def outer():
+        @timer.timeit()
+        def inner():
+            pass
+
+        return inner()
+
+    outer()
+
+    # Should have two print calls (inner and outer)
+    assert mock_print.call_count == 2
+    inner_output = mock_print.call_args_list[0][0][0]
+    outer_output = mock_print.call_args_list[1][0][0]
+
+    inner_duration = float(inner_output.split('took ')[1].split(' [')[0])
+    outer_duration = float(outer_output.split('took ')[1].split(' [')[0])
+
+    assert inner_duration == inner_end - inner_start
+    assert outer_duration == outer_end - outer_start
+    assert outer_duration > inner_duration
+
+
+def test_unit_scaling(mocker):
+    """Test the time unit selection logic directly"""
+    mock_print = mocker.patch('builtins.print')
+
+    boundary_cases = [
+        (1e3 - 1, 'ns'),
+        (1e3, 'μs'),
+        (1e6 - 1, 'μs'),
+        (1e6, 'ms'),
+        (1e9 - 1, 'ms'),
+        (1e9, 's'),
+    ]
+
+    for ns, expected_unit in boundary_cases:
+        mocker.patch('time.perf_counter_ns', side_effect=[0, ns])
+        timer = Timer(precision=2)
+
+        @timer.timeit()
+        def dummy():
+            pass
+
+        dummy()
+        printed_output = mock_print.call_args[0][0]
+        assert expected_unit in printed_output, (
+            f"Failed for {ns:,}ns → Expected '{expected_unit}' in output. "
+            f'Got: {printed_output}'
+        )
+
+
+def test_function_metadata_preserved():
+    """Test that function metadata (name, docstring) is preserved"""
+    timer = Timer(precision=3)
+
+    @timer.timeit()
+    def dummy_func():
+        """Test docstring"""
+        pass
+
+    assert dummy_func.__name__ == 'dummy_func'
+    assert dummy_func.__doc__ == 'Test docstring'
+
+
+def test_timeit_with_iterations(mocker):
+    mock_print = mocker.patch('builtins.print')
+
+    k = 3
+    sim_times_ns = [0, 1e3, 0, 2e3, 0, 3e3]
+    mock_time = mocker.patch(
+        'time.perf_counter_ns',
+        side_effect=sim_times_ns,
+        autospec=True,
+    )
+
+    timer = Timer(precision=2)
+
+    @timer.timeit(iterations=k)
+    def sample_function():
+        return 'done'
+
+    result = sample_function()
+
+    assert result == 'done'
+    mock_time.assert_any_call()
+
+    mock_print.assert_called_once_with(
+        f'sample_function took {sum(sim_times_ns) / 3e3:.{timer.precision}f} [μs] (avg. over {k} runs)'
+    )
+
+
+def test_timeout_single_iteration(mocker):
+    cfg_timeout_s = 0.1
+    duration_s = cfg_timeout_s + 0.1
+    current_time_ns = 0.0
+    duration_ns = duration_s * 1e9
+
+    mocker.patch(
+        'time.perf_counter_ns',
+        side_effect=[0.0, duration_ns],
+        autospec=True,
+    )
+    timer = Timer(precision=6, verbose=True)
+
+    @timer.timeit(timeout=cfg_timeout_s)
+    def timed_function():
+        nonlocal current_time_ns
+        current_time_ns += duration_ns
+
+    with pytest.raises(TimeoutError) as exc_info:
+        timed_function()
+
+    assert f'took {duration_s:.{timer.precision}f}s' in str(exc_info.value)
+
+
+def test_timeout_multiple_iterations(mocker):
+    sim_time_per_iter_s = 0.3
+    sim_time_per_iter_ns = sim_time_per_iter_s * 1e9
+
+    k = 5
+    timeout_threshold = (k - 1) * sim_time_per_iter_s - 0.1
+
+    mocker.patch(
+        'time.perf_counter_ns',
+        side_effect=[sim_time_per_iter_ns * count for count in range(2 * k - 1)],
+        autospec=True,
+    )
+
+    timer = Timer(precision=6, verbose=True)
+
+    @timer.timeit(iterations=k, timeout=timeout_threshold)
+    def func(duration: float) -> str:
+        return f'Function completed in simulated {duration}s'
+
+    with pytest.raises(TimeoutError) as exc_info:
+        func(sim_time_per_iter_s)
+
+    expected_timeout_val = f'{timeout_threshold:.{timer.precision}f}s'
+    expected_taken_val = f'{(sim_time_per_iter_s * (k - 1)):.{timer.precision}f}s'
+
+    expected_message_template = (
+        f'func exceeded {expected_timeout_val} after {k - 1} iterations '
+        f'(took {expected_taken_val})'
+    )
+
+    assert str(exc_info.value) == expected_message_template
+
+
+def test_timeout_per_iteration(mocker):
+    sim_time_s = 0.2
+    cfg_timeout = 0.1
+    mocker.patch(
+        'time.perf_counter_ns', side_effect=[0.0, sim_time_s * 1e9], autospec=True
+    )
+
+    timer = Timer(precision=6, verbose=True)
+
+    @timer.timeit(iterations=5, timeout=cfg_timeout, per_iteration=True)
+    def func(duration: float) -> str:
+        return f'Function completed in simulated {duration}s'
+
+    with pytest.raises(TimeoutError) as exc_info:
+        func(sim_time_s)
+
+    assert (
+        f'exceeded {cfg_timeout:.{timer.precision}f}s on iteration 1 '
+        f'(took {sim_time_s:.{timer.precision}f}s)'
+    ) in str(exc_info.value)
+
+
+def test_timeout_with_fast_function(mocker):
+    mock_print = mocker.patch('builtins.print')
+    sim_time_ms = 50.1
+    sim_time_s = sim_time_ms / 1e3
+
+    mocker.patch(
+        'time.perf_counter_ns', side_effect=[0, sim_time_ms * 1e6], autospec=True
+    )
+
+    timer = Timer(precision=4)
+
+    @timer.timeit(timeout=1.0)
+    def func(duration: float) -> str:
+        return f'Function completed in simulated {duration}s'
+
+    result = func(sim_time_s)
+
+    mock_print.assert_called_once_with(
+        f'func took {sim_time_ms:.{timer.precision}f} [ms]'
+    )
+    assert result == f'Function completed in simulated {sim_time_s}s'

{nano_dev_utils-0.5.8 → nano_dev_utils-1.0.0}/uv.lock

@@ -31,7 +31,7 @@ wheels = [
 
 [[package]]
 name = "nano-dev-utils"
-version = "0.5.7"
+version = "0.5.8"
 source = { editable = "." }
 
 [package.optional-dependencies]

nano_dev_utils-0.5.8/src/nano_dev_utils/timers.py

@@ -1,49 +0,0 @@
-from functools import wraps
-import time
-from typing import Callable, ParamSpec, TypeVar
-
-P = ParamSpec('P')
-R = TypeVar('R')
-
-
-class Timer:
-    def __init__(self, precision=4, verbose=False):
-        self.precision = precision
-        self.verbose = verbose
-        self.units = [(1e9, 's'), (1e6, 'ms'), (1e3, 'μs'), (1.0, 'ns')]
-
-    def timeit(
-        self, iterations: int = 1
-    ) -> Callable[[Callable[P, R]], Callable[P, R | None]]:
-        def decorator(func: Callable[P, R]) -> Callable[P, R | None]:
-            """Decorator that times function execution with automatic unit scaling and averaging."""
-
-            @wraps(func)
-            def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | None:
-                total_elapsed = 0
-                result = None
-
-                for _ in range(iterations):
-                    start = time.perf_counter_ns()
-                    result = func(*args, **kwargs)
-                    total_elapsed += time.perf_counter_ns() - start
-
-                avg_elapsed = total_elapsed / iterations
-                value = avg_elapsed
-                unit = 'ns'
-
-                for divisor, unit in self.units:
-                    if avg_elapsed >= divisor or unit == 'ns':
-                        value = avg_elapsed / divisor
-                        break
-
-                extra_info = f'{args} {kwargs} ' if self.verbose else ''
-                iter_info = f' (avg over {iterations} runs)' if iterations > 1 else ''
-                print(
-                    f'{func.__name__} {extra_info}took {value:.{self.precision}f} [{unit}]{iter_info}'
-                )
-                return result
-
-            return wrapper
-
-        return decorator

nano_dev_utils-0.5.8/tests/test_timer.py

@@ -1,181 +0,0 @@
-import threading
-import time
-from src.nano_dev_utils.timers import Timer
-
-
-def test_initialization():
-    timer = Timer()
-    assert timer.precision == 4
-    assert not timer.verbose
-
-    timer_custom = Timer(precision=6, verbose=True)
-    assert timer_custom.precision == 6
-    assert timer_custom.verbose
-
-
-def test_timeit_simple(mocker):
-    mock_print = mocker.patch('builtins.print')
-    mock_time = mocker.patch('time.perf_counter_ns', side_effect=[0, 9.23467e5])
-    timer = Timer(precision=2)
-
-    @timer.timeit()
-    def sample_function():
-        return 'result'
-
-    result = sample_function()
-    assert result == 'result'
-    mock_time.assert_any_call()
-    mock_print.assert_called_once_with('sample_function took 923.47 [μs]')
-
-
-def test_timeit_no_args_kwargs(mocker):
-    mock_print = mocker.patch('builtins.print')
-    mock_time = mocker.patch('time.perf_counter_ns', side_effect=[1.0, 1.5])
-    timer = Timer(precision=2, verbose=True)
-
-    @timer.timeit()
-    def yet_another_function():
-        return 'yet another result'
-
-    result = yet_another_function()
-    assert result == 'yet another result'
-    mock_time.assert_any_call()
-    mock_print.assert_called_once_with('yet_another_function () {} took 0.50 [ns]')
-
-
-def test_multithreaded_timing(mocker):
-    """Test timer works correctly across threads"""
-    mock_print = mocker.patch('builtins.print')
-    timer = Timer()
-    results = []
-
-    @timer.timeit()
-    def threaded_operation():
-        time.sleep(0.1)
-        return threading.get_ident()
-
-    def run_in_thread():
-        results.append(threaded_operation())
-
-    threads = [threading.Thread(target=run_in_thread) for _ in range(3)]
-
-    for t in threads:
-        t.start()
-    for t in threads:
-        t.join()
-
-    # Should have 3 print calls (one per thread)
-    assert mock_print.call_count == 3
-    # All thread IDs should be different
-    assert len(set(results)) == 3
-
-
-def test_verbose_mode(mocker):
-    """Test that verbose mode includes positional and
-    keyword arguments in output and preserves the wrapped func result"""
-    mock_print = mocker.patch('builtins.print')
-    mocker.patch('time.perf_counter_ns', side_effect=[1e4, 5.23456e4])
-    verbose_timer = Timer(verbose=True)
-
-    @verbose_timer.timeit()
-    def func_with_args(a, b, c=3):
-        return a + b + c
-
-    res = func_with_args(1, 2, c=4)
-    output = mock_print.call_args[0][0]
-    assert '(1, 2)' in output  # checking positional args
-    assert "'c': 4" in output  # checking kwargs
-    mock_print.assert_called_once_with(
-        "func_with_args (1, 2) {'c': 4} took 42.3456 [μs]"
-    )
-    assert res == 7  # checking returned value preservation
-
-
-def test_nested_timers(mocker):
-    """Test that nested timers work correctly"""
-    mock_print = mocker.patch('builtins.print')
-    timer = Timer()
-
-    @timer.timeit()
-    def outer():
-        @timer.timeit()
-        def inner():
-            time.sleep(0.1)
-
-        return inner()
-
-    outer()
-
-    # Should have two print calls (inner and outer)
-    assert mock_print.call_count == 2
-    inner_output = mock_print.call_args_list[0][0][0]
-    outer_output = mock_print.call_args_list[1][0][0]
-
-    inner_time = float(inner_output.split('took ')[1].split(' [')[0])
-    outer_time = float(outer_output.split('took ')[1].split(' [')[0])
-
-    assert outer_time > inner_time
-
-
-def test_unit_scaling(mocker):
-    """Test the time unit selection logic directly"""
-    mock_print = mocker.patch('builtins.print')
-
-    boundary_cases = [
-        (1e3 - 1, 'ns'),
-        (1e3, 'μs'),
-        (1e6 - 1, 'μs'),
-        (1e6, 'ms'),
-        (1e9 - 1, 'ms'),
-        (1e9, 's'),
-    ]
-
-    for ns, expected_unit in boundary_cases:
-        mocker.patch('time.perf_counter_ns', side_effect=[0, ns])
-        timer = Timer(precision=2)
-
-        @timer.timeit()
-        def dummy():
-            pass
-
-        dummy()
-        printed_output = mock_print.call_args[0][0]
-        assert expected_unit in printed_output, (
-            f"Failed for {ns:,}ns → Expected '{expected_unit}' in output. "
-            f'Got: {printed_output}'
-        )
-
-
-def test_function_metadata_preserved():
-    """Test that function metadata (name, docstring) is preserved"""
-    timer = Timer(precision=3)
-
-    @timer.timeit()
-    def dummy_func():
-        """Test docstring"""
-        pass
-
-    assert dummy_func.__name__ == 'dummy_func'
-    assert dummy_func.__doc__ == 'Test docstring'
-
-
-def test_timeit_with_iterations(mocker):
-    mock_print = mocker.patch('builtins.print')
-    mock_time = mocker.patch(
-        'time.perf_counter_ns', side_effect=[0, 1000, 0, 2000, 0, 3000]
-    )
-
-    timer = Timer(precision=2)
-
-    @timer.timeit(iterations=3)
-    def sample_function():
-        return 'done'
-
-    result = sample_function()
-
-    assert result == 'done'
-    mock_time.assert_any_call()
-
-    mock_print.assert_called_once_with(
-        'sample_function took 2.00 [μs] (avg over 3 runs)'
-    )