nano-dev-utils 1.4.2__py3-none-any.whl

nano_dev_utils/__init__.py

@@ -0,0 +1,38 @@
+"""nano-dev-utils - A collection of small Python utilities for developers.
+Copyright (c) 2025 Yaron Dayan
+"""
+
+from pathlib import Path
+from importlib.metadata import version
+from .dynamic_importer import Importer
+from .timers import Timer
+from .release_ports import PortsRelease, PROXY_SERVER, INSPECTOR_CLIENT
+from .common import update, encode_dict, str2file, PredicateBuilder, FilterSet
+from .file_tree_display import FileTreeDisplay, DEFAULT_SFX
+
+timer = Timer()
+ports_release = PortsRelease()
+importer = Importer()
+filetree_display = FileTreeDisplay(root_dir=str(Path.cwd()))
+predicate_builder = PredicateBuilder
+
+__version__ = version('nano-dev-utils')
+
+__all__ = [
+    'Importer',
+    'Timer',
+    'PortsRelease',
+    'PROXY_SERVER',
+    'INSPECTOR_CLIENT',
+    'update',
+    'encode_dict',
+    'str2file',
+    'PredicateBuilder',
+    'predicate_builder',
+    'FilterSet',
+    'timer',
+    'ports_release',
+    'importer',
+    'filetree_display',
+    'DEFAULT_SFX',
+]

nano_dev_utils/common.py

@@ -0,0 +1,177 @@
+import fnmatch
+import re
+
+from pathlib import Path
+from typing import AnyStr
+
+from collections.abc import Callable
+from functools import partial
+from typing import TypeAlias
+
+
+FilterSet: TypeAlias = list[str] | set[str] | None
+
+
+def update(obj: object, attrs: dict) -> None:
+    """Updates an object's attributes from a dictionary.
+    Uses direct __dict__ modification if possible for performance,
+    otherwise falls back to setattr for objects without __dict__ (e.g., __slots__).
+
+    Args:
+        obj: The object whose attributes will be updated.
+        attrs: Dictionary of attribute names and values.
+
+    Raises:
+        AttributeError: If an attribute cannot be set (optional, see notes).
+    """
+    if hasattr(obj, '__dict__'):
+        obj.__dict__.update(attrs)
+    else:
+        for key, value in attrs.items():
+            try:
+                setattr(obj, key, value)
+            except AttributeError as e:
+                raise AttributeError(
+                    f"Cannot set attribute '{key}' on object '{obj}': {e}"
+                )
+
+
+def encode_dict(input_dict: dict) -> bytes:
+    """
+    Encodes the values of a dictionary into a single bytes object.
+
+    Each value in the dictionary is converted to its string representation, encoded as bytes,
+    and concatenated together with a single space (b' ') separator.
+
+    Parameters:
+        input_dict (dict): The dictionary whose values are to be encoded.
+
+    Returns:
+        bytes: A single bytes object containing all values, separated by spaces.
+
+    Example:
+        >>> encode_dict({"a": 1, "b": "test"})
+        b'1 test'
+
+    Raises:
+        TypeError: If input_dict is not a dictionary.
+    """
+    if not isinstance(input_dict, dict):
+        raise TypeError('input_dict must be a dictionary.')
+    return b' '.join(str(v).encode() for v in input_dict.values())
+
+
+def str2file(
+    content: AnyStr, filepath: str, mode: str = 'w', enc: str = 'utf-8'
+) -> None:
+    """Simply save file directly from any string content.
+
+    Args:
+        content (AnyStr): String or bytes to write. Must match the mode type ,e.g. bytes for binary.
+        filepath (str): Full file path to write to.
+        mode (str): see doc for Path.open. Defaults to 'w'.
+        enc (str): Encoding used in text modes; ignored in binary modes. Defaults to 'utf-8'.
+    """
+    out_file_path = Path(filepath)
+    try:
+        if 'b' in mode:
+            with out_file_path.open(mode) as f:
+                f.write(content)
+        else:
+            with out_file_path.open(mode, encoding=enc) as f:
+                f.write(content)
+
+    except PermissionError as e:
+        raise PermissionError(f"Cannot write to '{out_file_path}': {e}")
+    except OSError as e:
+        raise OSError(f"Error writing file '{out_file_path}': {e}")
+
+
+class PredicateBuilder:
+    def build_predicate(
+        self, allow: FilterSet, block: FilterSet
+    ) -> Callable[[str], bool]:
+        """Build a memory-efficient predicate function."""
+        compile_patts = self.compile_patts
+
+        allow_lits, allow_patts = compile_patts(allow)
+        block_lits, block_patts = compile_patts(block)
+
+        flag = (
+            1 if allow_lits or allow_patts else 0,
+            1 if block_lits or block_patts else 0,
+        )
+
+        match flag:  # (allow, block)
+            case (0, 0):
+                return lambda name: True
+
+            case (0, 1):
+                return partial(
+                    self._match_patt_with_lits,
+                    name_patts=block_patts,
+                    name_lits=block_lits,
+                    negate=True,
+                )
+
+            case (1, 0):
+                return partial(
+                    self._match_patt_with_lits,
+                    name_patts=allow_patts,
+                    name_lits=allow_lits,
+                    negate=False,
+                )
+
+            case (1, 1):
+                return partial(
+                    self._allow_block_predicate,
+                    allow_lits=allow_lits,
+                    allow_patts=allow_patts,
+                    block_lits=block_lits,
+                    block_patts=block_patts,
+                )
+
+    @staticmethod
+    def compile_patts(fs: FilterSet) -> tuple[set[str], list[re.Pattern]]:
+        if not fs:
+            return set(), []
+        literals, patterns = set(), []
+        for item in fs:
+            if '*' in item or '?' in item or '[' in item:
+                patterns.append(re.compile(fnmatch.translate(item)))
+            else:
+                literals.add(item)
+        return literals, patterns
+
+    @staticmethod
+    def _match_patts(name: str, patterns: list[re.Pattern]) -> bool:
+        """Return True if name matches any compiled regex pattern."""
+        return any(pat.fullmatch(name) for pat in patterns)
+
+    def _match_patt_with_lits(
+        self,
+        name: str,
+        *,
+        name_lits: set[str],
+        name_patts: list[re.Pattern],
+        negate: bool = False,
+    ) -> bool:
+        """Return True if name is in literals or matches any pattern."""
+        res = name in name_lits or self._match_patts(name, name_patts)
+        return not res if negate else res
+
+    def _allow_block_predicate(
+        self,
+        name: str,
+        *,
+        allow_lits: set[str],
+        allow_patts: list[re.Pattern],
+        block_lits: set[str],
+        block_patts: list[re.Pattern],
+    ) -> bool:
+        """Return True if name is allowed and not blocked (block takes precedence)."""
+        if name in block_lits or self._match_patts(name, block_patts):
+            return False
+        if name in allow_lits or self._match_patts(name, allow_patts):
+            return True
+        return False

nano_dev_utils/dynamic_importer.py

@@ -0,0 +1,31 @@
+from types import ModuleType
+from typing import Any
+
+import importlib
+from nano_dev_utils.common import update
+
+
+class Importer:
+    def __init__(self):
+        self.imported_modules = {}
+
+    def update(self, attrs: dict) -> None:
+        update(self, attrs)
+
+    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/file_tree_display.py

@@ -0,0 +1,219 @@
+import os
+import re
+
+from collections.abc import Generator
+from pathlib import Path
+from typing_extensions import Callable, Any
+
+from .common import str2file, FilterSet, PredicateBuilder
+
+
+DEFAULT_SFX = '_filetree.txt'
+
+STYLES: list[str] = [' ', '-', '—', '_', '*', '>', '<', '+', '.']
+
+_NUM_SPLIT = re.compile(r'(\d+)').split
+
+
+class FileTreeDisplay:
+    """Generate and display a visual file tree of a directory.
+
+    This class builds a directory tree structure and yields formatted
+    visual representations of directories and files.
+    Supports exclusion lists, configurable indentation, and custom prefix styles.
+    """
+
+    def __init__(
+        self,
+        root_dir: str | None = None,
+        filepath: str | None = None,
+        ignore_dirs: FilterSet = None,
+        ignore_files: FilterSet = None,
+        include_dirs: FilterSet = None,
+        include_files: FilterSet = None,
+        style: str = ' ',
+        indent: int = 2,
+        files_first: bool = False,
+        sort_key_name: str = 'natural',
+        reverse: bool = False,
+        custom_sort: Callable[[str], Any] | None = None,
+        save2file: bool = True,
+        printout: bool = False,
+    ) -> None:
+        """Initialize the FileTreeDisplay instance.
+
+        Args:
+            root_dir (str): Root directory to traverse.
+            filepath: str | None: full output file path.
+            ignore_dirs (list[str] | set[str] | None): Directory names or patterns to ignore.
+            ignore_files (list[str] | set[str] | None): File names or patterns to ignore.
+            include_dirs (list[str] | set[str] | None): Directory names or patterns to include.
+            include_files (list[str] | set[str] | None): File names or patterns to include.
+            style (str): Character(s) used to represent hierarchy levels. Defaults to " ".
+            indent (int): Number of style characters used per hierarchy level. Defaults to 2.
+            files_first (bool): Determines whether to list files first. Defaults to False.
+            sort_key_name (str): sorting key name, e.g. 'lex' for lexicographic or 'custom'. Defaults to 'natural'.
+                                 '' means no sorting.
+            reverse (bool): reversed sorting.
+            custom_sort (Callable[[str], Any] | None):
+            save2file (bool): save file tree info to a file.
+            printout (bool): print file tree info.
+        """
+        self.root_path = Path(root_dir) if root_dir else Path.cwd()
+        self.filepath = filepath
+        self.ignore_dirs = set(ignore_dirs or [])
+        self.ignore_files = set(ignore_files or [])
+        self.include_dirs = set(include_dirs or [])
+        self.include_files = set(include_files or [])
+        self.style = style
+        self.indent = indent
+        self.files_first = files_first
+        self.sort_key_name = sort_key_name
+        self.reverse = reverse
+        self.custom_sort = custom_sort
+        self.save2file = save2file
+        self.printout = printout
+
+        self.sort_keys = {
+            'natural': self._nat_key,
+            'lex': self._lex_key,
+            'custom': self.custom_sort,
+            '': None,
+        }
+
+        self.pb = PredicateBuilder()
+        self.dir_filter = self.pb.build_predicate(self.include_dirs, self.ignore_dirs)
+        self.file_filter = self.pb.build_predicate(
+            self.include_files, self.ignore_files
+        )
+
+    def init(self, *args, **kwargs) -> None:
+        self.__init__(*args, **kwargs)
+
+    def update(self, attrs: dict) -> None:
+        self.__dict__.update(attrs)
+        pattern = re.compile(r'^(ign|inc)')
+        if any(pattern.match(key) for key in attrs):
+            self.update_predicates()
+
+    def update_predicates(self):
+        self.dir_filter = self.pb.build_predicate(self.include_dirs, self.ignore_dirs)
+        self.file_filter = self.pb.build_predicate(
+            self.include_files, self.ignore_files
+        )
+
+    @staticmethod
+    def _nat_key(name: str) -> list[int | str | Any]:
+        """Natural sorting key"""
+        return [
+            int(part) if part.isdigit() else part.lower() for part in _NUM_SPLIT(name)
+        ]
+
+    @staticmethod
+    def _lex_key(name: str) -> str:
+        """Lexicographic sorting key"""
+        return name.lower()
+
+    def file_tree_display(self) -> str:
+        """Generate and save the directory tree to a text file.
+
+        Returns:
+            Either a str: Path to the saved output file containing the directory tree.
+            or the whole built tree, as a string of CRLF-separated lines.
+        """
+        root_path_str = str(self.root_path)
+        filepath = self.filepath
+        if not self.root_path.is_dir():
+            raise NotADirectoryError(f"The path '{root_path_str}' is not a directory.")
+
+        if self.style not in STYLES:
+            raise ValueError(f"'{self.style}' is invalid: must be one of {STYLES}\n")
+
+        iterator = self.build_tree(root_path_str)
+
+        tree_info = self.get_tree_info(iterator)
+
+        if self.save2file and filepath:
+            str2file(tree_info, filepath)
+            return filepath
+
+        if self.printout:
+            print(tree_info)
+
+        return tree_info
+
+    def get_tree_info(self, iterator: Generator[str, None, None]) -> str:
+        lines = [f'{self.root_path.name}/']
+        lines.extend(list(iterator))
+        return '\n'.join(lines)
+
+    def build_tree(self, dir_path: str, prefix: str = '') -> Generator[str, None, None]:
+        """Yields formatted directory tree lines, using a recursive DFS.
+        Intended order of appearance is with a preference to subdirectories first.
+
+        Args:
+            dir_path (str): The directory path currently being traversed.
+            prefix (str): Hierarchical prefix applied to each level.
+
+        Yields:
+            str: A formatted string representing either a directory or a file.
+        """
+        files_first = self.files_first
+        dir_filter, file_filter = self.dir_filter, self.file_filter
+        sort_key_name, reverse = self.sort_key_name, self.reverse
+        sort_key = self.sort_keys.get(self.sort_key_name)
+        curr_indent = self.style * self.indent
+
+        next_prefix = prefix + curr_indent
+
+        if sort_key is None:
+            if sort_key_name == 'custom':
+                raise ValueError(
+                    "custom_sort function must be specified when sort_key_name='custom'"
+                )
+            raise ValueError(f'Invalid sort key name: {sort_key_name}')
+
+        try:
+            with os.scandir(dir_path) as entries:
+                dirs, files = [], []
+                append_dir, append_file = dirs.append, files.append
+                for entry in entries:
+                    name = entry.name
+                    if entry.is_dir():
+                        if dir_filter(name):
+                            append_dir((name, entry.path))
+                    else:
+                        if file_filter(name):
+                            append_file(name)
+
+        except (PermissionError, OSError) as e:
+            msg = (
+                '[Permission Denied]'
+                if isinstance(e, PermissionError)
+                else '[Error reading directory]'
+            )
+            yield f'{next_prefix}{msg}'
+            return
+
+        if sort_key:
+            dirs.sort(key=lambda d: sort_key(d[0]), reverse=reverse)
+            files.sort(key=sort_key, reverse=reverse)
+
+        if files_first:
+            for name in files:
+                yield next_prefix + name
+
+        for name, path in dirs:
+            yield f'{next_prefix}{name}/'
+            yield from self.build_tree(path, next_prefix)
+
+        if not files_first:
+            for name in files:
+                yield next_prefix + name
+
+    def format_out_path(self) -> Path:
+        alt_file_name = f'{self.root_path.name}{DEFAULT_SFX}'
+        out_file = (
+            Path(self.filepath) if self.filepath else (self.root_path / alt_file_name)
+        )
+        return out_file

nano_dev_utils/release_ports.py

@@ -0,0 +1,164 @@
+import platform
+import subprocess
+import logging
+
+from .common import update
+
+
+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 init(self, *args, **kwargs) -> None:
+        self.__init__(*args, **kwargs)
+
+    def update(self, attrs: dict) -> None:
+        update(self, attrs)
+
+    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,214 @@
+from functools import wraps
+import time
+import logging
+import inspect
+
+from typing import (
+    TypeVar,
+    ParamSpec,
+    Callable,
+    Awaitable,
+    Any,
+    cast,
+)
+
+from nano_dev_utils.common import update
+
+
+lgr = logging.getLogger(__name__)
+"""Module-level logger. Configure using logging.basicConfig() in your application."""
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+class Timer:
+    def __init__(
+        self, precision: int = 4, verbose: bool = False, printout: bool = False
+    ):
+        self.precision = precision
+        self.verbose = verbose
+        self.printout = printout
+
+    def init(self, *args, **kwargs) -> None:
+        self.__init__(*args, **kwargs)
+
+    def update(self, attrs: dict[str, Any]) -> None:
+        update(self, attrs)
+
+    def res_formatter(self, elapsed_ns: float, *, precision: int = 4) -> str:
+        return self._duration_formatter(elapsed_ns, precision=precision)
+
+    def timeit(
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
+    ) -> Callable[[Callable[P, Any]], Callable[P, Any]]:
+        """Decorator that measures execution time for sync / async functions.
+
+        Args:
+            iterations: Number of times to run the function (averaged for reporting).
+            timeout: Optional max allowed time (in seconds); raises TimeoutError if exceeded.
+            per_iteration: If True, enforces timeout per iteration, else cumulatively.
+
+        Returns:
+        A decorated function that behaves identically to the original, with timing logged.
+        """
+
+        RP = ParamSpec('RP')
+        RR = TypeVar('RR')
+
+        precision, verbose, printout = self.precision, self.verbose, self.printout
+        check_timeout = self._check_timeout
+        duration_formatter = self._duration_formatter
+        formatted_msg = self._formatted_msg
+
+        def decorator(
+            func: Callable[RP, RR] | Callable[RP, Awaitable[RR]],
+        ) -> Callable[RP, Any]:
+            if inspect.iscoroutinefunction(func):
+                async_func = cast(Callable[RP, Awaitable[RR]], func)
+
+                @wraps(func)
+                async def async_wrapper(*args: RP.args, **kwargs: RP.kwargs) -> RR:
+                    func_name = func.__name__
+                    total_elapsed_ns = 0
+                    result: RR | None = None
+                    for i in range(1, iterations + 1):
+                        start_ns = time.perf_counter_ns()
+                        result = await async_func(*args, **kwargs)
+                        duration_ns = time.perf_counter_ns() - start_ns
+                        total_elapsed_ns += duration_ns
+
+                        check_timeout(
+                            func_name,
+                            i,
+                            duration_ns,
+                            total_elapsed_ns,
+                            timeout,
+                            per_iteration,
+                        )
+                    avg_elapsed_ns = total_elapsed_ns / iterations
+                    duration_str = duration_formatter(avg_elapsed_ns, precision)
+
+                    msg = formatted_msg(
+                        func_name, args, kwargs, duration_str, iterations, verbose
+                    )
+                    lgr.info(msg)
+                    if printout:
+                        print(msg)
+                    return cast(RR, result)
+
+                return cast(Callable[RP, Awaitable[RR]], async_wrapper)
+            else:
+                sync_func = cast(Callable[RP, RR], func)
+
+                @wraps(func)
+                def sync_wrapper(*args: RP.args, **kwargs: RP.kwargs) -> RR:
+                    func_name = func.__name__
+                    total_elapsed_ns = 0
+                    result: RR | None = None
+                    for i in range(1, iterations + 1):
+                        start_ns = time.perf_counter_ns()
+                        result = sync_func(*args, **kwargs)
+                        duration_ns = time.perf_counter_ns() - start_ns
+                        total_elapsed_ns += duration_ns
+                        check_timeout(
+                            func_name,
+                            i,
+                            duration_ns,
+                            total_elapsed_ns,
+                            timeout,
+                            per_iteration,
+                        )
+                    avg_elapsed_ns = total_elapsed_ns / iterations
+                    duration_str = duration_formatter(avg_elapsed_ns, precision)
+                    msg = formatted_msg(
+                        func_name, args, kwargs, duration_str, iterations, verbose
+                    )
+                    lgr.info(msg)
+                    if printout:
+                        print(msg)
+                    return cast(RR, result)
+
+                return cast(Callable[RP, RR], sync_wrapper)
+
+        return decorator
+
+    def _check_timeout(
+        self,
+        func_name: str,
+        i: int,
+        duration_ns: float,
+        total_elapsed_ns: float,
+        timeout: float | None,
+        per_iteration: bool,
+    ) -> None:
+        """Raise TimeoutError if timeout is exceeded."""
+        if timeout is None:
+            return
+        precision = self.precision
+        timeout_exceeded = f'{func_name} exceeded {timeout:.{precision}f}s'
+        if per_iteration:
+            duration_s = duration_ns / 1e9
+            if duration_s > timeout:
+                raise TimeoutError(
+                    f'{timeout_exceeded} on iteration {i} '
+                    f'(took {duration_s:.{precision}f}s)'
+                )
+        else:
+            total_duration_s = total_elapsed_ns / 1e9
+            if total_duration_s > timeout:
+                raise TimeoutError(
+                    f'{timeout_exceeded} after {i} iterations '
+                    f'(took {total_duration_s:.{precision}f}s)'
+                )
+
+    @staticmethod
+    def _duration_formatter(elapsed_ns: float, precision: int = 4) -> str:
+        """Convert nanoseconds to the appropriate time unit, supporting multi-unit results."""
+        ns_sec, ns_min, ns_hour = 1e9, 6e10, 3.6e12
+        ns_ms, ns_us = 1e6, 1e3
+
+        if elapsed_ns < ns_sec:
+            if elapsed_ns >= ns_ms:
+                return f'{elapsed_ns / ns_ms:.{precision}f} ms'
+            elif elapsed_ns >= ns_us:
+                return f'{elapsed_ns / ns_us:.{precision}f} μs'
+            return f'{elapsed_ns:.2f} ns'
+
+        if elapsed_ns < ns_min:
+            seconds = elapsed_ns / ns_sec
+            return f'{seconds:.1f} s' if seconds < 10 else f'{seconds:.0f} s'
+
+        if elapsed_ns >= ns_hour:
+            hours = int(elapsed_ns / ns_hour)
+            rem = elapsed_ns % ns_hour
+            mins = int(rem / ns_min)
+            secs = int((rem % ns_min) / ns_sec)
+
+            parts = [f'{hours} h']
+            if mins:
+                parts.append(f'{mins} m')
+            if secs:
+                parts.append(f'{secs} s')
+            return ' '.join(parts)
+
+        else:
+            minutes = int(elapsed_ns / ns_min)
+            seconds = int((elapsed_ns % ns_min) / ns_sec)
+            return f'{minutes} m {seconds} s' if seconds else f'{minutes} m'
+
+    @staticmethod
+    def _formatted_msg(
+        func_name: str,
+        args: tuple,
+        kwargs: dict,
+        duration_str: str,
+        iterations: int,
+        verbose: bool,
+    ) -> str:
+        extra_info = f'{args} {kwargs} ' if verbose else ''
+        iter_info = f' (avg. over {iterations} runs)' if iterations > 1 else ''
+        return f'{func_name} {extra_info}took {duration_str}{iter_info}'

nano_dev_utils-1.4.2.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: nano_dev_utils
+Version: 1.4.2
+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
+Project-URL: license, https://github.com/yaronday/nano_dev_utils/blob/master/LICENSE
+Author-email: Yaron Dayan <yaronday77@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: build>=1.3.0
+Description-Content-Type: text/markdown
+
+# nano_dev_utils
+
+A collection of small Python utilities for developers.
+
+## Modules
+
+### `timers.py`
+
+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, printout: 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`.
+    * `printout`: Allows printing to console.
+
+* **`def timeit(
+        self,
+        iterations: int = 1,
+        timeout: float | None = None,
+        per_iteration: bool = False,
+    ) -> Callable[[Callable[P, Any]], Callable[P, Any]]:`**:   
+      Decorator that times either **sync** or **async** 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
+        * Logs the function name and execution time (with optional arguments)
+        * Returns the result of the original function (unless timeout occurs)
+
+#### Example Usage:
+
+```python
+import time
+import logging
+from nano_dev_utils import timer
+
+# This timer version uses a logger but also allows printing (if enabled), so it has to be configured in your app, for instance: 
+logging.basicConfig(filename='timer example.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+# Basic timing
+@timer.timeit()
+def my_function(a, b=10):
+    """A sample function."""
+    time.sleep(0.1)
+    return a + b
+
+timer.init(precision=6, verbose=True)
+'''Alternative options: 
+timer.update({'precision': 6, 'verbose': True})  # 1. Using update method  
+
+from nano_dev_utils.timers import Timer  # 2. explicit instantiation
+timer = Timer(precision=6, verbose=True)  
+'''
+
+timer.update({'printout': True})  # allow printing to console
+
+# 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`
+
+This module provides an `Importer` class for lazy loading and caching module imports.
+
+#### `Importer` Class
+
+* **`__init__(self)`**: Initializes an `Importer` instance with an empty dictionary `imported_modules` to cache imported modules.
+
+* **`import_mod_from_lib(self, library: str, module_name: str) -> ModuleType | Any`**: Lazily imports a module from a specified library and caches it.
+    * `library` (str): The name of the library (e.g., "os", "requests").
+    * `module_name` (str): The name of the module to import within the library (e.g., "path", "get").
+    * Returns the imported module. If the module has already been imported, it returns a cached instance.
+    * Raises `ImportError` if the module cannot be found.
+
+#### Example Usage:
+
+```python
+from nano_dev_utils import importer
+
+os_path = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path: {os_path}")
+
+requests_get = importer.import_mod_from_lib("requests", "get")
+print(f"Imported requests.get: {requests_get}")
+
+# Subsequent calls will return the cached module
+os_path_again = importer.import_mod_from_lib("os", "path")
+print(f"Imported os.path again (cached): {os_path_again}")
+```
+
+### `release_ports.py`
+
+This module provides a `PortsRelease` class to identify and release processes 
+listening on specified TCP ports.    
+It supports Windows, Linux, and macOS.
+
+#### `PortsRelease` Class
+
+* **`__init__(self, default_ports: list[int] | None = None)`**: 
+* Initializes a `PortsRelease` instance.
+    * `default_ports`: A list of default ports to manage. If not provided, it defaults to `[6277, 6274]`.
+
+* **`get_pid_by_port(self, port: int) -> int | None`**: A static method that attempts to find   
+     a process ID (PID) listening on a given `port`.       
+*    It uses platform-specific commands (`netstat`, `ss`, `lsof`).       
+*    Returns the PID if found, otherwise `None`.    
+
+* **`kill_process(self, pid: int) -> bool`**: A static method that attempts to kill the process 
+  with the given `pid`.   
+* It uses platform-specific commands (`taskkill`, `kill -9`). 
+* Returns `True` if the process was successfully killed, `False` otherwise. 
+
+* **`release_all(self, ports: list[int] | None = None) -> None`**: Releases all processes listening on the specified `ports`.   
+    * `ports`: A list of ports to release.   
+    * If `None`, it uses the `default_ports` defined during initialization.   
+    * For each port, it first tries to get the PID and then attempts to kill the process.       
+    * It logs the actions and any errors encountered. Invalid port numbers in the provided list are skipped.
+
+#### Example Usage:
+
+```python
+import logging
+from nano_dev_utils import ports_release, PortsRelease
+
+
+# configure the logger
+logging.basicConfig(filename='port release.log',
+                    level=logging.INFO,  # DEBUG, WARNING, ERROR, CRITICAL 
+                    format='%(asctime)s - %(levelname)s: %(message)s',
+                    datefmt='%d-%m-%Y %H:%M:%S')
+
+
+ports_release.release_all()
+
+# Create an instance with custom ports
+custom_ports_releaser = PortsRelease(default_ports=[8080, 9000, 6274])
+custom_ports_releaser.release_all(ports=[8080, 9000])
+
+# Release only the default ports
+ports_release.release_all()
+```
+
+### `file_tree_display.py`
+
+This module provides a utility for generating a visually structured directory tree.  
+It supports recursive traversal, customizable hierarchy styles, and inclusion / exclusion  
+patterns for directories and files.  
+Output can be displayed in the console or saved to a file.
+
+
+#### Key Features
+
+- Recursively displays and logs directory trees
+- Efficient directory traversal
+- Blazing fast (see Benchmarks below)
+- Generates human-readable file tree structure 
+- Supports including / ignoring specific directories or files via pattern matching
+- Customizable tree display output
+- Optionally saves the resulting tree to a text file
+- Lightweight, flexible and easily configurable
+
+
+## Benchmarks
+
+As measured on a dataset of 10553 files, 1235 folders (ca. 16 GB) using Python 3.10 on SSD.   
+Avg. time was measured over 10 runs per configuration.  
+
+| Tool            | Time (s) |
+|-----------------|----------| 
+| FileTreeDisplay | 0.198    |
+| Seedir          | 4.378    |
+
+
+
+#### Class Overview
+
+**`FileTreeDisplay`**
+Constructs and manages the visual representation of a directory structure.
+
+**Initialization Parameters**
+
+| Parameter                  | Type                            | Description                                                                 |
+|:---------------------------|:--------------------------------|:----------------------------------------------------------------------------|
+| `root_dir`                 | `str`                           | Path to the directory to scan.                                              |
+| `filepath`                 | `str / None`                    | Optional output destination for the saved file tree.                        |                                               
+| `ignore_dirs`              | `list[str] or set[str] or None` | Directory names or patterns to skip.                                        |                                                
+| `ignore_files`             | `list[str] or set[str] or None` | File names or patterns to skip.                                             |
+| `include_dirs`             | `list[str] or set[str] or None` | Only include specified folder names or patterns.                            |
+| `include_files`            | `list[str] or set[str] or None` | Only include specified file names or patterns, '*.pdf' - only include pdfs. |
+| `style`                    | `str`                           | Character(s) used to mark hierarchy levels. Defaults to `' '`.              |
+| `indent`                   | `int`                           | Number of style characters per level. Defaults `2`.                         |
+| `files_first`              | `bool`                          | Determines whether to list files first. Defaults to False.                  |
+| `sort_key_name`            | `str`                           | Sort key. 'lex' (lexicographic) or 'custom'. Defaults to 'natural'.         |
+| `reverse`                  | `bool`                          | Reversed sorting order.                                                     |
+| `custom_sort`              | `Callable[[str], Any] / None`   | Custom sort key function.                                                   |
+| `title`                    | `str`                           | Custom title shown in the output.                                           |
+| `save2file`                | `bool`                          | Save file tree (folder structure) info into a file.                         |
+| `printout`                 | `bool`                          | Print file tree info.                                                       |
+
+#### Core Methods
+
+- `file_tree_display(save2file: bool = True) -> str | None`
+Generates the directory tree. If `save2file=True`, saves the output; otherwise prints it directly.
+- `build_tree(dir_path: str, prefix: str = '') -> Generator[str, None, None]`
+Recursively yields formatted lines representing directories and files.
+
+
+#### Example Usage
+
+```python
+from pathlib import Path
+from nano_dev_utils.file_tree_display import FileTreeDisplay
+
+root = r'c:/your_root_dir'
+target_path = r'c:/your_target_path'
+filename = 'filetree.md'
+filepath = str(Path(target_path, filename))
+
+ftd = FileTreeDisplay(root_dir=root,
+                      ignore_dirs=['.git', 'node_modules', '.idea'],
+                      ignore_files=['.gitignore', '*.toml'], 
+                      style='—',
+                      include_dirs=['src', 'tests', 'snapshots'],
+                      filepath=filepath, 
+                      sort_key_name='custom',
+                      custom_sort=(lambda x: any(ext in x.lower() for ext in ('jpg', 'png'))),
+                      files_first=True,
+                      reverse=True
+                     )
+ftd.file_tree_display()
+```
+
+
+#### Error Handling
+
+The module raises well-defined exceptions for common issues:
+
+- `NotADirectoryError` when the path is not a directory
+- `PermissionError` for unreadable directories or write-protected files
+- `OSError` for general I/O or write failures
+
+***
+
+## License
+This project is licensed under the MIT License. 
+See [LICENSE](LICENSE) for details.

nano_dev_utils-1.4.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+nano_dev_utils/__init__.py,sha256=bJNCUyssMVyNmOey-god8A2kElC4nCR9B5DsdvUrKWw,1014
+nano_dev_utils/common.py,sha256=MsY5n9lSOjvEu0wGvmd2zQamFLLbtbjodZku5W9tuWE,5873
+nano_dev_utils/dynamic_importer.py,sha256=-Mh76366lI_mP2QA_jxiVfcKCHOHeukS_j4v7fTh0xw,1028
+nano_dev_utils/file_tree_display.py,sha256=RMd2l1FZgO__9EmCSKRkZ6s7tYpCx6Fe7e83fAxNxg0,8234
+nano_dev_utils/release_ports.py,sha256=yLWMMbN6j6kWtGTg-Nynn37-Q4b2rxkls9hs2sqeZjA,6081
+nano_dev_utils/timers.py,sha256=H6pZBaCasy79ketkGYPwgcLYdNnLSrpIbH9ob0a7iCI,7851
+nano_dev_utils-1.4.2.dist-info/METADATA,sha256=8_9FvdpfJnkDVtHx38tiY9__dp8zMuIl-m0bupKNAXI,12133
+nano_dev_utils-1.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nano_dev_utils-1.4.2.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
+nano_dev_utils-1.4.2.dist-info/RECORD,,

nano_dev_utils-1.4.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nano_dev_utils-1.4.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.