Filesystem Module¶
The rite.filesystem module provides file and directory operations, path management, and compression utilities.
Overview¶
filesystem ¶
Filesystem Module¶
Provides core filesystem operations for paths, files, folders, and extensions.
Canonical functions are organized by domain:
- Path: path_clean, path_exists, path_is_dir, path_is_file, path_leaf, path_safe_join, path_secure
- File: file_read_bytes, file_read_text, file_write_bytes, file_write_text, copy_file, copy_files, delete_file, move_file, rename_file, file_size_to_string, create_spooled_temporary_file
- Folder: folder_ensure_exists, folder_list_files, folder_size_to_string
- Extension: extension_normalize, extension_validate, EXTENSION_REGEX
- Compress: compress_file, uncompress_file
All public symbols follow a consistent domain-prefixed naming convention.
Legacy symbols are available in the deprecated module for backwards compatibility.
Example
from rite.filesystem import path_leaf, file_read_text path_leaf("/path/to/file.txt") 'file.txt' text = file_read_text("docs/readme.md")
Functions¶
compress_file ¶
Compress a file using gzip and return the compressed output.
input_file: File-like object to compress.
filename: Original filename (used as internal gzip metadata).
Tuple of (compressed file object, new filename with .gz extension).
copy_file ¶
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 ¶
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 ¶
create_spooled_temporary_file(filepath: str | Path | None = None, fileobj: object | 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 ¶
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.
extension_normalize ¶
Normalize a file extension.
Strips whitespace and leading dots, converts to lowercase.
extension: Extension string (e.g. ".JPG", " pdf ", "tar.gz").
leading_dot: If True, return with a leading ".".
str | None: Normalized extension, or None if empty/None.
Example:¶
>>> extension_normalize(".JPG")
'jpg'
>>> extension_normalize(" PDF ", leading_dot=True)
'.pdf'
>>> extension_normalize(" ")
None
extension_validate ¶
extension_validate(extension: str | None, *, allowed: Iterable[str] | None = None, regex: Pattern[str] = EXTENSION_REGEX) -> None
Validate a file extension.
extension: Extension string to validate (should be normalized).
allowed: Optional iterable of allowed extensions (case-insensitive).
regex: Pattern to match valid extensions.
ValueError: If extension is None/empty, doesn't match regex, or not allowed.
Example:¶
>>> extension_validate("pdf")
>>> extension_validate("jpg", allowed=["png", "jpg", "gif"])
>>> extension_validate("exe", allowed=["png", "jpg"])
Traceback (most recent call last):
ValueError: Extension 'exe' not allowed...
file_read_bytes ¶
file_read_text ¶
file_size_to_string ¶
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_write_bytes ¶
Write bytes to a file, creating parent directories if needed.
Args¶
path: File path.
data: Bytes content to write.
file_write_text ¶
Write text to a file, creating parent directories if needed.
Args¶
path: File path.
text: Text content to write.
encoding: Text encoding to use.
folder_ensure_exists ¶
Ensure that path exists as a directory, creating parents as needed.
folder_list_files ¶
folder_size_to_string ¶
Return the total size of a folder as a human-readable string.
This walks the folder, summing file sizes using Path.stat and then
formatting the aggregate size via :func:file_size_to_string.
Args¶
path: Folder path.
recursive: If ``True``, walk subfolders recursively.
Returns¶
str: Human-readable size such as ``"12.3 MB"``.
move_file ¶
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.
path_clean ¶
Clean a path by normalizing slashes.
Ensures path has exactly one leading slash and no trailing slash.
path: Path string to clean.
str: Cleaned path with single leading slash.
Example:¶
>>> path_clean("//path/to/file//")
'/path/to/file'
>>> path_clean("path/to/file")
'/path/to/file'
path_is_dir ¶
Return True if a filesystem path is a directory.
path_is_file ¶
Return True if a filesystem path is a regular file.
path_leaf ¶
Return the last part (leaf) of a given file path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
The input file path |
required |
Returns:
| Type | Description |
|---|---|
str
|
The leaf name (file or folder name) of the path |
Example
path_leaf("/some/folder/file.txt") 'file.txt' path_leaf("Documents/project") 'project'
path_safe_join ¶
Safely join path components ensuring result stays under the base directory.
This function prevents directory traversal attacks by ensuring the resulting path never escapes the base directory.
base_directory_path: Base directory path.
*path_components: Path components to join.
str: Joined path relative to base (without leading slash).
ValueError: If joined path escapes base directory.
Example:¶
>>> path_safe_join("/var/data", "uploads", "file.txt")
'var/data/uploads/file.txt'
>>> path_safe_join("/var/data", "../etc/passwd")
Traceback (most recent call last):
ValueError: the joined path is located outside of the base path
path_secure ¶
Secure a file path against traversal attacks.
Normalizes and secures a file path, ensuring it stays within the base directory by using only the basename of the user path.
base_path: The base directory path.
user_path: The user-provided path to secure.
str: A secured path string.
Example:¶
>>> path_secure("/var/data", "../../../etc/passwd")
'/var/data/passwd'
rename_file ¶
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.
uncompress_file ¶
Decompress a gzip file and return the uncompressed output.
input_file: Gzip-compressed file-like object.
filename: Original filename (used to derive uncompressed name).
Tuple of (decompressed file object, filename without .gz extension).
Modules¶
compress ¶
Compression helpers for filesystem utilities.
Functions¶
compress_file ¶
Compress a file using gzip and return the compressed output.
input_file: File-like object to compress.
filename: Original filename (used as internal gzip metadata).
Tuple of (compressed file object, new filename with .gz extension).
uncompress_file ¶
Decompress a gzip file and return the uncompressed output.
input_file: Gzip-compressed file-like object.
filename: Original filename (used to derive uncompressed name).
Tuple of (decompressed file object, filename without .gz extension).
Modules¶
gzip_compress ¶
Gzip Compression Module¶
Provides gzip compression functionality for file objects.
gzip_settings ¶
GZIP Compression Settings Module¶
Provides configurable settings for GZIP compression operations.
Configuration settings for GZIP compression operations.
Attributes¶
TMP_FILE_MAX_SIZE : int Maximum size in bytes before spooling to disk (default: 5MB). TMP_FILE_READ_SIZE : int Chunk size in bytes for file I/O operations (default: 1MB). TMP_DIR : None | str Temporary directory path (None uses system default).
gzip_uncompress ¶
Gzip Decompression Module¶
Provides gzip decompression functionality for file objects.
file ¶
File-level helpers for the filesystem package.
Functions¶
copy_file ¶
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 ¶
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 ¶
create_spooled_temporary_file(filepath: str | Path | None = None, fileobj: object | 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 ¶
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 ¶
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 ¶
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.
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.
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.
file_move ¶
File Move Module¶
Provides utilities for moving files between directories.
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_text ¶
file_rename ¶
File Rename Module¶
Provides utilities for renaming files within directories.
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.
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.
create_spooled_temporary_file(filepath: str | Path | None = None, fileobj: object | 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 ¶
file_write_bytes ¶
file_extension ¶
File extension helpers for the filesystem package.
Modules¶
extension_normalize ¶
File Extension Normalization Module¶
Provides utilities for normalizing file extensions.
Normalize a file extension.
Strips whitespace and leading dots, converts to lowercase.
extension: Extension string (e.g. ".JPG", " pdf ", "tar.gz").
leading_dot: If True, return with a leading ".".
str | None: Normalized extension, or None if empty/None.
Example:¶
>>> extension_normalize(".JPG")
'jpg'
>>> extension_normalize(" PDF ", leading_dot=True)
'.pdf'
>>> extension_normalize(" ")
None
extension_regex ¶
extension_validate ¶
File Extension Validation Module¶
Provides utilities for validating file extensions.
extension_validate(extension: str | None, *, allowed: Iterable[str] | None = None, regex: Pattern[str] = EXTENSION_REGEX) -> None
Validate a file extension.
extension: Extension string to validate (should be normalized).
allowed: Optional iterable of allowed extensions (case-insensitive).
regex: Pattern to match valid extensions.
ValueError: If extension is None/empty, doesn't match regex, or not allowed.
Example:¶
>>> extension_validate("pdf")
>>> extension_validate("jpg", allowed=["png", "jpg", "gif"])
>>> extension_validate("exe", allowed=["png", "jpg"])
Traceback (most recent call last):
ValueError: Extension 'exe' not allowed...
folder ¶
Rite - Folder Module¶
This module provides utilities for folder management and manipulation within the Rite application.
Modules¶
folder_content_delete ¶
Folder Content Delete Module¶
Deletes all files and subdirectories inside a given folder.
Deletes all files and subdirectories inside a given folder. The folder itself is preserved.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
folder
|
str | Path
|
The directory whose contents will be deleted. |
required |
dry_run
|
bool
|
If True, shows what would be deleted without performing it. |
False
|
verbose
|
bool
|
If True, prints or logs deleted paths. |
True
|
folder_create ¶
Folder Create Module¶
This module provides functions to create directories.
Ensures the given directory exists and returns the Path object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
The directory path to create. |
required |
mode
|
int
|
Permissions mode (default: 0o777). |
511
|
Returns:
| Name | Type | Description |
|---|---|---|
Path |
Path
|
A pathlib.Path object representing the created or existing directory. |
folder_ensure_exists ¶
folder_list_folders ¶
Folder List Folders Module¶
Lists all subdirectories inside a given directory.
list_folders(rootdir: str | Path, pattern: str | None = None, recursive: bool = False) -> list[Path]
Lists all subdirectories inside a given directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
rootdir
|
str | Path
|
The directory to search. |
required |
pattern
|
str | None
|
Optional glob pattern to filter directories (e.g., 'data*'). |
None
|
recursive
|
bool
|
If True, searches recursively through all subfolders. |
False
|
Returns:
| Type | Description |
|---|---|
list[Path]
|
list[Path]: A list of Path objects representing found directories. |
folder_size_get ¶
Folder Size Get Module¶
Calculate the total size of all files in a folder recursively.
folder_size_to_string ¶
Folder Size To String¶
Compute the total size of a folder and return a human-readable string.
Return the total size of a folder as a human-readable string.
This walks the folder, summing file sizes using Path.stat and then
formatting the aggregate size via :func:file_size_to_string.
Args¶
path: Folder path.
recursive: If ``True``, walk subfolders recursively.
Returns¶
str: Human-readable size such as ``"12.3 MB"``.
mimetype ¶
Storage Storage - Mimetype Utils Module¶
This module groups functions related to MIME type (Multipurpose Internet Mail Extensions) handling within the storage system. It provides utilities for verifying the MIME type of files, which is crucial for validating file types, ensuring compatibility, and enhancing security by preventing the processing of unsupported or potentially malicious file formats.
Included Utilities: - MIME Type Verification: Checks if a file's MIME type matches expected types, helping in enforcing content policies and security measures.
Future or Conditional Utilities: - MIME Type Detection: (Commented out) Functionality for determining the MIME type of a file based on its content, which can be useful for content identification and handling.
These utilities assist in maintaining a robust and secure storage system by ensuring that only files with appropriate MIME types are processed or stored.
Modules¶
mimetype_guess ¶
MIME Type Guessing Utility¶
Best-effort MIME type detection for heterogeneous inputs. Supports:
- UploadedFile-like objects (honors explicit content_type if present)
- File-like objects (reads non-destructive head bytes)
- Bytes-like payloads
- Filenames, paths, and URLs (extension-based guess)
Provides a simple mimetype_guess() routine with an optional
prefer_sniff mode to prioritize byte-sniffing over extension guessing.
Returns a lowercase MIME string like "image/png", or None when unknown.
mimetype_guess(input_object: object, *, prefer_sniff: bool = False, max_bytes: int = 8192) -> str | None
Best-effort MIME detection for
- UploadedFile-like objects (uses
.content_typeif present) - File-like objects (reads head bytes non-destructively)
- Bytes-like objects
- Strings / PathLike (filenames or URLs)
Order (default):
1) explicit .content_type if present
2) guess from name/path (extension)
3) sniff head bytes
If prefer_sniff=True:
1) explicit .content_type
2) sniff head bytes
3) guess from name/path
Returns a lowercase MIME string like "image/png", or None if unknown.
mimetype_guess_from_path ¶
Mimetype Guess From Path¶
Guess the mimetype and encoding from a file path using mimetypes.
mimetype_match ¶
Mimetype Match Utility Module¶
Simple helpers to match MIME types against wildcard or exact patterns.
mimetype_read_head_bytes ¶
MIME Type Utility Module¶
Module docstring placeholder added for standardized formatting.
Return up to the first n bytes from obj without consuming it,
or None if that can't be done safely.
Supports
- bytes / bytearray / memoryview
- str / os.PathLike (opened in 'rb' and closed)
- File-like objects with .peek(n)
- File-like objects with .read(n) and seek/tell (position restored)
If the object is a non-seekable stream without .peek(), returns None to avoid side effects (reading would consume data).
mimetype_sniff ¶
Mimetype Sniff Utility Module¶
Best-effort magic-number based MIME type detection.
Best-effort MIME sniffing from magic numbers.
Returns None if no known signature is found. Only inspects the first
max_probe bytes (default 512). Supports common formats: PNG, JPEG,
GIF, WebP, PDF, ZIP, GZIP, MP3/ID3, MP4 (ftyp brands), WAV,
Ogg/Opus/Vorbis, FLAC, AVIF/HEIF.
buf: Bytes-like object to sniff.
max_probe: Maximum bytes to inspect. Defaults to 512.
str | None: MIME type string or None if unrecognized.
mimetype_validate ¶
Rite - Filesystem - MIME Type Validation Module¶
Provides functionality to validate MIME types of files or data.
Bases: ValueError
Raised when a value does not satisfy MIME type constraints.
validate_mimetype(input_object: Any, *, allowed: Iterable[str] | None = None, forbidden: Iterable[str] | None = None) -> str
Validate MIME type of input_object without any Django dependency.
Returns the detected MIME string on success. Raises MimeValidationError on failure.
mimetype_verify ¶
Verify Mimetype Function¶
Check File Type
This function checks the MIME type of a file to determine if it matches allowed types, which is useful for validating uploaded files.
Verify Mimetype Function¶
Verifies if the MIME type of a given file is within the allowed types.
Parameters: - filename (str): The path or name of the file to check. - allowed_types (list): A list of allowed MIME types (e.g., ['image/jpeg', 'image/png']).
Returns: - bool: True if the file's MIME type is allowed, False otherwise.
path ¶
Path helpers for filesystem package.
Modules¶
path_clean ¶
Path Cleaning Module¶
Provides path normalization and cleaning utilities.
path_exists ¶
path_is_dir ¶
path_is_file ¶
path_leaf ¶
Path Leaf Extraction¶
Get the leaf (final component) of a path.
Return the last part (leaf) of a given file path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
The input file path |
required |
Returns:
| Type | Description |
|---|---|
str
|
The leaf name (file or folder name) of the path |
Example
path_leaf("/some/folder/file.txt") 'file.txt' path_leaf("Documents/project") 'project'
path_safe_join ¶
Safe Path Join Module¶
Provides safe path joining preventing traversal outside base directory.
Safely join path components ensuring result stays under the base directory.
This function prevents directory traversal attacks by ensuring the resulting path never escapes the base directory.
base_directory_path: Base directory path.
*path_components: Path components to join.
str: Joined path relative to base (without leading slash).
ValueError: If joined path escapes base directory.
Example:¶
>>> path_safe_join("/var/data", "uploads", "file.txt")
'var/data/uploads/file.txt'
>>> path_safe_join("/var/data", "../etc/passwd")
Traceback (most recent call last):
ValueError: the joined path is located outside of the base path
path_secure ¶
Path Security Module¶
Provides secure path operations preventing traversal attacks.
Secure a file path against traversal attacks.
Normalizes and secures a file path, ensuring it stays within the base directory by using only the basename of the user path.
base_path: The base directory path.
user_path: The user-provided path to secure.
str: A secured path string.
Example:¶
>>> path_secure("/var/data", "../../../etc/passwd")
'/var/data/passwd'
Submodules¶
File Operations¶
Read, write, copy, move, and delete files.
File-level helpers for the filesystem package.
Modules¶
file_read_text ¶
file_read_bytes ¶
file_write_bytes ¶
file_copy ¶
File Copy Module¶
Provides utilities for copying files.
Functions¶
copy_file ¶
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_move ¶
File Move Module¶
Provides utilities for moving files between directories.
Functions¶
move_file ¶
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_delete ¶
File Deletion Module¶
Provides utilities for deleting files safely.
file_rename ¶
File Rename Module¶
Provides utilities for renaming files within directories.
Functions¶
rename_file ¶
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 ¶
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'.
Folder Operations¶
Manage directories and list files.
Rite - Folder Module¶
This module provides utilities for folder management and manipulation within the Rite application.
Modules¶
folder_ensure_exists ¶
folder_size_to_string ¶
Folder Size To String¶
Compute the total size of a folder and return a human-readable string.
Functions¶
folder_size_to_string ¶
Return the total size of a folder as a human-readable string.
This walks the folder, summing file sizes using Path.stat and then
formatting the aggregate size via :func:file_size_to_string.
Args¶
path: Folder path.
recursive: If ``True``, walk subfolders recursively.
Returns¶
str: Human-readable size such as ``"12.3 MB"``.
Path Utilities¶
Path manipulation and validation.
Path helpers for filesystem package.
Modules¶
path_exists ¶
path_is_file ¶
path_is_dir ¶
path_clean ¶
Path Cleaning Module¶
Provides path normalization and cleaning utilities.
Functions¶
path_secure ¶
Path Security Module¶
Provides secure path operations preventing traversal attacks.
Functions¶
path_secure ¶
Secure a file path against traversal attacks.
Normalizes and secures a file path, ensuring it stays within the base directory by using only the basename of the user path.
base_path: The base directory path.
user_path: The user-provided path to secure.
str: A secured path string.
Example:¶
>>> path_secure("/var/data", "../../../etc/passwd")
'/var/data/passwd'
path_safe_join ¶
Safe Path Join Module¶
Provides safe path joining preventing traversal outside base directory.
Functions¶
path_safe_join ¶
Safely join path components ensuring result stays under the base directory.
This function prevents directory traversal attacks by ensuring the resulting path never escapes the base directory.
base_directory_path: Base directory path.
*path_components: Path components to join.
str: Joined path relative to base (without leading slash).
ValueError: If joined path escapes base directory.
Example:¶
>>> path_safe_join("/var/data", "uploads", "file.txt")
'var/data/uploads/file.txt'
>>> path_safe_join("/var/data", "../etc/passwd")
Traceback (most recent call last):
ValueError: the joined path is located outside of the base path
path_leaf ¶
Path Leaf Extraction¶
Get the leaf (final component) of a path.
Functions¶
path_leaf ¶
Return the last part (leaf) of a given file path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
The input file path |
required |
Returns:
| Type | Description |
|---|---|
str
|
The leaf name (file or folder name) of the path |
Example
path_leaf("/some/folder/file.txt") 'file.txt' path_leaf("Documents/project") 'project'
Compression¶
Gzip compression and decompression.
Compression helpers for filesystem utilities.
Functions¶
compress_file ¶
Compress a file using gzip and return the compressed output.
input_file: File-like object to compress.
filename: Original filename (used as internal gzip metadata).
Tuple of (compressed file object, new filename with .gz extension).
uncompress_file ¶
Decompress a gzip file and return the uncompressed output.
input_file: Gzip-compressed file-like object.
filename: Original filename (used to derive uncompressed name).
Tuple of (decompressed file object, filename without .gz extension).
Examples¶
File Operations¶
from rite.filesystem import (
file_read_text,
file_write_text,
file_copy,
file_move
)
# Read text file
content = file_read_text("input.txt")
# Write text file
file_write_text("output.txt", "Hello World")
# Copy file
file_copy("source.txt", "destination.txt")
# Move file
file_move("old.txt", "new.txt")
Path Management¶
from rite.filesystem import (
path_exists,
path_is_file,
path_secure,
path_safe_join
)
# Check existence
exists = path_exists("/path/to/file.txt")
# Check if file
is_file = path_is_file("/path/to/file.txt")
# Secure path (prevent directory traversal)
safe = path_secure("../../etc/passwd")
# Safe join
joined = path_safe_join("/base", "sub", "file.txt")