craft_parts.utils.file_utils module

File-related utilities.

class craft_parts.utils.file_utils.NonBlockingRWFifo(path)

Bases: object

A non-blocking FIFO for reading and writing.

Parameters:

path (str)

close()

Close the FIFO.

Return type:

None

property path: str

Return the path to the FIFO file.

read()

Read from the FIFO.

Return type:

str

write(data)

Write to the FIFO.

Parameters:

data (str) – The data to write.

Return type:

int

craft_parts.utils.file_utils.calculate_hash(filename, *, algorithm)

Calculate the hash of the given file.

Parameters:

  • filename (Path) – The path to the file to digest.

  • algorithm (str) – The algorithm to use, as defined by hashlib.

Return type:

str

Returns:

The file hash.

Raises:

ValueError – If the algorithm is unsupported.

craft_parts.utils.file_utils.copy(source, destination, *, follow_symlinks=False, permissions=None)

Copy source and destination files.

This function overwrites the destination if it already exists, and also tries to copy ownership information.

Parameters:

  • source (Path) – The source to be copied to destination.

  • destination (Path) – Where to put the copy.

  • follow_symlinks (bool) – Whether or not symlinks should be followed.

  • permissions (list[Permissions] | None) – The permissions definitions that should be applied to the new file.

Raises:

CopyFileNotFound – If source doesn’t exist.

Return type:

None

craft_parts.utils.file_utils.create_similar_directory(source, destination, permissions=None, *, overwrite_metadata=True)

Create a directory with the same permission bits and owner information.

Parameters:

  • source (Path) – Directory from which to copy name, permission bits, and owner information.

  • destination (Path) – Directory to create and to which the source information will be copied.

  • permissions (list[Permissions] | None) – The permission definitions to apply to the new directory. If omitted, the new directory will have the same permissions and ownership of source.

  • overwrite_metadata (bool) – Whether to overwrite metadata (mode, ownership) of existing destination directories.

Return type:

None

craft_parts.utils.file_utils.find_merge_conflicts(src_root, dst_root, *, strict=False)

Check that the given directories can be merged.

Checks that the two directories provided can be merged without overwriting files.

Parameters:

  • strict (bool) – if True, errors if overwriting a file, even if it’s identical.

  • src_root (Path)

  • dst_root (Path)

Return type:

dict[Path, list[str]]

craft_parts.utils.file_utils.get_path_differences(a, b)

Get a list of differences between two paths.

This is a more forgiving test than Path.samefile(), checking whether the files referenced by these two paths are equivalent for the purpose of organizing. If either file does not exist, they are considered to be equivalent.

To be equivalent, they must: - Be of the same type (or one must be a symlink to the other). - Have the same owner and group - Have the same mode.

For regular files, they must also: - Have the same size - Have the same contents

Return type:

list[str]

Returns:

A list of differences. An empty list means the paths are equivalent.

Parameters:

  • a (Path)

  • b (Path)

Hard-link source and destination files.

Parameters:

  • source (Path) – The source to which destination will be linked.

  • destination (Path) – The destination to be linked to source.

  • follow_symlinks (bool) – Whether or not symlinks should be followed.

Raises:

CopyFileNotFound – If source doesn’t exist.

Return type:

None

Hard-link source and destination files. Copy if it fails to link.

Hard-linking may fail (e.g. a cross-device link, or permission denied), so as a backup plan we just copy it. Note that we always copy the file if its permissions will change.

Parameters:

  • source (Path) – The source to which destination will be linked.

  • destination (Path) – The destination to be linked to source.

  • follow_symlinks (bool) – Whether or not symlinks should be followed.

  • permissions (list[Permissions] | None) – The permissions definitions that should be applied to the new file.

Return type:

None

Copy a source tree into a destination, hard-linking if possible.

Parameters:

  • source_tree (Path) – Source directory to be copied.

  • destination_tree (Path) – Destination directory. If this directory already exists, the files in source_tree will take precedence.

  • ignore (Callable[[str, list[str]], list[str]] | None) – If given, called with two params, source dir and dir contents, for every dir copied. Should return list of contents to NOT copy.

  • copy_function (Callable[..., None]) – Callable that actually copies.

  • overwrite_metadata (bool) – Whether to overwrite metadata (mode, ownership) of existing destination directories.

Return type:

None

craft_parts.utils.file_utils.move(source, destination)

Move regular files, directories, or special files from source to destination.

Parameters:

  • source (Path) – Directory from which to move the file or directory.

  • destination (Path) – Directory where the file or directory will be moved to.

Return type:

None