{"id":2274,"library":"scantree","title":"Flexible recursive directory iterator","description":"scantree (version 0.0.4) is a Python library that provides a flexible recursive directory iterator, combining the efficiency of `os.scandir` with the wildcard matching capabilities of `glob.glob(\"**\", recursive=True)`. It offers an in-memory representation of the file-tree, efficient access to `os.DirEntry` properties, and includes features like detection and handling of cyclic symlinks. The library is actively maintained with an infrequent release cadence.","status":"active","version":"0.0.4","language":"en","source_language":"en","source_url":"https://github.com/andhus/scantree","tags":["file system","directory traversal","recursive","glob","scandir","utility","pathlib"],"install":[{"cmd":"pip install scantree","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for attribute handling and data structures.","package":"attrs","optional":false},{"reason":"Likely used for gitignore-style pattern matching in filters.","package":"pathspec","optional":false}],"imports":[{"note":"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.","wrong":"import scantree as st; tree = st.scantree(...)","symbol":"scantree","correct":"from scantree import scantree"},{"symbol":"RecursionFilter","correct":"from scantree import RecursionFilter"}],"quickstart":{"code":"import tempfile\nimport shutil\nfrom pathlib import Path\nfrom scantree import scantree, RecursionFilter\n\n# Create a temporary directory structure for demonstration\ntemp_dir_path = Path(tempfile.mkdtemp())\ntry:\n    # Create subdirectories and files\n    (temp_dir_path / \"dir1\").mkdir()\n    (temp_dir_path / \"dir2\" / \"sub_dir\").mkdir(parents=True)\n\n    (temp_dir_path / \"dir1\" / \"file1.txt\").touch()\n    (temp_dir_path / \"dir1\" / \"file2.log\").touch()\n    (temp_dir_path / \"dir2\" / \"sub_dir\" / \"file3.txt\").touch()\n    (temp_dir_path / \"root_file.txt\").touch()\n\n    print(f\"Created temporary directory: {temp_dir_path}\")\n\n    # Scan the directory for all .txt files recursively\n    # The first argument to scantree is the root path to scan.\n    # RecursionFilter can specify match patterns, ignore patterns, etc.\n    tree = scantree(temp_dir_path, RecursionFilter(match=['*.txt']))\n\n    print(\"\\nRelative paths of .txt files found:\")\n    for path_obj in tree.filepaths():\n        print(path_obj.relative) # path.relative is relative to the scan root\n\n    # Access metadata of directory entries\n    print(\"\\nExample: Accessing metadata for a directory entry\")\n    if tree.directories:\n        first_dir_node = tree.directories[0]\n        print(f\"First directory found (absolute path): {first_dir_node.path.absolute}\")\n        print(f\"Is symlink: {first_dir_node.path.is_symlink()}\")\n\nfinally:\n    # Clean up the temporary directory\n    shutil.rmtree(temp_dir_path)\n    print(f\"\\nCleaned up temporary directory: {temp_dir_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python environment to 3.8 or newer. Revert to `scantree` version <0.0.2 if Python 2 is strictly required (not recommended).","message":"Support for Python 2 was dropped in `scantree` version 0.0.2. Users on Python 2.x environments must upgrade to Python 3.8+ to use current versions of the library.","severity":"breaking","affected_versions":"<0.0.2"},{"fix":"Ensure you are on `scantree` version 0.0.4 or newer. If issues persist with cyclic symlinks on Windows, manual handling or alternative directory traversal logic might be required for those specific paths.","message":"While `scantree` aims for Windows compatibility (with fixes in v0.0.4), known limitations exist, particularly concerning cyclic symlinks. Users heavily relying on complex symlink structures on Windows might encounter unexpected behavior.","severity":"gotcha","affected_versions":"<0.0.4"},{"fix":"Always be mindful of the root path passed to `scantree()`. If you need paths relative to the current working directory, pass `Path.cwd()` as the root, or use `path.absolute` and then process it as needed.","message":"The `path.relative` property of `DirEntry` objects returned by `scantree` is relative to the *root path provided to the `scantree` function*, not necessarily the current working directory. Be explicit with your scan root to avoid confusion, especially when moving or combining paths.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}