Iterate through a file tree
Project description
iterpath lets you iterate over a file tree as a single iterator of pathlib.Path objects, eliminating the need to combine lists returned by os.walk() or recursively call Path.iterdir() or os.scandir(). Besides the standard os.walk() options, the library also includes options for sorting & filtering entries.
Installation
iterpath requires Python 3.6 or higher. Just use pip for Python 3 (You have pip, right?) to install it:
python3 -m pip install iterpath
Example
Iterate over this library’s source repository, skipping the .git and test/data folders:
>>> import os.path >>> from iterpath import iterpath >>> def filterer(dir_entry): ... if dir_entry.name == ".git": ... return False ... elif dir_entry.path == os.path.join(".", "test", "data"): ... return False ... else: ... return True ... >>> for p in iterpath(".", sort=True, filter_dirs=filterer): ... print(p) ... .github .github/workflows .github/workflows/test.yml .gitignore LICENSE MANIFEST.in README.rst TODO.md pyproject.toml setup.cfg src src/iterpath src/iterpath/__init__.py src/iterpath/__pycache__ src/iterpath/__pycache__/__init__.cpython-39.pyc src/iterpath/py.typed test test/test_iterpath.py tox.ini
API
The iterpath module provides a single function, also named iterpath:
iterpath(dirpath: Union[AnyStr, os.PathLike[AnyStr]], **kwargs) -> Iterator[pathlib.Path]
Iterate through the file tree rooted at the directory dirpath in depth-first order, yielding the files & directories within. If dirpath is an absolute path, the generated Path objects will be absolute; otherwise, if dirpath is a relative path, the Path objects will be relative and will have dirpath as a prefix.
Note that, although iterpath() yields pathlib.Path objects, it operates internally on os.DirEntry objects, and so any function supplied as the sort_key parameter or as a filter/exclude parameter must accept os.DirEntry instances.
Keyword arguments:
- dirs: bool = True
Whether to include directories in the output
- topdown: bool = True
Whether to yield each directory before (True) or after (False) its contents
- include_root: bool = False
Whether to include the dirpath argument passed to iterpath() in the output
- followlinks: bool = False
Whether to treat a symlink to a directory as a directory
- onerror: Optional[Callable[[OSError], Any]] = None
Specify a function to be called whenever an OSError is encountered while iterating over a directory. If the function reraises the exception, iterpath() aborts; otherwise, it continues with the next directory. By default, OSError exceptions are ignored.
- sort: bool = False
Sort the entries in each directory. When False, entries are yielded in the order returned by os.scandir(). When True, entries are sorted, by default, by filename in ascending order, but this can be changed via the sort_key and sort_reverse arguments.
- sort_key: Optional[Callable[[os.DirEntry[AnyStr]], _typeshed.SupportsLessThan]] = None
Specify a custom key function for sorting directory entries. Only has an effect when sort is True.
- sort_reverse: bool = False
Sort directory entries in reverse order. Only has an effect when sort is True.
- filter_dirs: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None
Specify a predicate to be applied to all directories encountered; only those for which the predicate returns a true value will be yielded & descended into
- filter_files: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None
Specify a predicate to be applied to all files encountered; only those for which the predicate returns a true value will be yielded
- exclude_dirs: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None
Specify a predicate to be applied to all directories encountered; only those for which the predicate returns a false value will be yielded & descended into
- exclude_files: Optional[Callable[[os.DirEntry[AnyStr]], Any]] = None
Specify a predicate to be applied to all files encountered; only those for which the predicate returns a false value will be yielded
Warnings:
If dirpath is a relative path, changing the working directory while iterpath() is in progress will lead to errors, or at least inaccurate results.
Setting followlinks to True can result in infinite recursion if a symlink points to a parent directory of itself.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.