py-ascii-tree 0.2.0

String ASCII tree from list or directory of filepaths

ASCII Tree from Paths

Create ASCII tree strings from list or directories of filepaths. Useful for formatting directory information into LLM context window.

Installation

pip install py-ascii-tree

Example usage

Basic Usage with Strings

from py_ascii_tree import ascii_tree

example_paths = [
    "src/main.py",
    "src/utils/helpers.py",
    "src/utils/config.py",
    "src/utils/database.py",
    "src/utils/auth.py",
    "src/models/user.py",
    "src/models/database.py",
    "tests/test_main.py",
    "tests/test_utils.py",
    "tests/integration/test_api.py",
    "tests/integration/test_db.py",
    "docs/README.md",
    "docs/api/endpoints.md",
    "docs/api/authentication.md",
    "requirements.txt",
    ".gitignore",
]

print("1. Basic tree (no limits):")
print(ascii_tree(example_paths))
print("\n" + "=" * 60 + "\n")

print("2. With depth limit (max_depth=2):")
print(ascii_tree(example_paths, max_depth=2))
print("\n" + "=" * 60 + "\n")

print("3. With separate file and directory limits (max_files_per_dir=2, max_dirs_per_dir=1):")
print(ascii_tree(example_paths, max_files_per_dir=2, max_dirs_per_dir=1))
print("\n" + "=" * 60 + "\n")

print("4. With file limit only (max_files_per_dir=3):")
print(ascii_tree(example_paths, max_files_per_dir=3))
print("\n" + "=" * 60 + "\n")

Output:

1. Basic tree (no limits):
├── src
│   ├── utils
│   │   ├── helpers.py
│   │   ├── config.py
│   │   ├── database.py
│   │   └── auth.py
│   ├── models
│   │   ├── user.py
│   │   └── database.py
│   └── main.py
├── tests
│   ├── integration
│   │   ├── test_api.py
│   │   └── test_db.py
│   ├── test_main.py
│   └── test_utils.py
├── docs
│   ├── api
│   │   ├── endpoints.md
│   │   └── authentication.md
│   └── README.md
├── requirements.txt
└── .gitignore

============================================================

2. With depth limit (max_depth=2):
├── src
│   ├── utils
│   │   ├── ... (depth limit reached)
│   ├── models
│   │   ├── ... (depth limit reached)
│   └── main.py
├── tests
│   ├── integration
│   │   ├── ... (depth limit reached)
│   ├── test_main.py
│   └── test_utils.py
├── docs
│   ├── api
│   │   ├── ... (depth limit reached)
│   └── README.md
├── requirements.txt
└── .gitignore

============================================================

3. With separate file and directory limits (max_files_per_dir=2, max_dirs_per_dir=1):
├── src
│   ├── utils
│   │   ├── helpers.py
│   │   ├── config.py
│   │   └── ... (2 more files)
│   ├── main.py
│   └── ... (1 more directories)
├── requirements.txt
├── .gitignore
└── ... (2 more directories)

============================================================

4. With file limit only (max_files_per_dir=3):
├── src
│   ├── utils
│   │   ├── helpers.py
│   │   ├── config.py
│   │   ├── database.py
│   │   └── ... (1 more files)
│   ├── models
│   │   ├── user.py
│   │   └── database.py
│   └── main.py
├── tests
│   ├── integration
│   │   ├── test_api.py
│   │   └── test_db.py
│   ├── test_main.py
│   └── test_utils.py
├── docs
│   ├── api
│   │   ├── endpoints.md
│   │   └── authentication.md
│   └── README.md
├── requirements.txt
└── .gitignore

Usage with Dictionary for Path and File Size

from py_ascii_tree import ascii_tree

path_sizes = {
    "src/main.py": 2048,
    "src/utils/helpers.py": 1024,
    "src/utils/config.py": 512,
    "src/utils/database.py": 4096,
    "src/utils/auth.py": 3072,
    "src/models/user.py": 1536,
    "tests/test_main.py": 2560,
    "README.md": 1024,
    "requirements.txt": 256,
}

print("5. With file sizes displayed:")
print(ascii_tree(path_sizes, show_sizes=True))
print("\n" + "=" * 60 + "\n")

print("6. Sorted by size, 2 files per directory, 1 subdir per directory, sizes shown:")
print(
    ascii_tree(
        path_sizes,
        max_files_per_dir=2,
        max_dirs_per_dir=1,
        sort_by_size=True,
        show_sizes=True,
    )
)
print("\n" + "=" * 60 + "\n")

print("7. All limits combined:")
print(
    ascii_tree(
        path_sizes,
        max_depth=4,
        max_files_per_dir=3,
        max_dirs_per_dir=1,
        sort_by_size=True,
        show_sizes=True,
    )
)

Output:

============================================================

5. With file sizes displayed:
├── src
│   ├── utils
│   │   ├── helpers.py (1.0KB)
│   │   ├── config.py (512B)
│   │   ├── database.py (4.0KB)
│   │   └── auth.py (3.0KB)
│   ├── models
│   │   └── user.py (1.5KB)
│   └── main.py (2.0KB)
├── tests
│   └── test_main.py (2.5KB)
├── README.md (1.0KB)
└── requirements.txt (256B)

============================================================

6. Sorted by size, 2 files per directory, 1 subdir per directory, sizes shown:
├── src
│   ├── utils
│   │   ├── database.py (4.0KB)
│   │   ├── auth.py (3.0KB)
│   │   └── ... (2 more files)
│   ├── main.py (2.0KB)
│   └── ... (1 more directories)
├── README.md (1.0KB)
├── requirements.txt (256B)
└── ... (1 more directories)

============================================================

7. All limits combined:
├── src
│   ├── utils
│   │   ├── database.py (4.0KB)
│   │   ├── auth.py (3.0KB)
│   │   ├── helpers.py (1.0KB)
│   │   └── ... (1 more files)
│   ├── main.py (2.0KB)
│   └── ... (1 more directories)
├── README.md (1.0KB)
├── requirements.txt (256B)
└── ... (1 more directories)