Path Tree

Purpose

VCollab applications frequently need to scan directory structures — listing files and subdirectories recursively, representing them as structured data for API responses, and generating CLI-style tree visualizations.

The vcti-path-tree package provides Pydantic models (File, Directory) for representing file system trees and entry points — get_path_tree() for scanning directories into models, get_cli_tree() for generating tree visualizations, walk_tree() for iterating over scanned trees, and get_tree_stats() for summary statistics.

Requires Python 3.12+. Dependencies: pydantic, vcti-enum.

Installation

From GitHub (recommended for development)

# Latest main branch
pip install vcti-path-tree



### In `requirements.txt`

vcti-path-tree>=1.1.1

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-path-tree>=1.1.1",
]

Quick Start

from pathlib import Path
from vcti.pathtree import get_path_tree, get_cli_tree

# Scan a directory into Pydantic models
tree = get_path_tree(Path("/data/project"))

# Generate a CLI-style tree visualization
lines = get_cli_tree(tree)
for line in lines:
    print(line)
# project/
# ├── src/
# │   ├── main.py
# │   └── utils.py
# └── README.md

# Access model attributes
root = tree[0]
print(root.name)       # "project"
print(root.type)       # PathType.DIRECTORY
for child in root.children:
    print(f"  {child.name} ({child.type})")

# Relative paths with posix format
tree = get_path_tree(
    Path("/data/project"),
    base_path=Path("/data"),
    as_posix=True
)
print(tree[0].path)    # "project"

# Skip root directory, get only children
children = get_path_tree(Path("/data/project"), skip_root=True)

# Limit recursion depth
tree = get_path_tree(Path("/data/project"), max_depth=2)

# Filter: only include .py files and directories
tree = get_path_tree(
    Path("/data/project"),
    filter_fn=lambda p: p.is_dir() or p.suffix == ".py",
)

# Include file timestamps
tree = get_path_tree(Path("/data/project"), include_metadata=True)

# Serialize to JSON (Pydantic models)
import json
print(json.dumps([node.model_dump() for node in tree], indent=2))

Public API

Limitations

• Symlinks are followed. The scanner uses Python's default behavior (Path.stat(), Path.iterdir()), which follows symbolic links. Use max_depth to guard against cycles from recursive symlinks.
• Permission errors propagate. If a file or directory is not readable, OSError is raised. There is no partial-tree or skip-on-error mode.
• Entire tree is materialized in memory. Not suitable for very large directory trees where streaming would be preferred.

Documentation

• Design — Concepts, architecture decisions, and trade-offs
• Source Guide — Execution flow traces for developers
• API Reference — Autodoc for all modules