searchpath¶
searchpath finds files across prioritized directories and tracks where each match comes from. Use it for config cascades (project overrides user overrides system), plugin discovery, or any scenario where files might exist in more than one location and you need to know which one you found.
Alpha software
This project is in early development. APIs may change without notice. Not yet recommended for production use.
Installation¶
Requires Python 3.10 or later. See Installation for package manager options and optional dependencies.
Quick example¶
# demo
import searchpath
from pathlib import Path
# Find first config file, checking project dir before user dir
config = searchpath.first("config.toml", project_dir, user_dir)
# Find with provenance (which directory did it come from?)
match = searchpath.match("*.toml", ("project", project_dir), ("user", user_dir))
if match:
print(f"Found {match.relative} in {match.scope} scope")
# Output: Found config.toml in project scope
# Find all Python files, excluding tests
files = searchpath.all("**/*.py", src_dir, exclude=["test_*", "*_test.py"])
The key insight: when you need to search several directories in priority order, you also need to know which directory each result came from. searchpath gives you both.
Use cases¶
searchpath provides the foundation for any code that searches directories in priority order:
Config cascades
Project-level config overrides user-level, which overrides system defaults. searchpath finds the first match and tells you which level it came from.
Plugin discovery
Find plugins across app directories, user plugins, and shared plugins. Deduplicate by filename so user plugins can override built-ins.
Theme loading
Search for templates in a custom theme directory first, falling back to the default theme. Know which theme provided each template.
Asset resolution
Resolve assets from project directories before falling back to shared resources. Track provenance for caching and debugging.
Build systems
Discover source files across several roots with flexible include/exclude patterns. Filter by gitignore-style rules.
Developer tools
Linters, formatters, and code generators that target specific file types. Find files matching patterns while respecting project ignore rules.
Multi-tenant systems
Tenant-specific files override defaults. Track which tenant level each file comes from for auditing.
When to use something else¶
searchpath is designed for ordered multi-directory searches with provenance tracking. For other use cases, consider:
| If you want to | Use instead |
|---|---|
| Search a single directory tree | pathlib.Path.rglob() |
| Search file contents | ripgrep, grep |
| Watch for changes | watchfiles |
searchpath shines when you need to search directories in priority order and know which directory each result came from.
Next steps¶
Ready to start using searchpath? Choose your path based on how you learn best.
-
Tutorials
Learn searchpath step by step with hands-on lessons that teach the fundamentals.
-
How-to guides
Follow practical recipes that show how to achieve specific goals with searchpath.
-
Reference
Look up technical details about the API, including classes, functions, and configuration.
-
Explanation
Understand the concepts, architecture, and design decisions behind searchpath.