Directory

This is a virtual Directory class to isolate the rest of BuildStream from the backing store implementation. Sandboxes are allowed to read from and write to the underlying storage, but all others must use this Directory class to access files and directories in the sandbox.

See also: Sandboxing.

exception VirtualDirectoryError(message, reason=None)

Bases: buildstream._exceptions.BstError

Raised by Directory functions when system calls fail. This will be handled internally by the BuildStream core, if you need to handle this error, then it should be reraised, or either of the ElementError or SourceError exceptions should be raised from this error.

class Directory(external_directory=None)

Bases: object

descend(*paths: str, create: bool = False, follow_symlinks: bool = False)

Descend one or more levels of directory hierarchy and return a new Directory object for that directory.

Parameters

• *paths – A list of strings which are all directory names.

• create – If this is true, the directories will be created if they don’t already exist.

Yields

A Directory object representing the found directory.

Raises

VirtualDirectoryError – if any of the components in subdirectory_spec cannot be found, or are files, or symlinks to files.

import_files(external_pathspec: Union[Directory, str], *, filter_callback: Optional[Callable[[str], bool]] = None, report_written: bool = True, update_mtime: Optional[float] = None, can_link: bool = False, properties: Optional[List[str]] = None) → buildstream.utils.FileListResult

Imports some or all files from external_path into this directory.

Parameters

• external_pathspec – Either a string containing a pathname, or a Directory object, to use as the source.

• filter_callback – Optional filter callback. Called with the relative path as argument for every file in the source directory. The file is imported only if the callable returns True. If no filter callback is specified, all files will be imported.

• report_written – Return the full list of files written. Defaults to true. If false, only a list of overwritten files is returned.

• update_mtime – Update the access and modification time of each file copied to the time specified in seconds.

• can_link – Whether it’s OK to create a hard link to the original content, meaning the stored copy will change when the original files change. Setting this doesn’t guarantee hard links will be made.

• properties – Optional list of strings representing file properties to capture when importing.

Yields

A report of files imported and overwritten.

import_single_file(external_pathspec, properties=None)

Imports a single file from an external path

export_files(to_directory, *, can_link=False, can_destroy=False)

Copies everything from this into to_directory.

Parameters

• to_directory (string) – a path outside this directory object where the contents will be copied to.

• can_link (bool) – Whether we can create hard links in to_directory instead of copying. Setting this does not guarantee hard links will be used.

• can_destroy (bool) – Can we destroy the data already in this directory when exporting? If set, this may allow data to be moved rather than copied which will be quicker.

export_to_tar(tarfile, destination_dir, mtime=1321009871)

Exports this directory into the given tar file.

Parameters

• tarfile (TarFile) – A Python TarFile object to export into.

• destination_dir (str) – The prefix for all filenames inside the archive.

• mtime (int) – mtimes of all files in the archive are set to this.

is_empty()

Return true if this directory has no files, subdirectories or links in it.

set_deterministic_user()

Sets all files in this directory to the current user’s euid/egid.

mark_unmodified()

Marks all files in this directory (recursively) as unmodified.

list_modified_paths()

Provide a list of relative paths which have been modified since the last call to mark_unmodified. Includes directories only if they are empty.

Yields

(List(str)) - list of all modified files with relative paths.

list_relative_paths()

Provide a list of all relative paths in this directory. Includes directories only if they are empty.

Yields

(List(str)) - list of all files with relative paths.

get_size()

Get an approximation of the storage space in bytes used by this directory and all files and subdirectories in it. Storage space varies by implementation and effective space used may be lower than this number due to deduplication.

exists(*paths: str, follow_symlinks: bool = False) → bool

Check whether the specified path exists.

Parameters

• *paths – A list of strings which are all path components.

• follow_symlinks – True to follow symlinks.

Returns

True if the path exists, False otherwise.

stat(*paths: str, follow_symlinks: bool = False) → os.stat_result

Get the status of a file.

Parameters

• *paths – A list of strings which are all path components.

• follow_symlinks – True to follow symlinks.

Returns

A os.stat_result object.

isfile(*paths: str, follow_symlinks: bool = False) → bool

Check whether the specified path is an existing regular file.

Parameters

• *paths – A list of strings which are all path components.

• follow_symlinks – True to follow symlinks.

Returns

True if the path is an existing regular file, False otherwise.

isdir(*paths: str, follow_symlinks: bool = False) → bool

Check whether the specified path is an existing directory.

Parameters

• *paths – A list of strings which are all path components.

• follow_symlinks – True to follow symlinks.

Returns

True if the path is an existing directory, False otherwise.

islink(*paths: str, follow_symlinks: bool = False) → bool

Check whether the specified path is an existing symlink.

Parameters

• *paths – A list of strings which are all path components.

• follow_symlinks – True to follow symlinks.

Returns

True if the path is an existing symlink, False otherwise.

open_file(*paths: str, mode: str = 'r')

Open file and return a corresponding file object. In text mode, UTF-8 is used as encoding.

Parameters

• *paths – A list of strings which are all path components.

• mode (str) – An optional string that specifies the mode in which the file is opened.

file_digest(*paths: str) → str

Return a digest of a file. The digest algorithm is implementation- defined.

Parameters

*paths – A list of strings which are all path components.

readlink(*paths: str) → str

Return a string representing the path to which the symbolic link points.

Parameters

*paths – A list of strings which are all path components.

remove(*paths: str, recursive: bool = False)

Remove a file, symlink or directory. Symlinks are not followed.

Parameters

• *paths – A list of strings which are all path components.

• recursive – True to delete non-empty directories.

rename(src: List[str], dest: List[str])

Rename a file, symlink or directory. If destination path exists already and is a file or empty directory, it will be replaced.

Parameters

• *src – Source path components.

• *dest – Destination path components.