curldl.util.fs module

Filesystem utilities for internal use

class curldl.util.fs.FileSystem

Bases: object

Filesystem utilities, include cryptographic digest verification wrappers

static verify_rel_path_is_safe(basedir: str | PathLike[str], rel_path: str | PathLike[str]) → None

Verify that a relative path does not escape base directory and either does not exist or is a file or a symlink to one.

Parameters:

• basedir (str | PathLike[str]) – base directory path

• rel_path (str | PathLike[str]) – path relative to base directory

Raises:

ValueError – relative path escapes base directory before or after symlink resolution, resulting path is a dangling symlink, is not a file or a symlink to file

classmethod create_directory_for_path(path: str | PathLike[str]) → None

Create all path components for path, except for last.

Parameters:

path (str | PathLike[str]) – file path

classmethod verify_size_and_digests(path: str | PathLike[str], *, size: int | None = None, digests: dict[str, str] | None = None) → None

Verify file size and digests and raise ValueError in case of mismatch. digests is a dict of hash algorithms and digests to check (see curldl.util.crypt.Cryptography.verify_digest()).

Parameters:

• path (str | PathLike[str]) – input file path

• size (int | None) – expected file size in bytes, or None to ignore

• digests (dict[str, str] | None) – mapping of digest algorithms to expected hexadecimal digest strings, or None to ignore

Raises:

ValueError – not a file or file size mismatch or one of digests fails verification

classmethod verify_size(path: str | PathLike[str], size: int) → None

Verify file size and raise ValueError in case of mismatch or if not a file.

Parameters:

• path (str | PathLike[str]) – input file path

• size (int) – expected file size in bytes

Raises:

ValueError – not a file or file size mismatch

static get_file_size(path: str | PathLike[str], default: int = 0) → int

Returns file size, or default if it does not exist or is not a file.

Parameters:

• path (str | PathLike[str]) – input file path

• default (int) – value to return if path does not exist or is not a file (e.g., a directory)

Returns:

input file size

Return type:

int

classmethod set_file_timestamp(path: str | PathLike[str], timestamp: int | float) → None

Sets file timestamp to a POSIX timestamp. If timestamp is negative, does nothing.

Parameters:

• path (str | PathLike[str]) – filesystem path, must exist; symlinks are followed

• timestamp (int | float) – POSIX UTC-based timestamp to store as last-modified and last-accessed file time if non-negative