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

nano_dev_utils/__init__.py

@@ -0,0 +1,18 @@
+"""nano-dev-utils - A collection of small Python utilities for developers.
+Copyright (c) 2025 Yaron Dayan
+"""
+
+from .dynamic_importer import Importer
+from .timers import Timer
+from .release_ports import PortsRelease, PROXY_SERVER, INSPECTOR_CLIENT
+from importlib.metadata import version
+
+__version__ = version('nano-dev-utils')
+
+__all__ = [
+    'Importer',
+    'Timer',
+    'PortsRelease',
+    'PROXY_SERVER',
+    'INSPECTOR_CLIENT',
+]

nano_dev_utils/dynamic_importer.py

@@ -0,0 +1,27 @@
+from types import ModuleType
+from typing import Any
+
+import importlib
+
+
+class Importer:
+    def __init__(self):
+        self.imported_modules = {}
+
+    def import_mod_from_lib(self, library: str, module_name: str) -> ModuleType | Any:
+        """Lazily imports and caches a specific submodule from a given library.
+        :param library: The name of the library.
+        :param module_name: The name of the module to import.
+        :return: The imported module.
+        """
+        if module_name in self.imported_modules:
+            return self.imported_modules[module_name]
+
+        lib_mod = f'{library}.{module_name}'
+
+        try:
+            module = importlib.import_module(lib_mod)
+            self.imported_modules[module_name] = module
+            return module
+        except ModuleNotFoundError as e:
+            raise ImportError(f'Could not import {lib_mod}') from e

nano_dev_utils/release_ports.py

@@ -0,0 +1,155 @@
+import platform
+import subprocess
+import logging
+
+lgr = logging.getLogger(__name__)
+"""Module-level logger. Configure using logging.basicConfig() in your application."""
+
+PROXY_SERVER = 6277
+INSPECTOR_CLIENT = 6274
+
+
+class PortsRelease:
+    def __init__(self, default_ports: list[int] | None = None):
+        self.default_ports: list[int] = (
+            default_ports
+            if default_ports is not None
+            else [PROXY_SERVER, INSPECTOR_CLIENT]
+        )
+
+    @staticmethod
+    def _log_process_found(port: int, pid: int) -> str:
+        return f'Process ID (PID) found for port {port}: {pid}.'
+
+    @staticmethod
+    def _log_process_terminated(pid: int, port: int) -> str:
+        return f'Process {pid} (on port {port}) terminated successfully.'
+
+    @staticmethod
+    def _log_no_process(port: int) -> str:
+        return f'No process found listening on port {port}.'
+
+    @staticmethod
+    def _log_invalid_port(port: int) -> str:
+        return f'Invalid port number: {port}. Skipping.'
+
+    @staticmethod
+    def _log_terminate_failed(
+        pid: int, port: int | None = None, error: str | None = None
+    ) -> str:
+        base_msg = f'Failed to terminate process {pid}'
+        if port:
+            base_msg += f' (on port {port})'
+        if error:
+            base_msg += f'. Error: {error}'
+        return base_msg
+
+    @staticmethod
+    def _log_line_parse_failed(line: str) -> str:
+        return f'Could not parse PID from line: {line}'
+
+    @staticmethod
+    def _log_unexpected_error(e: Exception) -> str:
+        return f'An unexpected error occurred: {e}'
+
+    @staticmethod
+    def _log_cmd_error(error: bytes) -> str:
+        return f'Error running command: {error.decode()}'
+
+    @staticmethod
+    def _log_unsupported_os() -> str:
+        return f'Unsupported OS: {platform.system()}'
+
+    def get_pid_by_port(self, port: int) -> int | None:
+        """Gets the process ID (PID) listening on the specified port."""
+        system = platform.system()
+        try:
+            cmd: str = {
+                'Windows': f'netstat -ano | findstr :{port}',
+                'Linux': f'ss -lntp | grep :{port}',
+                'Darwin': f'lsof -i :{port}',
+            }.get(system, '')
+            if not cmd:
+                lgr.error(self._log_unsupported_os())
+                return None
+
+            process = subprocess.Popen(
+                cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
+            )
+            output, error = process.communicate()
+            if error:
+                lgr.error(self._log_cmd_error(error))
+                return None
+
+            lines: list[str] = output.decode().splitlines()
+            for line in lines:
+                if str(port) in line:
+                    parts: list[str] = line.split()
+                    if system == 'Windows' and len(parts) > 4:
+                        try:
+                            return int(parts[4])
+                        except ValueError:
+                            lgr.error(self._log_line_parse_failed(line))
+                            return None
+                    elif system == 'Linux':
+                        for part in parts:
+                            if 'pid=' in part:
+                                try:
+                                    return int(part.split('=')[1])
+                                except ValueError:
+                                    lgr.error(self._log_line_parse_failed(line))
+                                    return None
+                    elif system == 'Darwin' and len(parts) > 1:
+                        try:
+                            return int(parts[1])
+                        except ValueError:
+                            lgr.error(self._log_line_parse_failed(line))
+                            return None
+            return None
+        except Exception as e:
+            lgr.error(self._log_unexpected_error(e))
+            return None
+
+    def kill_process(self, pid: int) -> bool:
+        """Kills the process with the specified PID."""
+        try:
+            cmd: str = {
+                'Windows': f'taskkill /F /PID {pid}',
+                'Linux': f'kill -9 {pid}',
+                'Darwin': f'kill -9 {pid}',
+            }.get(platform.system(), '')  # fallback to empty string
+            if not cmd:
+                lgr.error(self._log_unsupported_os())
+                return False
+            process = subprocess.Popen(cmd, shell=True, stderr=subprocess.PIPE)
+            _, error = process.communicate()
+            if process.returncode:
+                error_msg = error.decode()
+                lgr.error(self._log_terminate_failed(pid=pid, error=error_msg))
+                return False
+            return True
+        except Exception as e:
+            lgr.error(self._log_unexpected_error(e))
+            return False
+
+    def release_all(self, ports: list[int] | None = None) -> None:
+        try:
+            ports_to_release: list[int] = self.default_ports if ports is None else ports
+
+            for port in ports_to_release:
+                if not isinstance(port, int):
+                    lgr.error(self._log_invalid_port(port))
+                    continue
+
+                pid: int | None = self.get_pid_by_port(port)
+                if pid is None:
+                    lgr.info(self._log_no_process(port))
+                    continue
+
+                lgr.info(self._log_process_found(port, pid))
+                if self.kill_process(pid):
+                    lgr.info(self._log_process_terminated(pid, port))
+                else:
+                    lgr.error(self._log_terminate_failed(pid=pid, port=port))
+        except Exception as e:
+            lgr.error(self._log_unexpected_error(e))

nano_dev_utils/timers.py

@@ -0,0 +1,49 @@
+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.6.dist-info → nano_dev_utils-0.5.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nano_dev_utils
-Version: 0.5.6
+Version: 0.5.8
 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
@@ -34,10 +34,12 @@ This module provides a `Timer` class for measuring the execution time of code bl
     * `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]`**:   
+* **`timeit(
+        self, iterations: int = 1
+    ) -> 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 total execution time, prints the function name and execution    
+      calculates the average execution time, prints the function name and execution    
       time (optionally including arguments), and returns the result of the original function.
 
 #### Example Usage:
@@ -49,7 +51,7 @@ from nano_dev_utils.timers import Timer
 timer = Timer(precision=6, verbose=True)
 
 
-@timer.timeit
+@timer.timeit()
 def my_function(a, b=10):
   """A sample function."""
   time.sleep(0.1)

nano_dev_utils-0.5.8.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=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,,

nano_dev_utils-0.5.6.dist-info/RECORD

@@ -1,5 +0,0 @@
-LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
-nano_dev_utils-0.5.6.dist-info/METADATA,sha256=X5nF5ZkwJ4UmQMISX2ZDiDEP8OQV7yMjCeACZuAKy3k,5498
-nano_dev_utils-0.5.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nano_dev_utils-0.5.6.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
-nano_dev_utils-0.5.6.dist-info/RECORD,,

nano_dev_utils-0.5.6.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Yaron Dayan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.