file-tree-display 1.0.0__py3-none-any.whl

file_tree_display/__init__.py

@@ -0,0 +1,33 @@
+"""file-tree-display - A utility for generating a visually structured directory tree.
+Copyright (c) 2025 Yaron Dayan
+"""
+
+from pathlib import Path
+from importlib.metadata import version
+
+from nano_dev_utils.common import (
+    update,
+    str2file,
+    PredicateBuilder,
+    FilterSet,
+    load_cfg_file,
+)
+
+from .ftd import FileTreeDisplay
+from ._constants import PKG_NAME
+
+filetree_display = FileTreeDisplay(root_dir=str(Path.cwd()))
+predicate_builder = PredicateBuilder
+
+__version__ = version(PKG_NAME)
+
+__all__ = [
+    'update',
+    'str2file',
+    'PredicateBuilder',
+    'predicate_builder',
+    'FilterSet',
+    'filetree_display',
+    'FileTreeDisplay',
+    'load_cfg_file',
+]

file_tree_display/__main__.py

@@ -0,0 +1,129 @@
+"""CLI interface for FileTreeDisplay"""
+
+import argparse
+import sys
+
+
+from pathlib import Path
+from typing import Any
+
+from .ftd import FileTreeDisplay
+from nano_dev_utils.common import load_cfg_file
+from ._constants import DEFAULT_SFX
+
+
+def parse() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description='Display or export a formatted file tree of a directory.',
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument('--cfg', type=str, help='Path to JSON config file.')
+    parser.add_argument('--root-dir', '-r', type=str, help='Root directory to display.')
+    parser.add_argument('--filepath', '-o', type=str, help='Output file path.')
+    parser.add_argument(
+        '--ignore-dirs', nargs='*', default=None, help='Directories to ignore.'
+    )
+    parser.add_argument(
+        '--ignore-files', nargs='*', default=None, help='Files to ignore.'
+    )
+    parser.add_argument(
+        '--include-dirs', nargs='*', default=None, help='Directories to include.'
+    )
+    parser.add_argument(
+        '--include-files', nargs='*', default=None, help='Files to include.'
+    )
+    parser.add_argument(
+        '--style',
+        '-s',
+        choices=['classic', 'dash', 'arrow', 'plus'],
+        default='classic',
+        help='Tree connector style.',
+    )
+    parser.add_argument(
+        '--indent', '-i', type=int, default=2, help='Indent width per level.'
+    )
+    parser.add_argument(
+        '--files-first',
+        '-f',
+        action='store_true',
+        default=False,
+        help='List files before directories.',
+    )
+    parser.add_argument(
+        '--skip-sorting', action='store_true', default=False, help='Disable sorting.'
+    )
+    parser.add_argument(
+        '--sort-key',
+        choices=['natural', 'lex', 'custom'],
+        default='natural',
+        help='Sorting mode.',
+    )
+    parser.add_argument(
+        '--reverse', action='store_true', default=False, help='Reverse sort order.'
+    )
+    parser.add_argument(
+        '--no-save', action='store_true', default=False, help='Do not save to file.'
+    )
+    parser.add_argument(
+        '--printout',
+        '-p',
+        action='store_true',
+        default=False,
+        help='Print tree to stdout.',
+    )
+    parser.add_argument(
+        '--version', '-v', action='version', version=f'{FileTreeDisplay.get_version()}'
+    )
+    return parser.parse_args()
+
+
+def merge_config(
+    cli_args: argparse.Namespace, cfg_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Merge CLI args and config file into a unified options dict."""
+    merged = {**cfg_dict}
+    for k, v in vars(cli_args).items():
+        if v is not None and k != 'cfg':
+            merged[k] = v
+    return merged
+
+
+def main() -> None:
+    args = parse()
+    cfg_dict = load_cfg_file(args.cfg)
+    opts = merge_config(args, cfg_dict)
+
+    root_dir = Path(opts.get('root_dir') or Path.cwd())
+    if not root_dir.exists():
+        sys.exit(f"Error: root directory '{root_dir}' does not exist.")
+
+    filepath = opts.get('filepath')
+    if not filepath and not opts.get('no-save'):
+        filepath = str(root_dir.with_name(f'{root_dir.name}{DEFAULT_SFX}'))
+
+    ftd = FileTreeDisplay(
+        root_dir=str(root_dir),
+        filepath=filepath,
+        ignore_dirs=opts.get('ignore_dirs') or [],
+        ignore_files=opts.get('ignore_files') or [],
+        include_dirs=opts.get('include_dirs') or [],
+        include_files=opts.get('include_files') or [],
+        style=opts.get('style', 'classic'),
+        indent=int(opts.get('indent', 2)),
+        files_first=bool(opts.get('files_first', False)),
+        skip_sorting=bool(opts.get('skip_sorting', False)),
+        sort_key_name=opts.get('sort_key', 'natural'),
+        reverse=bool(opts.get('reverse', False)),
+        save2file=not opts.get('no_save', False),
+        printout=opts.get('printout', False),
+    )
+
+    try:
+        ftd.file_tree_display()
+    except Exception as e:
+        sys.exit(f'Error: {e}')
+
+
+if __name__ == '__main__':
+    main()

file_tree_display/__version__.py

@@ -0,0 +1 @@
+__version__ = '1.0.0'

file_tree_display/_constants.py

@@ -0,0 +1,2 @@
+PKG_NAME = 'file-tree-display'
+DEFAULT_SFX = '_filetree.txt'

file_tree_display/ftd.py

@@ -0,0 +1,325 @@
+import io
+import os
+import re
+
+from collections.abc import Generator
+from itertools import chain
+from pathlib import Path
+from typing_extensions import Callable, Any
+from typing import Iterable
+
+from importlib.metadata import version, PackageNotFoundError
+from nano_dev_utils.common import str2file, FilterSet, PredicateBuilder
+from ._constants import PKG_NAME
+
+_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.
+    """
+
+    __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 = '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.
+
+        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.
+            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'.
+            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.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,
+        }
+
+        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
+        )
+
+    @staticmethod
+    def get_version():
+        try:
+            return version(PKG_NAME)
+        except PackageNotFoundError:
+            return 'unknown'
+
+    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_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
+        )
+
+    @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 _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:
+        """Generates a directory tree and saves it to a text file.
+
+        Returns:
+            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.")
+
+        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 and filepath:
+            str2file(tree_info, filepath)
+
+        if self.printout:
+            print(tree_info)
+
+        self.get_num_of_entries(tree_info)
+
+        return tree_info
+
+    def get_tree_info(self, iterator: Generator[str, None, None]) -> str:
+        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 or disk drive currently being traversed.
+            prefix (str): Hierarchical prefix applied to each level.
+
+        Yields:
+            str: A formatted text representation of the folder structure.
+        """
+        branch = style['branch']
+        end = style['end']
+        vertical = style['vertical']
+        space = style['space']
+
+        recurse = self._build_tree
+
+        dirs: list[tuple[str, str]] = []
+        files: list[str] = []
+
+        try:
+            with os.scandir(dir_path) as it:
+                append_dir = dirs.append
+                append_file = files.append
+                for entry in it:
+                    name = entry.name
+                    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, 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)
+
+        # 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)
+        )
+
+        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,
+        }
+
+    @staticmethod
+    def get_num_of_entries(tree_info: str) -> None:
+        num_of_folders = tree_info.count('/') - 1
+        num_of_files = tree_info.count('\n') - num_of_folders
+        print(f'Scanned {num_of_folders} folders and {num_of_files} files.')

file_tree_display-1.0.0.dist-info/METADATA

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: file_tree_display
+Version: 1.0.0
+Summary: A utility for generating a visually structured directory tree.
+Project-URL: Homepage, https://github.com/yaronday/file_tree_display
+Project-URL: Issues, https://github.com/yaronday/file_tree_display/issues
+Project-URL: license, https://github.com/yaronday/file_tree_display/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
+Requires-Dist: nano-dev-utils>=1.6.2
+Description-Content-Type: text/markdown
+
+# file_tree_display
+
+A utility for generating a visually structured directory tree.
+
+## Modules
+
+## `file_tree_display.py`
+
+This core module 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
+
+The measurements were carried out on unfiltered folders containing multiple files und subdirectories, using SSD.   
+Avg. time was measured over 20 runs per configuration, using `timeit` decorator I've implemented in this package. 
+
+Comparing FileTreeDisplay (FTD) with
+[win_tree_wrapper](https://github.com/yaronday/nano_dev_utils/blob/master/benchmark/win_tree_wrapper.py) 
+(Windows [tree](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/tree) 
+wrapper which I've implemented for this purpose).    
+[Benchtest code](https://github.com/yaronday/nano_dev_utils/blob/master/benchmark/benchtest.py)  
+
+### Performance Comparison — FTD vs.`tree`
+
+<table>
+<tr><th>Test Context </th><th>Results</th></tr>
+<tr><td>
+
+| Metric               | Test1  | Test2      |
+|:---------------------|:-------|:-----------|
+| **Files**            | 10553  | 138492     |
+| **Folders**          | 1235   | 20428      |
+| **Wrapper Overhead** | ~30 ms | negligible |
+
+</td><td>
+
+| Tool     | T1 (s) | T2 (s) | Relative Speed |
+|:---------|:------:|:------:|:--------------:|
+| **FTD**  | 0.196  | 2.900* |       —        |
+| **tree** | 0.390  | 5.018  |   ~2x slower   |
+
+</td></tr> </table>
+
+***Without sorting** FTD takes 162 ms and 2.338 s for Test1 and Test2, respectively.  
+FTD is roughly **1.7x–2.4x faster** than the native `tree` binary across both datasets.  
+
+### Brief Analysis
+
+### I. Linear scaling as a function of entries 
+FTD performance scales almost perfectly linearly with total entries:
+
+* **T1:** 10 k files → 0.2 s
+* **T2:** 138 k files → 2.9 s
+  → ~14x more files → ~15x more runtime => expected by linearity.
+
+### II. Figuring out why `tree` is nearly 2 times slower than my FTD    
+Although `tree` is implemented in C, it incurs more I/O work:  
+* Performs full `lstat()` on each entry (permissions, timestamps, etc.).  
+* Prints incrementally to `stdout` → many system calls (syscalls).  
+* Handles color / formatting output.  
+
+My FTD avoids this by:  
+
+* Using `os.scandir()` (caching stat info).
+* Filtering and sorting in-memory.
+* Buffering output before optional print/write.
+
+Result: lower syscall count and fewer I/O stalls.
+
+### III. Python overhead is clearly negligible
+Even at 2.9 s for ~160K entries, throughput ~55K entries/s — close to filesystem limits on SSDs.
+Measured wrapper overhead (~30 ms) is < 1 % of total runtime.
+
+### Key Insights
+
+| Observation                    | Explanation                                         |
+|:-------------------------------|:----------------------------------------------------|
+| **FTD ~2x faster than `tree`** | Avoids per-file printing and redundant stats.       |
+| **I/O-bound execution**        | Filesystem metadata fetch dominates total time.     |
+| **Linear runtime scaling**     | Recursive generator design adds no hidden overhead. |
+| **Stable memory footprint**    | Uses streaming generators and `StringIO` buffering. |
+
+### Conclusions 
+
+* **FTD outperforms `tree` by roughly 2x** on both moderate and large datasets.  
+* **Runtime scales linearly** with total directory entries.  
+* **Python layer overhead is negligible** — performance is bounded by kernel I/O.
+
+
+#### Class Overview
+
+**`FileTreeDisplay`**
+Constructs and manages the visual representation of a folder structure of a path or of a disk drive.
+
+**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`                               | Characters used to mark hierarchy levels. Defaults to `'classic'`.               |
+| `indent`                              | `int`                               | Number of style characters per level. Defaults `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`                               | Sort key. Lexicographic ('lex') 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, *, prefix, style, sort_key,   
+   files_first, dir_filter, file_filter, reverse, indent) -> Generator[str, None, None]`  
+Recursively traverses the directory tree in depth-first order (DFS) and yields formatted lines representing the file and folder structure.
+
+| Parameter                           | Type                    | Description                                                                  |
+|-------------------------------------|-------------------------|------------------------------------------------------------------------------|
+| **`dir_path`**                      | `str`                   | Path to the directory being traversed.                                       |
+| **`prefix`**                        | `str`                   | Current indentation prefix for nested entries.                               |
+| **`style`**                         | `dict[str, str]`        | Connector style mapping with keys: `branch`, `end`, `space`, and `vertical`. |
+| **`sort_key`**                      | `Callable[[str], Any]`  | Function used to sort directory and file names.                              |
+| **`files_first`**                   | `bool`                  | If `True`, list files before subdirectories.                                 |
+| **`dir_filter`**, **`file_filter`** | `Callable[[str], bool]` | Predicates to include or exclude directories and files.                      |
+| **`reverse`**                       | `bool`                  | If `True`, reverses the sort order.                                          |
+| **`indent`**                        | `int`                   | Number of spaces (or repeated characters) per indentation level.             |
+
+
+#### 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='classic',
+                      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()
+```
+
+#### Custom connector style   
+You can define and register your own connector styles at runtime by adding entries to style_dict:
+
+```Python
+from nano_dev_utils.file_tree_display import FileTreeDisplay
+ftd = FileTreeDisplay(root_dir=".")
+ftd.style_dict["plus2"] = ftd.connector_styler("+-- ", "+== ")
+ftd.style = "plus2"
+ftd.printout = 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
+
+
+## FTD CLI — File Tree Display
+
+The **FTD CLI** (`ftd`) is a lightweight, configurable command-line tool for displaying or exporting a formatted file tree of a given directory.  
+It’s designed for flexibility, allowing users to control inclusion/exclusion rules, visual style, sorting behavior, and output options.
+
+---
+
+### Features
+
+* Generate a clean, formatted file tree of any directory
+* Choose from multiple connector styles (`classic`, `dash`, `arrow`, `plus`)
+* Fine-grained control over included/excluded files and directories
+* Flexible sorting modes (`natural`, `lex`, or `custom`)
+* Optionally export the tree to a file or print directly to stdout
+* Supports configuration via JSON config file
+
+---
+
+### Usage
+
+```bash
+ftd [OPTIONS]
+```
+
+Example:
+
+```bash
+ftd --root-dir ./src --style arrow --files-first --printout
+```
+
+This displays the tree structure of the `src` directory using the *arrow* connector style, listing files before directories, and prints the output to the console.
+
+---
+
+### Command-Line Options
+
+| Option            | Alias | Type   | Description                                                | Default   |
+|-------------------|-------|--------|------------------------------------------------------------|-----------|
+| `--cfg`           | –     | `str`  | Path to a JSON configuration file.                         | –         |
+| `--root-dir`      | `-r`  | `str`  | Root directory to display.                                 | –         |
+| `--filepath`      | `-o`  | `str`  | Output file path for exported tree.                        | –         |
+| `--ignore-dirs`   | –     | `str…` | Directories to exclude from the tree.                      | –         |
+| `--ignore-files`  | –     | `str…` | Files to exclude from the tree.                            | –         |
+| `--include-dirs`  | –     | `str…` | Directories to explicitly include.                         | –         |
+| `--include-files` | –     | `str…` | Files to explicitly include.                               | –         |
+| `--style`         | `-s`  | `str`  | Tree connector style (`classic`, `dash`, `arrow`, `plus`). | `classic` |
+| `--indent`        | `-i`  | `int`  | Indent width (spaces) per directory level.                 | `2`       |
+| `--files-first`   | `-f`  | flag   | List files before directories.                             | `False`   |
+| `--skip-sorting`  | –     | flag   | Disable sorting altogether.                                | `False`   |
+| `--sort-key`      | –     | `str`  | Sorting key: `natural`, `lex`, or `custom`.                | `natural` |
+| `--reverse`       | –     | flag   | Reverse the sort order.                                    | `False`   |
+| `--no-save`       | –     | flag   | Do not save output to file (useful with `--printout`).     | `False`   |
+| `--printout`      | `-p`  | flag   | Print the generated tree to stdout.                        | `False`   |
+| `--version`       | `-v`  | flag   | Show the current version of FTD and exit.                  | –         |
+
+---
+
+### Configuration via JSON file
+
+FTD can also load parameters from a JSON config file:
+
+```json
+{
+  "root_dir": "./project",
+  "ignore_dirs": ["__pycache__", "build"],
+  "ignore_files": [".DS_Store"],
+  "style": "dash",
+  "files_first": true,
+  "printout": true
+}
+```
+
+Run it using:
+
+```bash
+ftd --cfg path/to/config.json
+```
+
+Command-line arguments always **override** config file values.
+
+---
+
+### Examples
+
+Display the current directory with default settings:
+
+```bash
+ftd -r .
+```
+
+Display a tree with dashed connectors, ignoring test folders, and print it:
+
+```bash
+ftd -r ./src --ignore-dirs tests --style dash --printout
+```
+
+Export a formatted tree to a file:
+
+```bash
+ftd -r ./app --filepath tree.txt
+```
+
+Reverse lexical sort with 4-space indentation:
+
+```bash
+ftd -r ./data --sort-key lex --reverse --indent 4
+```
+
+---
+
+### 🧾 Output Example
+
+```text
+src
+├── main.py
+├── utils
+│   ├── helpers.py
+│   └── validators.py
+└── tests
+    ├── test_main.py
+    └── test_utils.py
+```
+
+---
+
+***
+
+## License
+This project is licensed under the MIT License. 
+See [LICENSE](https://github.com/yaronday/file_tree_display/blob/master/LICENSE) for details.

file_tree_display-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+file_tree_display/__init__.py,sha256=jkyGGykmiDBixkjDQD2N1p4cXQzbU8YlpmyiY4tUOyg,718
+file_tree_display/__main__.py,sha256=o74jt4m-8ycgmmKELMGXwdQDnQBJtx9ymHgJCI4l-9Y,4160
+file_tree_display/__version__.py,sha256=crlYURA_2Ujkpz7iVPHovvxZRtvt4QBXF5AAFJzRfz0,23
+file_tree_display/_constants.py,sha256=C4oom9OD9QrJ6wW53ULhmuHLCIKw9pmXkHjLrjOcMAU,63
+file_tree_display/ftd.py,sha256=T8OJXpry9BgcTlfg5MPGb-yM_SpKHZgluG2OwElC2ys,11764
+file_tree_display-1.0.0.dist-info/METADATA,sha256=8FdkRn1OwNq2WukopnNQvDOSsI03L0SImi5lUacyU6o,15505
+file_tree_display-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+file_tree_display-1.0.0.dist-info/entry_points.txt,sha256=L_gNQlsvydWniPChrLbA6a36_5-YuxVqMq9i4a6cEU8,56
+file_tree_display-1.0.0.dist-info/licenses/LICENSE,sha256=Muenl7Bw_LdtHZtlOMAP7Kt97gDCq8WWp2605eDWhHU,1089
+file_tree_display-1.0.0.dist-info/RECORD,,

file_tree_display-1.0.0.dist-info/WHEEL

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

file_tree_display-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ftd = file_tree_display.__main__:main

file_tree_display-1.0.0.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.