iterdir

iterdir is a method of the pathlib.Path class in Python that returns an iterator over the entries contained in a directory. Each item yielded by the iterator is a Path object representing a file, subdirectory, or symbolic link within the directory. The method is non-recursive, meaning it only lists the immediate contents of the specified directory.

The iterator is lazy and typically backed by an efficient system call, often using the operating system’s directory scanning facilities. Because it yields Path objects rather than strings, you can immediately apply Path methods to each entry, such as is_file(), is_dir(), or resolve(). The order of entries is not guaranteed and may vary between systems and runs.

Common considerations include potential exceptions: a FileNotFoundError occurs if the path does not exist, a NotADirectoryError if the path points to a non-directory, and a PermissionError if access is denied. Other OS-related errors may raise OSError. In normal use, you should handle or let these exceptions propagate according to your program’s error handling strategy.

Typical usage is straightforward: for child in Path("/path/to/dir").iterdir(): print(child) or filter with conditions such as if child.is_file():. For recursive listing, other pathlib features like glob or rglob can be used. Compared to os.listdir, itdir returns Path objects and integrates more naturally with other pathlib operations, while os.scandir offers similar performance with DirEntry objects.

See also: Path.glob, Path.rglob, and the pathlib module.