nano-dev-utils 1.4.0__py3-none-any.whl → 1.5.2__py3-none-any.whl

nano_dev_utils/common.py

@@ -61,7 +61,9 @@ def encode_dict(input_dict: dict) -> bytes:
     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:
+def str2file(
+    content: AnyStr, filepath: str, mode: str = 'w', enc: str = 'utf-8'
+) -> None:
     """Simply save file directly from any string content.
 
     Args:
@@ -71,6 +73,10 @@ def str2file(content: AnyStr, filepath: str, mode: str = 'w', enc: str = 'utf-8'
         enc (str): Encoding used in text modes; ignored in binary modes. Defaults to 'utf-8'.
     """
     out_file_path = Path(filepath)
+
+    if not out_file_path.parent.exists():
+        out_file_path.parent.mkdir(parents=True, exist_ok=True)
+
     try:
         if 'b' in mode:
             with out_file_path.open(mode) as f:
@@ -86,32 +92,48 @@ def str2file(content: AnyStr, filepath: str, mode: str = 'w', enc: str = 'utf-8'
 
 
 class PredicateBuilder:
-    def build_predicate(self, allow: FilterSet, block: FilterSet) -> Callable[[str], bool]:
+    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)
+        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)
+                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)
+                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)
+                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]]:
@@ -119,7 +141,7 @@ class PredicateBuilder:
             return set(), []
         literals, patterns = set(), []
         for item in fs:
-            if "*" in item or "?" in item or "[" in item:
+            if '*' in item or '?' in item or '[' in item:
                 patterns.append(re.compile(fnmatch.translate(item)))
             else:
                 literals.add(item)
@@ -130,15 +152,27 @@ class PredicateBuilder:
         """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:
+    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:
+    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

nano_dev_utils/file_tree_display.py

@@ -1,16 +1,18 @@
+import io
 import os
 import re
 
 from collections.abc import Generator
+from itertools import chain
 from pathlib import Path
-from typing_extensions import LiteralString, Callable, Any
+from typing_extensions import Callable, Any
+from typing import Iterable
 
 from .common import str2file, FilterSet, PredicateBuilder
 
 
 DEFAULT_SFX = '_filetree.txt'
 
-STYLES: list[str] = [' ', '-', '—', '_', '*', '>', '<', '+', '.']
 
 _NUM_SPLIT = re.compile(r'(\d+)').split
 
@@ -22,22 +24,47 @@ class FileTreeDisplay:
     visual representations of directories and files.
     Supports exclusion lists, configurable indentation, and custom prefix styles.
     """
+
+    __slots__ = (
+        'root_path',
+        'filepath',
+        'ignore_dirs',
+        'ignore_files',
+        'include_dirs',
+        'include_files',
+        'style',
+        'indent',
+        'files_first',
+        'skip_sorting',
+        'sort_key_name',
+        'reverse',
+        'custom_sort',
+        'save2file',
+        'printout',
+        'style_dict',
+        'sort_keys',
+        'pb',
+        'dir_filter',
+        'file_filter',
+    )
+
     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,
+        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 = 'classic',
+        indent: int = 2,
+        files_first: bool = False,
+        skip_sorting: 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.
 
@@ -51,8 +78,8 @@ class FileTreeDisplay:
             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.
+            skip_sorting (bool): Skip sorting directly, even if configured.
             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.
@@ -67,69 +94,106 @@ class FileTreeDisplay:
         self.style = style
         self.indent = indent
         self.files_first = files_first
+        self.skip_sorting = skip_sorting
         self.sort_key_name = sort_key_name
         self.reverse = reverse
         self.custom_sort = custom_sort
         self.save2file = save2file
         self.printout = printout
 
+        self.style_dict: dict = {
+            'classic': self.connector_styler('├── ', '└── '),
+            'dash': self.connector_styler('|-- ', '`-- '),
+            'arrow': self.connector_styler('├─> ', '└─> '),
+            'plus': self.connector_styler('+--- ', '\\--- '),
+        }
+
         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)
+        self.file_filter = self.pb.build_predicate(
+            self.include_files, self.ignore_files
+        )
+
+    def format_style(self) -> dict:
+        style, style_dict = self.style, self.style_dict
+        style_keys = list(style_dict.keys())
+        if style not in style_keys:
+            raise ValueError(f"'{style}' is invalid: must be one of {style_keys}\n")
+        return style_dict[style]
 
     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):
+    def update_predicates(self) -> None:
         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)
+        self.file_filter = self.pb.build_predicate(
+            self.include_files, self.ignore_files
+        )
 
     @staticmethod
-    def _nat_key(name: str) -> list[int | LiteralString]:
+    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)]
+        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 _resolve_sort_key(self) -> Callable[[str], Any]:
+        sort_key_name, sort_keys = self.sort_key_name, self.sort_keys
+        key = sort_keys.get(sort_key_name)
+        if key is None:
+            if self.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}"! '
+                             f'Currently defined keys are: {list(sort_keys.keys())}')
+        return key
+
     def file_tree_display(self) -> str:
-        """Generate and save the directory tree to a text file.
+        """Generates a directory tree and saves it 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.
+            str: The complete directory tree as a single CRLF-delimited string.
         """
         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)
+        style = self.format_style()
+        sort_key = None if self.skip_sorting else self._resolve_sort_key()
+        dir_filter, file_filter = self.dir_filter, self.file_filter
+        files_first, reverse = self.files_first, self.reverse
+        indent = self.indent
+
+        iterator = self._build_tree(
+            root_path_str,
+            prefix='',
+            style=style,
+            sort_key=sort_key,
+            files_first=files_first,
+            dir_filter=dir_filter,
+            file_filter=file_filter,
+            reverse=reverse,
+            indent=indent,
+        )
 
         tree_info = self.get_tree_info(iterator)
 
-        if self.save2file:
+        if self.save2file and filepath:
             str2file(tree_info, filepath)
-            return filepath
 
         if self.printout:
             print(tree_info)
@@ -137,73 +201,110 @@ class FileTreeDisplay:
         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.
+        buf = io.StringIO()
+        write = buf.write
+        write(f'{self.root_path.name}/\n')
+        buf.writelines(f'{line}\n' for line in iterator)
+        out = buf.getvalue()
+        return out[:-1] if out.endswith('\n') else out
+
+    def _build_tree(
+        self,
+        dir_path: str,
+        *,
+        prefix: str,
+        style: dict,
+        sort_key: Callable[[str], Any] | None,
+        files_first: bool,
+        dir_filter: Callable[[str], bool],
+        file_filter: Callable[[str], bool],
+        reverse: bool,
+        indent: int,
+    ) -> Generator[str, None, None]:
+        """Yields lines representing a formatted folder structure using a recursive DFS.
+        The internal recursive generator has runtime consts threaded through to avoid attrib. lookups.
 
         Args:
-            dir_path (str): The directory path currently being traversed.
+            dir_path (str): The directory path or disk drive currently being traversed.
             prefix (str): Hierarchical prefix applied to each level.
 
         Yields:
-            str: A formatted string representing either a directory or a file.
+            str: A formatted text representation of the folder structure.
         """
-        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
+        branch = style['branch']
+        end = style['end']
+        vertical = style['vertical']
+        space = style['space']
 
-        next_prefix = prefix + curr_indent
+        recurse = self._build_tree
 
-        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}")
+        dirs: list[tuple[str, str]] = []
+        files: list[str] = []
 
         try:
-            with os.scandir(dir_path) as entries:
-                dirs, files = [], []
-                append_dir, append_file = dirs.append, files.append
-                for entry in entries:
+            with os.scandir(dir_path) as it:
+                append_dir = dirs.append
+                append_file = files.append
+                for entry in it:
                     name = entry.name
-                    if entry.is_dir():
+                    try:
+                        is_dir = entry.is_dir(follow_symlinks=False)
+                    except OSError:
+                        continue
+
+                    if 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}'
+        except (PermissionError, OSError, FileNotFoundError) as e:
+            if isinstance(e, PermissionError):
+                yield '[Permission Denied]'
+            else:
+                yield '[Error reading directory]'
             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)
+        # Compute combined sequence without extra temporary tuples where possible
+        f_iter: Iterable[tuple[str, None, bool]] = ((f, None, False) for f in files)
+        d_iter: Iterable[tuple[str, str, bool]] = ((d[0], d[1], True) for d in dirs)
+        seq: Iterable[tuple[str, str | None, bool]] = (
+            chain(f_iter, d_iter) if files_first else chain(d_iter, f_iter)
         )
-        return out_file
+
+        combined = list(seq)
+        last_index = len(combined) - 1
+
+        for idx, (name, path, is_dir) in enumerate(combined):
+            is_last = idx == last_index
+            connector = end if is_last else branch
+            formatted_name = f'{name}/' if is_dir else name
+            yield f'{prefix}{connector}{formatted_name}'
+            extension = space if is_last else vertical
+
+            if is_dir and path:
+                yield from recurse(
+                    path,
+                    prefix=prefix + extension,
+                    style=style,
+                    sort_key=sort_key,
+                    files_first=files_first,
+                    dir_filter=dir_filter,
+                    file_filter=file_filter,
+                    reverse=reverse,
+                    indent=indent,
+                )
+
+    def connector_styler(self, branch: str, end: str) -> dict:
+        indent = self.indent
+        return {
+            'space': ' ' * indent,
+            'vertical': f'│{" " * (indent - 1)}',
+            'branch': branch,
+            'end': end,
+        }