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

nano_dev_utils/__init__.py

@@ -2,10 +2,19 @@
 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 importlib.metadata import version
+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')
 
@@ -15,4 +24,15 @@ __all__ = [
     '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

@@ -2,12 +2,16 @@ 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.

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

@@ -2,6 +2,9 @@ import platform
 import subprocess
 import logging
 
+from .common import update
+
+
 lgr = logging.getLogger(__name__)
 """Module-level logger. Configure using logging.basicConfig() in your application."""
 
@@ -60,6 +63,12 @@ class PortsRelease:
     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()

nano_dev_utils/timers.py

@@ -1,68 +1,214 @@
 from functools import wraps
 import time
-from typing import Callable, ParamSpec, TypeVar
+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):
+    def __init__(
+        self, precision: int = 4, verbose: bool = False, printout: bool = False
+    ):
         self.precision = precision
         self.verbose = verbose
-        self.units = [(1e9, 's'), (1e6, 'ms'), (1e3, 'μs'), (1.0, 'ns')]
+        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, 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'
+    ) -> 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)'
                 )
-                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}'
+        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)'
                 )
-                return result
 
-            return wrapper
+    @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
 
-        return decorator
+        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.1.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: nano_dev_utils
+Version: 1.4.1
+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.1.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=5Ci6IgdEfwIvRtQes4byab1GJowLdfnurUBUxorSgIc,7840
+nano_dev_utils-1.4.1.dist-info/METADATA,sha256=sfJDvXpotS86VX6o1XjnwFY3CDoTNUpJkDlLoOpFsGM,12133
+nano_dev_utils-1.4.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nano_dev_utils-1.4.1.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
+nano_dev_utils-1.4.1.dist-info/RECORD,,

nano_dev_utils-1.0.0.dist-info/METADATA

@@ -1,167 +0,0 @@
-Metadata-Version: 2.4
-Name: nano_dev_utils
-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
-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
-Provides-Extra: test
-Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
-Requires-Dist: pytest>=8.2.0; extra == 'test'
-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)`**: 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,
-        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:
-
-```python
-import time
-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
-
-# 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.dynamic_importer import Importer
-
-importer = 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 PortsRelease
-
-# For configuration of logging level and format (supported already):  
-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')
-
-# Create an instance with default ports
-port_releaser = PortsRelease()
-port_releaser.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
-port_releaser.release_all()
-```
-
-## License
-This project is licensed under the MIT License. 
-See [LICENSE](LICENSE) for details.

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