API Reference

Auto-generated from docstrings via mkdocstrings.

Modern API

rglob.rglob.find(base, patterns='*', *, exclude=(), max_depth=None, hidden=False, follow_symlinks=False, case_sensitive=None, sort=True, on_error='warn', kinds=(), min_size=None, max_size=None, newer_than=None, older_than=None, newer_than_file=None, perm=None, uid=None, gid=None, respect_gitignore=False)

Recursively yield filesystem entries matching patterns under base.

Parameters:

Name	Type	Description	Default
base	str | PathLike[str]	Root directory to walk.	required
patterns	str | Sequence[str]	Glob pattern or sequence of patterns. "*" (the default) matches everything. Patterns without separators match against entry basenames; patterns with / or ** match against the relative path from base. ** matches any number of path components, including zero.	'*'
exclude	str | Sequence[str]	Pattern or patterns to exclude. Same syntax as patterns; matching entries are skipped and not descended into (i.e. pruning behaviour for directories).	()
max_depth	int | None	Maximum recursion depth. None means unbounded; 0 limits to direct children of base.	None
hidden	bool	When False (default), entries whose name starts with "." are skipped (no descent into hidden directories).	False
follow_symlinks	bool	When False (default), symbolic links to directories are not descended into. When True, symlink cycles are terminated by a per-call realpath memo.	False
case_sensitive	bool | None	Force case-sensitive (True) or case-insensitive (False) matching. None (default) follows the host OS (case-sensitive on Linux, case-insensitive on macOS/Windows).	None
sort	bool	When True (default), entries within each directory are yielded in sorted order, giving a deterministic depth-first traversal. Set False for raw scandir order — this is the performance mode when stable ordering isn't required; it skips a per-directory sort that costs ~5-10% on large trees and makes the walker proportionally lighter for agent/CLI consumers that pipe results through their own sorter (or don't care about order at all, like --null and --jsonl consumers).	True
on_error	OnError	How to handle OSError / PermissionError while walking. "warn" (default) emits a :class:RuntimeWarning; "ignore" swallows the error; "raise" re-raises.	'warn'
kinds	Iterable[Kind]	Iterable of "f" (regular file), "d" (directory), "l" (symlink), "x" (executable). Empty (default) means "all kinds".	()
min_size	int | float | str | None	Minimum file size as bytes (int/float) or string ("1K", "5MiB", "100 MB"). Directories and symlinks bypass this filter.	None
max_size	int | float | str | None	Maximum file size — same format as min_size.	None
newer_than	datetime | timedelta | str | None	Only yield entries with mtime strictly after this timestamp. Accepts :class:datetime, :class:timedelta (interpreted as "now minus delta"), an ISO date string, or a relative duration like "7d" / "3h" / "2w".	None
older_than	datetime | timedelta | str | None	Only yield entries with mtime strictly before this timestamp — same format as newer_than.	None
newer_than_file	str | PathLike[str] | None	Only yield entries with mtime strictly after this file's mtime.	None
perm	int | str | None	POSIX permission filter. Plain values require exact mode, -MODE requires all bits, and /MODE requires any bit.	None
uid	int | None	POSIX owner uid filter.	None
gid	int | None	POSIX owner gid filter.	None
respect_gitignore	bool	When True, skip files that any .gitignore under base would ignore. Requires the optional pathspec dependency (pip install rglob[gitignore]); silently no-ops if not installed.	False

Yields:

Type	Description
Path	class:pathlib.Path instances for each match, in deterministic
Path	order when sort=True.

Examples:

>>> from rglob import find
>>> list(find("/tmp", "*.txt"))
>>> list(find("/tmp", ["*.py", "*.pyx"]))
>>> list(find(".", "**/test_*.py"))

rglob.rglob.find_all(base, patterns='*', **kwargs)

Eager variant of :func:find — returns list[Path].

Legacy API (still supported)

rglob.rglob.rglob(base, pattern)

Recursively glob entries under base matching pattern.

Breaking change in 2.0: now returns list[Path] (was list[str] in 1.x). See the migration guide and ADR-0003 for context. To restore the old behaviour locally:

paths = [str(p) for p in rglob(base, pattern)]

rglob.rglob.rglob_(pattern)

Recursively glob entries under the current working directory.

rglob.rglob.lcount(base, pattern, func=lambda _line: True)

Count lines across files matching pattern under base.

Parameters:

Name	Type	Description	Default
base	str | PathLike[str]	root directory to walk.	required
pattern	str	glob pattern (e.g. "*.py").	required
func	Callable[[str], bool]	per-line predicate; only lines for which it returns truthy are counted. Defaults to "count every line".	lambda _line: True

Returns:

Type	Description
int	Integer total line count.

rglob.rglob.tsize(base, pattern, func=megabytes)

Sum the total size of files matching pattern under base.

Parameters:

Name	Type	Description	Default
base	str | PathLike[str]	root directory to walk.	required
pattern	str	glob pattern (e.g. "*.jpg").	required
func	Callable[[float], float]	unit-conversion function from bytes to the desired unit. Defaults to :func:megabytes.	megabytes

Returns:

Type	Description
float	The total size converted by func (a float).

Unit helpers

rglob.rglob.kilobytes(value)

Convert bytes to kibibytes (KiB).

rglob.rglob.megabytes(value)

Convert bytes to mebibytes (MiB).

rglob.rglob.gigabytes(value)

Convert bytes to gibibytes (GiB).

rglob.rglob.terabytes(value)

Convert bytes to tebibytes (TiB).

Path return at 2.0

As of 2.0, rglob() / rglob_() return list[Path] (previously list[str]). See migrating to 2.0 for the one-line migration. The new find() / find_all() family already returns Path so code targeting the modern API doesn't need to change.