Skip to content

Python API

Two objects, kept deliberately apart. JsonBuilder decides what is in the tree; ArbolTerminalView draws exactly what it is given and filters nothing.

import arbol

builder = arbol.JsonBuilder(ignore_patterns=["__*__/", "*.pyc"], level=2)
json_path = builder.write_directory("some/dir")

view = arbol.ArbolTerminalView()
print(view.render(arbol.JsonBuilder.load(json_path)))

Module-level shortcuts cover the simple cases:

arbol.render({"ROOT": "r", "a": ["x", "y"]})
arbol.print_tree(arbol.load_json("tree.json"))
arbol.write_directory_json("some/dir", level=2)

By default write_directory puts the JSON in a temporary folder and leaves it there for you to clean up. Pass output_path to save it somewhere real; missing parent directories are created and an existing file is overwritten.

The dict shape

Everything renders from one shape, which is JSON-native — only dicts, lists and strings:

{"ROOT": "sample_tree", "docs": ["api.md", "guide.md", {"images": ["logo.png"]}]}
  • a directory is a list of entries
  • a file is a string in that list
  • a subdirectory is a single-key dict, {name: [...entries]}

Files have two representations

At the top level every entry is a dict key, so a top-level file is emitted as name: [] — an empty child list, which renders as a leaf. A nested file is a plain string inside its parent's list. Anything consuming this shape has to handle both.

ROOT names the root node and is filtered out before recursion, so it never appears as a branch.

Behavior worth knowing

  • Symlinked directories are listed but never followed, so a symlink loop cannot blow up the output. tree behaves the same without -l.
  • A directory that cannot be read is drawn as empty rather than aborting the walk.
  • Entries sort directories first, then files, case-insensitively — the same order as tree --dirsfirst.
  • ignore_patterns matches names at any depth, never paths, and applies to files and directories alike unless a trailing / narrows it. See Ignore patterns.
  • show_all=True is the -a flag: it turns off the default hiding of dot names and dunder folders. Patterns still apply on top of it.
  • render uses a fixed-width, non-terminal console and right-strips every line, so its output is stable and comparable against a literal.