nano-dev-utils 0.5.8__py3-none-any.whl → 1.0.0__py3-none-any.whl

nano_dev_utils/timers.py

@@ -7,38 +7,57 @@ R = TypeVar('R')
 
 
 class Timer:
-    def __init__(self, precision=4, verbose=False):
+    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
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
     ) -> 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."""
+        """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 = 0
-                result = None
+                total_elapsed_ns = 0
+                result: R | None = None
 
-                for _ in range(iterations):
-                    start = time.perf_counter_ns()
+                for i in range(1, iterations + 1):
+                    start_ns = time.perf_counter_ns()
                     result = func(*args, **kwargs)
-                    total_elapsed += time.perf_counter_ns() - start
+                    duration_ns = time.perf_counter_ns() - start_ns
+                    total_elapsed_ns += duration_ns
 
-                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
+                    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 ''
+                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}'
                 )

{nano_dev_utils-0.5.8.dist-info → nano_dev_utils-1.0.0.dist-info}/METADATA

@@ -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-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+nano_dev_utils/__init__.py,sha256=imiI367TPj5s4IFmi-VrKJLbdkIxdIPISNscthoaS9U,454
+nano_dev_utils/dynamic_importer.py,sha256=cm2VwDYSGwhGZNO3uMX-O0LaKtEFtzkPm7BrZW4igG4,911
+nano_dev_utils/release_ports.py,sha256=sgmoPax9Hpcse1rHbBSnDJWTkvV6aWpZ5hQFxBKhGR8,5886
+nano_dev_utils/timers.py,sha256=dTbmf2O10YQw_Gz_fVATdZXqxgSpTjTlbeekd_jpLyw,2875
+nano_dev_utils-1.0.0.dist-info/METADATA,sha256=YOD8JC-1a-gaDHF5-VYu3Qtr5-uqHlsSorPguSZvk58,6498
+nano_dev_utils-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nano_dev_utils-1.0.0.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
+nano_dev_utils-1.0.0.dist-info/RECORD,,

nano_dev_utils-0.5.8.dist-info/RECORD

@@ -1,8 +0,0 @@
-nano_dev_utils/__init__.py,sha256=imiI367TPj5s4IFmi-VrKJLbdkIxdIPISNscthoaS9U,454
-nano_dev_utils/dynamic_importer.py,sha256=cm2VwDYSGwhGZNO3uMX-O0LaKtEFtzkPm7BrZW4igG4,911
-nano_dev_utils/release_ports.py,sha256=sgmoPax9Hpcse1rHbBSnDJWTkvV6aWpZ5hQFxBKhGR8,5886
-nano_dev_utils/timers.py,sha256=IiCltOHRkYqfX_IzHQ2Xty4ptITBiaOldFO1HhQ6r_A,1748
-nano_dev_utils-0.5.8.dist-info/METADATA,sha256=KA_vxHbiStc8At1rFrWu2Rt8G_eJzyrRLeb3tYQWfUs,5550
-nano_dev_utils-0.5.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nano_dev_utils-0.5.8.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
-nano_dev_utils-0.5.8.dist-info/RECORD,,