treex-cli 0.1.0__py3-none-any.whl

treex.py

@@ -0,0 +1,258 @@
+# Copyright (c) 2026 Corey Goldberg
+# SPDX-License-Identifier: MIT
+
+
+"""Print a directory tree with file metadata.
+
+The directory tree is rendered using Unicode box-drawing characters. File names are
+displayed with their human-readable size and, optionally, modification time. Text
+files also include their line count. Binary and unreadable files are marked with
+their type.
+
+When run inside a Git repository, files and directories ignored by Git
+are automatically excluded using Git's own ignore rules. If Git is not
+installed, or the directory is not part of a Git repository, the
+filesystem is scanned normally without Git filtering.
+
+Use --all to disable Git ignore filtering and show all files.
+Use --width to control the column at which file metadata starts.
+Use --modified to show file modification times.
+"""
+
+import argparse
+import subprocess
+from contextlib import suppress
+from datetime import datetime
+from pathlib import Path
+
+DEFAULT_METADATA_COLUMN = 50
+
+
+class GitIgnore:
+    """Use Git's own ignore machinery when available."""
+
+    def __init__(self, directory):
+        self.directory = Path(directory).resolve()
+        self.enabled = False
+        self.repo_root = None
+        # Git isn't installed or can't be executed.
+        with suppress(OSError):
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=self.directory,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                text=True,
+                check=False,
+            )
+            if result.returncode == 0:
+                self.repo_root = Path(result.stdout.strip()).resolve()
+                self.enabled = True
+
+    def ignored(self, path):
+        """Return True if Git considers the path ignored."""
+        if not self.enabled:
+            return False
+        try:
+            relative_path = path.resolve().relative_to(self.repo_root)
+            result = subprocess.run(
+                ["git", "check-ignore", "--quiet", "--", str(relative_path)],
+                cwd=self.repo_root,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+        except (ValueError, OSError):
+            return False
+        else:
+            return result.returncode == 0
+
+
+def format_size(size):  # noqa: RET503
+    """Format bytes as a human-readable size."""
+    units = ["B", "KB", "MB", "GB", "TB"]
+    for unit in units:
+        if size < 1024 or unit == units[-1]:
+            if unit == "B":
+                return f"{size} B"
+            return f"{size:.1f} {unit}"
+        size /= 1024
+
+
+def format_modified(timestamp):
+    """Format a modification timestamp for display."""
+    return datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M")
+
+
+def is_binary_file(path, chunk_size=8192):
+    """Return True if the file appears to be binary."""
+    try:
+        with path.open("rb") as f:
+            chunk = f.read(chunk_size)
+        if not chunk:
+            return False
+        # Check for NUL bytes.
+        if b"\x00" in chunk:
+            return True
+        # Treat files that aren't valid UTF-8 as binary.
+        try:
+            chunk.decode("utf-8")
+        except UnicodeDecodeError:
+            return True
+        else:
+            return False
+    except OSError:
+        return True
+
+
+def count_lines(path):
+    """Count lines without loading the entire file into memory."""
+    count = 0
+    try:
+        with path.open("rb") as f:
+            for _ in f:
+                count += 1
+    except OSError:
+        return None
+    return count
+
+
+def file_info(path):
+    """Return size, description, raw size, and modification time."""
+    try:
+        stat = path.stat()
+        size = stat.st_size
+        modified = format_modified(stat.st_mtime)
+    except OSError:
+        return "?", "[unreadable]", 0, None
+    size_text = format_size(size)
+    if is_binary_file(path):
+        return size_text, "[binary]", size, modified
+    lines = count_lines(path)
+    if lines is None:
+        return size_text, "[unreadable]", size, modified
+    return size_text, f"{lines:,} lines", size, modified
+
+
+def print_tree(
+    directory,
+    prefix="",
+    stats=None,
+    gitignore=None,
+    width=DEFAULT_METADATA_COLUMN,
+    show_modified=False,
+):
+    """Recursively print the directory tree."""
+    if stats is None:
+        stats = {
+            "directories": 0,
+            "files": 0,
+            "total_size": 0,
+        }
+    path = Path(directory)
+    try:
+        entries = list(path.iterdir())
+    except PermissionError:
+        print(prefix + "└── [permission denied]")
+        return stats
+    # Filter ignored entries before determining which entry is last.
+    visible_entries = []
+    for entry in entries:
+        # Git's internal repository data is never useful in the tree output.
+        if entry.name == ".git":
+            continue
+        if gitignore and gitignore.ignored(entry):
+            continue
+        visible_entries.append(entry)
+    visible_entries.sort(key=lambda p: (p.is_file(), p.name.lower()))
+    for index, entry in enumerate(visible_entries):
+        is_last = index == len(visible_entries) - 1
+        connector = "└── " if is_last else "├── "
+        if entry.is_dir():
+            stats["directories"] += 1
+            print(prefix + connector + entry.name)
+            extension = "    " if is_last else "│   "
+            print_tree(
+                entry,
+                prefix + extension,
+                stats,
+                gitignore,
+                width,
+                show_modified,
+            )
+        elif entry.is_file():
+            stats["files"] += 1
+            size, info, raw_size, modified = file_info(entry)
+            stats["total_size"] += raw_size
+            # The complete tree/name portion is padded to the
+            # requested width so metadata lines up vertically.
+            tree_name = prefix + connector + entry.name
+            output = f"{tree_name:<{width}}{size:>10}    {info}"
+            if show_modified and modified is not None:
+                output += f"    {modified}"
+            print(output)
+    return stats
+
+
+def parse_args(argv=None):
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="print a directory tree with file metadata.",
+    )
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        default=Path(),
+        type=Path,
+        help="directory to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "-a",
+        "--all",
+        action="store_true",
+        help="show all files, including git-ignored",
+    )
+    parser.add_argument(
+        "-w",
+        "--width",
+        type=int,
+        default=DEFAULT_METADATA_COLUMN,
+        metavar="N",
+        help=f"starting column for file metadata (default: {DEFAULT_METADATA_COLUMN})",
+    )
+    parser.add_argument(
+        "-m",
+        "--modified",
+        action="store_true",
+        help="show file modification times",
+    )
+    return parser.parse_args(argv)
+
+
+def main():
+    args = parse_args()
+    path = args.directory
+    if not path.is_dir():
+        print(f"Not a directory: {path}")
+        return 1
+    if args.width < 1:
+        print("Width must be greater than zero.")
+        return 1
+    # Only initialize Git integration when it will actually be used.
+    gitignore = None if args.all else GitIgnore(path)
+    print(path.resolve())
+    stats = print_tree(
+        path, gitignore=gitignore, width=args.width, show_modified=args.modified
+    )
+    print(
+        f""
+        f""
+        f"{stats['directories']} directories, "
+        f"{stats['files']} files, "
+        f"{format_size(stats['total_size'])}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

treex_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: treex-cli
+Version: 0.1.0
+Summary: Print a directory tree with file metadata
+Author: Corey Goldberg
+Maintainer: Corey Goldberg
+License-Expression: MIT
+Project-URL: homepage, https://github.com/cgoldberg/treex
+Project-URL: source, https://github.com/cgoldberg/treex
+Project-URL: download, https://pypi.org/project/treex-cli
+Keywords: tree,directory,files,cli,metadata
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# treex
+
+## Print a directory tree with file metadata
+
+- Copyright (c) 2026 [Corey Goldberg][github-profile]
+- Development: [GitHub][github-repo]
+- Releases: [PyPI][pypi-home]
+- License: [MIT][mit-license]
+
+----
+
+## About
+
+`treex` is a command-line utility (similar to [tree][tree-home]) that recursively
+scans a directory and prints its contents as a tree using Unicode box-drawing
+characters. File names include their human-readable size and, optionally,
+modification time. Text files also include their line count, while binary and
+unreadable files are marked with their type. When Git is installed, it respects
+`.gitignore` rules.
+
+Requirements:
+
+- Python 3.10+
+- Git 2.0+ (optional)
+- UTF-8-compatible terminal
+
+----
+
+## Installation
+
+Install `treex` from [PyPI][pypi-home] using either `pip` or `pipx`:
+
+- `pip install treex-cli`
+- `pipx install treex-cli`
+
+----
+
+## Usage
+
+```
+$ treex --help
+usage: treex [-h] [-a] [-w N] [-m] [directory]
+
+print a directory tree with file metadata.
+
+positional arguments:
+  directory       directory to scan (default: current directory)
+
+options:
+  -h, --help      show this help message and exit
+  -a, --all       show all files, including git-ignored
+  -w, --width N   starting column for file metadata (default: 50)
+  -m, --modified  show file modification times
+```
+
+[github-profile]: https://github.com/cgoldberg
+[github-repo]: https://github.com/cgoldberg/treex
+[pypi-home]: https://pypi.org/project/treex-cli
+[mit-license]: https://raw.githubusercontent.com/cgoldberg/treex/refs/heads/main/LICENSE
+[tree-home]: https://oldmanprogrammer.net/source.php?dir=projects/tree

treex_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+treex.py,sha256=tij4JJROSG_1seIVUKbMJlHDu84-UTK_lNuD2zRmYE8,7868
+treex_cli-0.1.0.dist-info/licenses/LICENSE,sha256=9cKDUev9NW0GecCyLOnJpvrIFcDRFusy2XrWyiWG304,1071
+treex_cli-0.1.0.dist-info/METADATA,sha256=LefKFkAP9qoNbGQJ5IBHczbXwpkRYVD3N-8whaUEou0,2548
+treex_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+treex_cli-0.1.0.dist-info/entry_points.txt,sha256=hR-28y-rXChHXzu19fhhky5NZt3P6EKxrB-laq78VOg,37
+treex_cli-0.1.0.dist-info/top_level.txt,sha256=Q2lsPiM6enBh4T-ZtRWruXPJPoyJTORjjQNeJtEl-I8,6
+treex_cli-0.1.0.dist-info/RECORD,,

treex_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

treex_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+treex = treex:main

treex_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Goldberg
+
+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.

treex_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+treex