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

nano_dev_utils/timers.py

@@ -7,32 +7,62 @@ 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, func: Callable[P, R]) -> Callable[P, R]:
-        """Decorator that times function execution with automatic unit scaling."""
+    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."""
 
-        @wraps(func)
-        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-            start = time.perf_counter_ns()
-            result = func(*args, **kwargs)
-            elapsed = time.perf_counter_ns() - start
+        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
 
-            value = elapsed
-            unit = 'ns'
+                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
 
-            for divisor, unit in self.units:
-                if elapsed >= divisor or unit == 'ns':
-                    value = 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)'
+                                )
 
-            extra_info = f'{args} {kwargs} ' if self.verbose else ''
-            print(
-                f'{func.__name__} {extra_info}took {value:.{self.precision}f} [{unit}]'
-            )
-            return result
+                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 wrapper
+
+        return decorator

{nano_dev_utils-0.5.7.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.7
+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,21 +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`.
-
-* **`timeit(self, func: Callable[P, R]) -> Callable[P, R]`**:   
-      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 total execution time, prints the function name and execution    
-      time (optionally including arguments), and returns the result of the original function.
+    * `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,
+        timeout: float | None = None,
+        per_iteration: bool = False
+    ) -> Callable[[Callable[P, R]], Callable[P, R | None]]`**:   
+      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:
 
@@ -48,16 +60,22 @@ from nano_dev_utils.timers import Timer
 
 timer = Timer(precision=6, verbose=True)
 
-
-@timer.timeit
+# 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.7.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=EJFFU9y5qv9w9mfjtBsrgyCXj7NoBpXH0AzPewFnRa0,1205
-nano_dev_utils-0.5.7.dist-info/METADATA,sha256=NsqOX4UXr2EhEW7qUkLz_5qL95B9PmqTuDLR4NsNkVY,5498
-nano_dev_utils-0.5.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nano_dev_utils-0.5.7.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
-nano_dev_utils-0.5.7.dist-info/RECORD,,