Install & Compatibility
Where this runs
tested against v0.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.250s · 18.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.226s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
scantree
✓ from scantree import scantree
✗ import scantree as st; tree = st.scantree(...)
While 'import scantree as st' works, the common pattern is to import 'scantree' (the function) and 'RecursionFilter' directly for clarity, as shown in official examples.
RecursionFilter
✓ from scantree import RecursionFilter
This quickstart demonstrates how to use `scantree` to recursively find files matching a specific pattern (e.g., all '.txt' files) within a temporary directory structure. It also shows how to access properties like relative and absolute paths, and check if an entry is a symlink. The `RecursionFilter` is used to define matching rules.
import tempfile
import shutil
from pathlib import Path
from scantree import scantree, RecursionFilter
# Create a temporary directory structure for demonstration
temp_dir_path = Path(tempfile.mkdtemp())
try:
# Create subdirectories and files
(temp_dir_path / "dir1").mkdir()
(temp_dir_path / "dir2" / "sub_dir").mkdir(parents=True)
(temp_dir_path / "dir1" / "file1.txt").touch()
(temp_dir_path / "dir1" / "file2.log").touch()
(temp_dir_path / "dir2" / "sub_dir" / "file3.txt").touch()
(temp_dir_path / "root_file.txt").touch()
print(f"Created temporary directory: {temp_dir_path}")
# Scan the directory for all .txt files recursively
# The first argument to scantree is the root path to scan.
# RecursionFilter can specify match patterns, ignore patterns, etc.
tree = scantree(temp_dir_path, RecursionFilter(match=['*.txt']))
print("\nRelative paths of .txt files found:")
for path_obj in tree.filepaths():
print(path_obj.relative) # path.relative is relative to the scan root
# Access metadata of directory entries
print("\nExample: Accessing metadata for a directory entry")
if tree.directories:
first_dir_node = tree.directories[0]
print(f"First directory found (absolute path): {first_dir_node.path.absolute}")
print(f"Is symlink: {first_dir_node.path.is_symlink()}")
finally:
# Clean up the temporary directory
shutil.rmtree(temp_dir_path)
print(f"\nCleaned up temporary directory: {temp_dir_path}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'scantree'
The scantree package is not installed in the current Python environment.
TypeError: 'Tree' object is not iterable
The scantree.scantree function returns a Tree object, which is not directly iterable; you must use its walk() method or access attributes like files, dirs, or entries.
fixtree = scantree.scantree('.'); for entry in tree.walk(): print(entry.path) AttributeError: 'Entry' object has no attribute 'size'
The scantree.Entry object does not have direct attributes like 'size'; file properties are accessed through its stat() method.
fixfor entry in tree.walk(): if entry.is_file(): print(entry.stat().st_size)
FileNotFoundError: [Errno 2] No such file or directory: '/nonexistent/path'
The starting path provided to scantree.scantree does not exist on the file system.
fixEnsure the directory path passed to scantree.scantree is valid and accessible, for example: scantree.scantree('./my_existing_directory') ModuleNotFoundError: No module named 'scantree.Tree'
The Tree class is defined within the scantree module and should be imported directly from it, not as a submodule.
fixfrom scantree import Tree
Upgrade
Version history
0.0.4latest on PyPI · released Aug 3, 2024
Audit
Dependencies
attrsrequiredUsed for attribute handling and data structures.
pathspecrequiredLikely used for gitignore-style pattern matching in filters.