Directory - Interfacing with files

The Directory class is given to plugins by way of the Sandbox and in some other instances. This API allows plugins to interface with files and directory hierarchies owned by BuildStream.

Paths

The path argument to directory functions depict a relative path. Path elements are separated with the / character regardless of the platform. Both . and .. entries are permitted. Absolute paths are not permitted, as such it is illegal to specify a path with a leading / character.

Directory objects represent a directory entry within the context of a directory tree, and the directory returned by Sandbox.get_virtual_directory() is the root of the sandbox’s directory tree. Attempts to escape the root of a directory tree using .. entries will not result in an error, instead .. entries which cross the root boundary will be evaluated as the root directory. This behavior matches POSIX behavior of filesystem root directories.

exception DirectoryError(message: str, reason: str | None = None)

Bases: BstError

Raised by Directory functions.

It is recommended to handle this error and raise a more descriptive user facing ElementError or SourceError from this error.

If this is not handled, the BuildStream core will fail the current task where the error occurs and present the user with the error.

class FileType(value)

Bases: FastEnum

Depicts the type of a file

DIRECTORY: int = <buildstream.storage.directory.FileType object>

A directory

REGULAR_FILE: int = <buildstream.storage.directory.FileType object>

A regular file

A symbolic link

class FileStat(file_type: int, *, executable: bool = False, size: int = 0, mtime: float = 1321009871)

Bases: object

Depicts stats about a file

Note

This object can be compared with the equality operator, two FileStat objects will be considered equivalent if they have the same FileType and have equivalent attributes.

file_type: int

The FileType of this file

executable: bool

Whether this file is executable

size: int

The size of the file in bytes

mtime: float

The modification time of the file

class Directory(external_directory=None)

Bases: object

The Directory object represents a directory in a filesystem hierarchy

Tip

Directory objects behave as a collection of entries in the pythonic sense. Iterating over a directory will yield the entries, and a directory is truthy if it contains any entries and falsy if it is empty.

open_directory(path: str, *, create: bool = False, follow_symlinks: bool = False) → Directory

Open a Directory object relative to this directory

Parameters:

  • path – A path relative to this directory.

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

Returns:

A Directory object representing the found directory.

Raises:

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

import_files(external_pathspec: Directory | str, *, filter_callback: Callable[[str], bool] | None = None, collect_result: bool = True) → FileListResult | None

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.

  • collect_result – Whether to collect data for the FileListResult, defaults to True.

Returns:

A FileListResult report of files imported and overwritten, or None if collect_result is False.

Raises:

DirectoryError – if any system error occurs.

import_single_file(external_pathspec: str) → FileListResult

Imports a single file from an external path

Parameters:

  • external_pathspec – A string containing a pathname.

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

Returns:

A FileListResult report of files imported and overwritten.

Raises:

DirectoryError – if any system error occurs.

export_to_tar(tarfile: TarFile, destination_dir: str, mtime: int = 1321009871) → None

Exports this directory into the given tar file.

Parameters:

  • tarfile – A Python TarFile object to export into.

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

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

Raises:

DirectoryError – if any system error occurs.

list_relative_paths() → Iterator[str]

Generate a list of all relative paths in this directory.

Yields:

All files in this directory with relative paths.

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

Check whether the specified path exists.

Parameters:

  • path – A path relative to this directory.

  • follow_symlinks – True to follow symlinks.

Returns:

True if the path exists, False otherwise.

stat(path: str, *, follow_symlinks: bool = False) → FileStat

Get the status of a file.

Parameters:

  • path – A path relative to this directory.

  • follow_symlinks – True to follow symlinks.

Returns:

A FileStat object.

Raises:

DirectoryError – if any system error occurs.

open_file(path: str, *, mode: str = 'r') → Iterator[IO]

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

Parameters:

  • path – A path relative to this directory.

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

Yields:

The file object for the open file

Raises:

DirectoryError – if any system error occurs.

file_digest(path: str) → str

Return a unique digest of a file.

Parameters:

path – A path relative to this directory.

Raises:

DirectoryError – if the specified path depicts an entry that is not a FileType.REGULAR_FILE, or if any system error occurs.

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

Parameters:

path – A path relative to this directory.

Returns:

The path to which the symbolic link points to.

Raises:

DirectoryError – if any system error occurs.

remove(path: str, *, recursive: bool = False) → None

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

Parameters:

  • path – A path relative to this directory.

  • recursive – True to delete non-empty directories.

Raises:

DirectoryError – if any system error occurs.

rename(src: str, dest: str) → None

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

Parameters:

  • src – A source path relative to this directory.

  • dest – A destination path relative to this directory.

Raises:

DirectoryError – if any system error occurs.

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

Check whether the specified path is an existing regular file.

Parameters:

  • path – A path relative to this directory.

  • follow_symlinks – True to follow symlinks.

Returns:

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

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

Check whether the specified path is an existing directory.

Parameters:

  • path – A path relative to this directory.

  • follow_symlinks – True to follow symlinks.

Returns:

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

Check whether the specified path is an existing symlink.

Parameters:

  • path – A path relative to this directory.

  • follow_symlinks – True to follow symlinks.

Returns:

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