Представляем dirstree: переиспользуемые правила выбора файлов проекта.

Линтерам, тестовым инструментам и анализаторам кода сначала нужно пройти по директории проекта и решить, какие файлы обрабатывать. Например, выбрать только Python-файлы, но пропустить виртуальные окружения, сгенерированные результаты и служебные данные Git. Если каждый компонент задаёт эти правила отдельно, разные части одной системы могут случайно обработать разные наборы файлов.

os.walk() и Path.rglob() выполняют обход, а PathSpec обрабатывает шаблоны исключений. Вызывающему коду всё равно приходится объединять их с проверками расширений и оформлять правила для повторного использования.

dirstree — небольшая Python-библиотека, которая хранит правила выбора файлов в одном переиспользуемом объекте. Она возвращает подходящие объекты pathlib.Path по одному и фильтрует их по расширениям и шаблонам, похожим на правила .gitignore. Релиз доступен на GitHub.

Что делает dirstree🔗

Передайте DirectoryWalker корень в виде строки или Path, при необходимости ограничьте расширения файлов, добавьте исключения в знакомом синтаксисе .gitignore — и перебирайте отобранные файлы.

Например, этот обходчик возвращает Python-файлы, исключая метаданные Git и виртуальное окружение:

from dirstree import DirectoryWalker

walker = DirectoryWalker(
    ".",
    extensions=[".py"],
    exclude_patterns=[".git", "venv"],
)

for path in walker.walk():
    print(path)

dirstree обходит один корень и возвращает файлы. Он принимает gitignore-подобные шаблоны, но не читает .gitignore, не воспроизводит все правила приоритетов Git и не пропускает обход исключённой директории.

Сравнение с более широкими файловыми инструментами🔗

WalkDir добавляет ограничение глубины и фильтры директорий, PyFilesystem2 поддерживает абстрактные файловые системы, а wcmatch — более богатые шаблоны.

dirstree предназначен для меньшего сценария: локальных деревьев исходников, объектов Path от входа до выхода и одного места для декларации правил отбора. Он не заявляет превосходство в скорости над стандартной библиотекой и не является универсальным файловым фреймворком.

Для кого предназначен dirstree🔗

dirstree предназначен для линтеров, анализаторов, инструментов преобразования кода, систем тестирования и сборочных помощников, которым регулярно нужен определённый набор файлов. В более крупной системе он может формировать список работ для другого компонента.