Skip to content

File Operations

The rite.filesystem.file submodule exposes helpers for reading, writing, copying, moving, and deleting files.

File-level helpers for the filesystem package.

Functions

copy_file(source_path: Path, destination_path: Path, overwrite: bool = True) -> None

Copy a file from source to destination.

Args

source_path: Source file path. destination_path: Destination file path. overwrite: Whether to overwrite the destination if it exists.

Raises

FileNotFoundError If the source file does not exist. FileExistsError If the destination file exists and overwrite is False.

copy_files(source_dir: Path, target_dir: Path, recursive: bool = False, overwrite: bool = True, preserve_metadata: bool = True) -> None

Copy files from source directory to target directory.

source_dir: Path to the source directory.
target_dir: Path to the destination directory.
recursive: If True, copy all files recursively from subdirectories.
overwrite: If True, overwrite files if they already exist.
preserve_metadata: If True, preserve file metadata using copy2.

FileNotFoundError: If the source directory does not exist.

create_spooled_temporary_file(filepath: str | Path | None = None, fileobj: IO[bytes] | None = None) -> tempfile.SpooledTemporaryFile

Create a spooled temporary file optionally seeded from a path or file.

If filepath or fileobj is provided, the content is copied into the new spooled file. Callers own the returned file object's lifecycle and should close it when finished.

filepath: Optional path to a file to copy into the spooled file.
fileobj: Optional file-like object to copy into the spooled file.

A spooled temporary file with the content copied if provided.

delete_file(directory_path: str, file_name: str) -> None

Delete a file within the specified directory.

directory_path: The path to the directory containing the file.
file_name: The name of the file to delete.

FileNotFoundError: If the file does not exist.
OSError: If the file could not be deleted due to an OS error.

move_file(directory_path: str, file_name: str, new_directory: str) -> None

Move a file from the current directory to a specified new directory.

directory_path: The path of the current directory.
file_name: The name of the file to be moved.
new_directory: The destination directory.

FileNotFoundError: If the file to move does not exist.
OSError: If the file could not be moved.
Note:
If the destination directory doesn't exist, it will be created.

rename_file(directory_path: str, old_file_name: str, new_file_name: str) -> None

Rename a file within the specified directory.

directory_path: The path to the directory containing the file.
old_file_name: The current name of the file.
new_file_name: The new name for the file.

FileNotFoundError: If the file to rename does not exist.
OSError: If the rename operation fails.

Modules

file_copy

File Copy Module

Provides utilities for copying files.

Functions

copy_file(source_path: Path, destination_path: Path, overwrite: bool = True) -> None

Copy a file from source to destination.

Args

source_path: Source file path. destination_path: Destination file path. overwrite: Whether to overwrite the destination if it exists.

Raises

FileNotFoundError If the source file does not exist. FileExistsError If the destination file exists and overwrite is False.

file_copy_multiple

Multiple File Copy Module

Provides utilities for copying multiple files or entire directories.

Functions

copy_files(source_dir: Path, target_dir: Path, recursive: bool = False, overwrite: bool = True, preserve_metadata: bool = True) -> None

Copy files from source directory to target directory.

source_dir: Path to the source directory.
target_dir: Path to the destination directory.
recursive: If True, copy all files recursively from subdirectories.
overwrite: If True, overwrite files if they already exist.
preserve_metadata: If True, preserve file metadata using copy2.

FileNotFoundError: If the source directory does not exist.

file_delete

File Deletion Module

Provides utilities for deleting files safely.

Functions

delete_file(directory_path: str, file_name: str) -> None

Delete a file within the specified directory.

directory_path: The path to the directory containing the file.
file_name: The name of the file to delete.

FileNotFoundError: If the file does not exist.
OSError: If the file could not be deleted due to an OS error.

file_move

File Move Module

Provides utilities for moving files between directories.

Functions

move_file(directory_path: str, file_name: str, new_directory: str) -> None

Move a file from the current directory to a specified new directory.

directory_path: The path of the current directory.
file_name: The name of the file to be moved.
new_directory: The destination directory.

FileNotFoundError: If the file to move does not exist.
OSError: If the file could not be moved.
Note:
If the destination directory doesn't exist, it will be created.

file_read_bytes

File Read Bytes

Read a file and return its contents as bytes.

Functions

file_read_bytes(path: str | Path) -> bytes

Read a file and return its contents as bytes.

Args
path: File path.
Returns
bytes: File content.

file_read_text

File Read Text

Read a file and return its contents as text.

Functions

file_read_text(path: str | Path, encoding: str = 'utf-8') -> str

Read a file and return its contents as text.

Args
path: File path.
encoding: Text encoding to use.
Returns
str: File content.

file_rename

File Rename Module

Provides utilities for renaming files within directories.

Functions

rename_file(directory_path: str, old_file_name: str, new_file_name: str) -> None

Rename a file within the specified directory.

directory_path: The path to the directory containing the file.
old_file_name: The current name of the file.
new_file_name: The new name for the file.

FileNotFoundError: If the file to rename does not exist.
OSError: If the rename operation fails.

file_size_to_string

File Size to String Converter Module

Provides functionality to convert file sizes to human-readable strings.

Functions

file_size_to_string(filehandle: BinaryIO | _SizedStream) -> str

Return the size of a file in a human-readable string.

Attempts to use filehandle.size if available (e.g. Django's UploadedFile), otherwise seeks to the end to determine size.

filehandle: A file-like object.

str: A string representing the file size, e.g., '2.4 MB', '1 KB'.

file_spooled

Spooled Temporary File Creation Module

Provides utilities for creating spooled temporary files.

Functions

create_spooled_temporary_file(filepath: str | Path | None = None, fileobj: IO[bytes] | None = None) -> tempfile.SpooledTemporaryFile

Create a spooled temporary file optionally seeded from a path or file.

If filepath or fileobj is provided, the content is copied into the new spooled file. Callers own the returned file object's lifecycle and should close it when finished.

filepath: Optional path to a file to copy into the spooled file.
fileobj: Optional file-like object to copy into the spooled file.

A spooled temporary file with the content copied if provided.

file_spooled_settings

Spooled File Settings Module

Configuration settings for spooled temporary file operations.

Classes

SpooledFileSettings

Configuration for spooled temporary file operations.

file_write_bytes

File Write Bytes

Write bytes to a file, creating parent directories if needed.

Functions

file_write_bytes(path: str | Path, data: bytes) -> None

Write bytes to a file, creating parent directories if needed.

Args
path: File path.
data: Bytes content to write.

file_write_text

File Write Text

Write text to a file, creating parent directories if needed.

Functions

file_write_text(path: str | Path, text: str, encoding: str = 'utf-8') -> None

Write text to a file, creating parent directories if needed.

Args
path: File path.
text: Text content to write.
encoding: Text encoding to use.

options: show_root_heading: true show_source: false heading_level: 2