Directories — dir_*

All traversals share the fs filter set: all, recurse (bool or depth), type, glob/regexp (mutually exclusive), invert, fail.

pyrfs.dir_create

dir_create(path: str, *, mode: int | str = 493, recurse: bool = True) -> FsPath

Create a directory (parents too when recurse); existing dirs are fine.

Vectorized: also accepts an iterable or pandas Series of paths.

Parameters:

Name	Type	Description	Default
path	str or PathLike	The directory to create.	required
mode	int or str	Permissions for newly created directories (default 0o755); subject to the process umask.	493
recurse	bool	Create missing parents too (default True, matching fs — note this differs from the recurse=False default of the listing functions).	True

Returns:

Type	Description
FsPath	The created path (chains).

See Also

file_create : The file counterpart. FsPath.mkdir : Fluent equivalent.

Examples:

>>> dir_create("out/plots")
FsPath('out/plots')
>>> dir_exists("out/plots")
True

pyrfs.dir_exists

dir_exists(path: str) -> bool

Whether the path exists and is a directory (follows symlinks).

Vectorized: also accepts an iterable or pandas Series of paths.

See Also

pyrfs.is_dir : Entry-itself (lstat) semantics — a symlink to a directory answers False there but True here.

pyrfs.dir_ls

dir_ls(path: PathInput = '.', *, all: bool = False, recurse: bool | int = False, type: str | Iterable[str] = 'any', glob: str | None = None, regexp: str | None = None, invert: bool = False, fail: bool = True) -> list[FsPath]

List directory entries with the full fs filter set.

The eager form of dir_walk — same parameters, returns a sorted list.

Parameters:

Name	Type	Description	Default
path	str or PathLike	Directory to list (default: the working directory).	'.'
all	bool	Include hidden dotfiles.	False
recurse	bool or int	True = full recursion, False = this level only, an int limits depth (1 = one level below path).	False
type	str or iterable of str	Keep only these entry types ("file", "directory", "symlink", ...); "any" keeps all.	'any'
glob	str	Keep entries whose path matches (mutually exclusive).	None
regexp	str	Keep entries whose path matches (mutually exclusive).	None
invert	bool	Keep entries that do not match glob/regexp.	False
fail	bool	Raise on unreadable entries (True) or warn and skip (False).	True

Returns:

Type	Description
list of FsPath	Entry paths, prefixed by path, siblings sorted by name.

Raises:

Type	Description
FsValueError	If both glob and regexp are set, or type names an unknown entry type.

See Also

dir_walk : The lazy (generator) form. dir_info : The same listing as typed stat rows / DataFrame. pyrfs.path_filter : The same glob/regexp filter for in-memory lists.

Examples:

>>> from pyrfs import file_touch
>>> _ = dir_create("proj/sub")
>>> _ = file_touch(["proj/a.py", "proj/b.txt"])
>>> dir_ls("proj")
[FsPath('proj/a.py'), FsPath('proj/b.txt'), FsPath('proj/sub')]
>>> dir_ls("proj", glob="*.py")
[FsPath('proj/a.py')]
>>> dir_ls("proj", type="directory")
[FsPath('proj/sub')]

pyrfs.dir_walk

dir_walk(path: PathInput = '.', *, all: bool = False, recurse: bool | int = False, type: str | Iterable[str] = 'any', glob: str | None = None, regexp: str | None = None, invert: bool = False, fail: bool = True) -> Iterator[FsPath]

Lazily yield directory entries, with the full fs filter set.

Parameters:

Name	Type	Description	Default
path	str or PathLike	Directory to walk.	'.'
all	bool	Include hidden dotfiles.	False
recurse	bool or int	True = full recursion, False = this level only, an int limits depth (1 = one level below path).	False
type	str or iterable of str	Keep only these entry types ("file", "directory", "symlink", ...); "any" keeps all.	'any'
glob	str	Keep entries whose path matches (mutually exclusive).	None
regexp	str	Keep entries whose path matches (mutually exclusive).	None
invert	bool	Keep entries that do not match glob/regexp.	False
fail	bool	Raise on unreadable entries (True) or warn and skip (False).	True

Yields:

Type	Description
FsPath	Entry paths, prefixed by path, siblings sorted by name.

Raises:

Type	Description
FsValueError	If both glob and regexp are set, or type names an unknown entry type.

See Also

dir_ls : The eager (list-returning) form. dir_map : Apply a function to each entry.

Examples:

>>> from pyrfs import file_touch
>>> _ = dir_create("logs")
>>> _ = file_touch("logs/a.log")
>>> walker = dir_walk("logs")  # nothing read yet — it's a generator
>>> next(walker)
FsPath('logs/a.log')

pyrfs.dir_map

dir_map(path: PathInput, fn: Callable[[FsPath], object], *, all: bool = False, recurse: bool | int = False, type: str | Iterable[str] = 'any', glob: str | None = None, regexp: str | None = None, invert: bool = False, fail: bool = True) -> list[object]

Apply fn to each entry and collect the results.

Takes the same filter arguments as dir_ls.

See Also

dir_walk : Iterate lazily instead of collecting.

Examples:

>>> from pyrfs import file_touch
>>> _ = dir_create("d")
>>> _ = file_touch(["d/a.py", "d/b.py"])
>>> dir_map("d", lambda p: p.ext())
['py', 'py']

pyrfs.dir_copy

dir_copy(path: str, new_path: PathInput, *, overwrite: bool = False) -> FsPath

Copy a directory tree to new_path (a name, or an existing directory).

Same destination resolution and overwrite guard as file_copy: copying into an existing directory targets new_path/basename (shell cp -r semantics). With overwrite=True an existing destination is replaced, not merged. Symlinks are copied as symlinks.

Parameters:

Name	Type	Description	Default
path	str or PathLike	Source directory.	required
new_path	str or PathLike	Destination name, or an existing directory to copy into.	required
overwrite	bool	Replace an existing (resolved) destination (default False).	False

Returns:

Type	Description
FsPath	The root of the new copy.

Raises:

Type	Description
NotADirectoryError	If path is not a directory.
FileExistsError	If the (resolved) destination exists and overwrite is False.

See Also

file_copy : Single files. file_move : Directories move via file_move (there is no dir_move).

Examples:

>>> _ = dir_create("src/sub")
>>> dir_copy("src", "backup")
FsPath('backup')
>>> dir_exists("backup/sub")
True

pyrfs.dir_delete

dir_delete(path: str) -> FsPath

Delete a directory and everything below it (recursive, like rm -rf).

Vectorized: also accepts an iterable or pandas Series of paths.

Returns:

Type	Description
FsPath	The deleted path.

See Also

file_delete : Single files and symlinks. FsPath.rmdir : Fluent equivalent.

Examples:

>>> _ = dir_create("scratch/deep")
>>> dir_delete("scratch")
FsPath('scratch')
>>> dir_exists("scratch")
False

pyrfs.dir_tree

dir_tree(path: PathInput = '.', *, recurse: bool | int = True, all: bool = False) -> None

Print a box-drawing tree of the directory, like the Unix tree.

Entries are coloured by type via LS_COLORS in a capable terminal (plain on non-TTY or NO_COLOR). Hidden files are skipped unless all=True; recurse limits depth as in dir_ls.

Examples:

>>> from pyrfs import file_touch
>>> _ = dir_create("proj/src")
>>> _ = file_touch("proj/README.md")
>>> dir_tree("proj")
proj
├── README.md
└── src