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, create=False)

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

  • *paths (str) – A list of strings which are all directory names.
  • create (boolean) – If this is true, the directories will be created if they don’t already exist.

A Directory object representing the found directory.


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

import_files(external_pathspec, *, filter_callback=None, report_written=True, update_mtime=False, can_link=False)

Imports some or all files from external_path into this directory.

  • external_pathspec – Either a string containing a pathname, or a Directory object, to use as the source.
  • filter_callback (callable) – 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 (bool) – Return the full list of files written. Defaults to true. If false, only a list of overwritten files is returned.
  • update_mtime (bool) – Update the access and modification time of each file copied to the current time.
  • can_link (bool) – 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. can_link will never be used if update_mtime is set.

(FileListResult) - A report of files imported and overwritten.

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

Copies everything from this into to_directory.

  • 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.

  • 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.

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


Sets a static modification time for all regular files in this directory. The magic number for timestamps is 2011-11-11 11:11:11.


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


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


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.

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 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.