treeproject

treeproject is a lightweight Python library providing simple, deterministic utilities to:

• render a directory structure as a readable Unicode tree,
• extract and concatenate file contents into a single structured text bundle.

It is designed for documentation, debugging, tooling, and building compact filesystem context bundles (for example, for LLM prompts).

The API is intentionally minimal, dependency-free, and based on pathlib.Path.

---

Installation

pip install treeproject

Requires Python 3.10+.

---

Features

• Unicode tree rendering (similar to the Unix tree command)
• Deterministic traversal (directories first, case-insensitive sorting)
• Strict pruning-based filtering
• Optional symbolic link traversal
• Text content extraction with stable formatting
• Binary file detection and skipping
• Configurable encoding and error handling
• Zero runtime dependencies

---

Quick Start

Render a directory tree

from pathlib import Path
from treeproject import path_tree

print(path_tree(Path("./my_project")))

Example output:

my_project
├── README.md
├── pyproject.toml
└── src
    ├── __init__.py
    └── app.py

---

Extract file contents

from pathlib import Path
from treeproject import path_content

bundle = path_content(Path("./my_project"))
print(bundle)

Example output format:

===== FILE: README.md =====
# My Project
...
===== END FILE =====

===== FILE: src/app.py =====
print("hello")
===== END FILE =====

---

Filtering and Pruning

Filtering is controlled via an include(Path) -> bool predicate.

If the predicate returns False for a directory, the directory is pruned and none of its descendants are visited.

IGNORE = {".git", "__pycache__", ".pytest_cache"}

def include(p: Path) -> bool:
    return p.name not in IGNORE

print(path_tree(Path("."), include=include))

The same predicate can be reused for content extraction.

---

API Reference

path_tree(root, *, follow_symlinks=False, include=lambda p: True) -> str

Render a Unicode directory tree and return it as a string.

• Directories are listed before files
• Sorting is case-insensitive
• Excluded directories are fully pruned

---

`path_content(root, *, follow_symlinks=False, include=lambda p: True,

skip_binary=True, encoding="utf-8", errors="raise") -> str`

Walk a filesystem path and return a single string containing the formatted contents of all selected files.

• Files are processed in deterministic order
• Binary files can be skipped automatically
• Errors can be raised or ignored per file

---

Design Notes

• Uses pathlib.Path.walk for traversal
• No global state
• No side effects except explicit string rendering in path_tree
• Suitable for programmatic use and automation

---

Development

git clone https://github.com/dylan-lebreton/treeproject
cd treeproject
poetry install
pytest

---

License

MIT License

Copyright (c) 2025 Dylan Lebreton