Files — file_*

Mutating verbs return the (new) path so calls chain; overwrite=False on an existing target raises FileExistsError. Copy/move into an existing directory targets dir/basename.

pyrfs.file_create

file_create(path: str, *, mode: int | str = 420) -> FsPath

Create a new file (an existing file is left unchanged).

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

Parameters:

Name	Type	Description	Default
path	str or PathLike	The file to create. The parent directory must exist.	required
mode	int or str	Permissions for a newly created file — octal string ("644"), symbolic ("u=rw,go=r"), or raw bits (default 0o644); subject to the process umask.	420

Returns:

Type	Description
FsPath	The created path (chains).

See Also

file_touch : Also update timestamps when the file exists. pyrfs.dir_create : The directory counterpart.

Examples:

>>> file_create("notes.txt")
FsPath('notes.txt')

pyrfs.file_touch

file_touch(path: str) -> FsPath

Update access/modification times, creating the file if needed.

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

See Also

file_create : Create without updating timestamps of an existing file.

Examples:

>>> file_touch("stamp.txt")
FsPath('stamp.txt')

pyrfs.file_copy

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

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

Vectorized: copy many files into one directory with file_copy([a, b], "dir").

Parameters:

Name	Type	Description	Default
path	str or PathLike	Source file.	required
new_path	str or PathLike	Destination file name, or an existing directory to copy into (the target then becomes new_path/basename).	required
overwrite	bool	Allow clobbering an existing destination (default False).	False

Returns:

Type	Description
FsPath	The path of the new copy.

Raises:

Type	Description
FileExistsError	If the (resolved) destination exists and overwrite is False.

See Also

file_move : Move instead of copy. pyrfs.dir_copy : Copy a directory tree. FsPath.copy_to : Fluent equivalent.

Examples:

>>> src = file_create("a.txt")
>>> file_copy(src, "b.txt")
FsPath('b.txt')
>>> file_copy(src, "b.txt")
Traceback (most recent call last):
    ...
FileExistsError: target already exists: FsPath('b.txt') (pass overwrite=True)

pyrfs.file_move

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

Move (rename) a file — or a directory: dirs move via file_move.

Same destination resolution and overwrite guard as file_copy. There is deliberately no dir_move, matching fs.

Parameters:

Name	Type	Description	Default
path	str or PathLike	Source file or directory.	required
new_path	str or PathLike	Destination name, or an existing directory to move into.	required
overwrite	bool	Allow clobbering an existing destination (default False).	False

Returns:

Type	Description
FsPath	The new location.

Raises:

Type	Description
FileExistsError	If the (resolved) destination exists and overwrite is False.

See Also

file_copy : Copy instead of move. FsPath.move_to : Fluent equivalent.

Examples:

>>> _ = file_create("a.txt")
>>> file_move("a.txt", "b.txt")
FsPath('b.txt')

pyrfs.file_delete

file_delete(path: str) -> FsPath

Delete a file or symlink (for directories use dir_delete).

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

Returns:

Type	Description
FsPath	The deleted path.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.

See Also

pyrfs.dir_delete : Recursive directory deletion. pyrfs.link_delete : Symlink-only deletion (refuses non-links).

Examples:

>>> p = file_create("scrap.txt")
>>> file_delete(p)
FsPath('scrap.txt')
>>> file_exists(p)
False

pyrfs.file_exists

file_exists(path: str) -> bool

Whether the path exists — a broken symlink counts as existing.

Uses lexists (the entry itself), matching fs. Vectorized: also accepts an iterable or pandas Series of paths.

See Also

pyrfs.dir_exists : Directory-specific test (follows symlinks). pyrfs.is_file, pyrfs.is_dir, pyrfs.is_link : Type predicates.

Examples:

>>> _ = file_create("here.txt")
>>> file_exists(["here.txt", "gone.txt"])
[True, False]

pyrfs.file_access

file_access(path: str, mode: str = 'exists') -> bool

Test access to a path for the current process.

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

Parameters:

Name	Type	Description	Default
path	str or PathLike	The path to test.	required
mode	('exists', 'read', 'write', 'execute')	The kind of access to check.	"exists"

Raises:

Type	Description
FsValueError	If mode is not one of the four accepted values.

Examples:

>>> p = file_create("data.txt")
>>> file_access(p, "read")
True

pyrfs.file_size

file_size(path: str) -> Bytes

File size as a pyrfs.Bytes value (compares against literals).

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

Returns:

Type	Description
Bytes	The size — an int subclass that displays humanized (444.5K) and compares against strings like "10KB".

See Also

pyrfs.Bytes : The typed scalar. file_info : Size together with the full stat row.

Examples:

>>> p = file_create("two-bytes.bin")
>>> with open(p, "wb") as fh:
...     _ = fh.write(b"hi")
>>> file_size(p)
Bytes(2)
>>> file_size(p) < "1KB"
True

pyrfs.file_chmod

file_chmod(path: str, mode: int | str) -> FsPath

Change permissions; symbolic modes apply relative to the current mode.

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

Parameters:

Name	Type	Description	Default
path	str or PathLike	The file to change.	required
mode	int or str	Octal string ("644"), display form ("rw-r--r--"), or raw bits — all absolute; symbolic clauses ("u+x") modify the current mode, like the chmod command.	required

See Also

pyrfs.Perms : The typed permission scalar. FsPath.chmod : Fluent equivalent.

Examples:

>>> p = file_create("run.sh", mode="644")
>>> _ = file_chmod(p, "u+x")
>>> file_access(p, "execute")
True

pyrfs.file_chown

file_chown(path: str, user: str | int | None = None, group: str | int | None = None) -> FsPath

Change owner and/or group (names or numeric ids; POSIX only).

Parameters:

Name	Type	Description	Default
path	str or PathLike	The file to change.	required
user	str or int	New owner (name or uid).	None
group	str or int	New group (name or gid).	None

Raises:

Type	Description
FsValueError	If neither user nor group is given.

pyrfs.file_show

file_show(path: str) -> FsPath

Open a file in the OS default application (open/xdg-open).

Examples:

>>> file_show("report.pdf")
FsPath('report.pdf')