Foundation types

class FastEnum(value)

Bases: object

A reimplementation of a subset of the Enum functionality, which is far quicker than Enum.

enum.Enum attributes accesses can be really slow, and slow down the execution noticeably. This reimplementation doesn’t suffer the same problems, but also does not reimplement everything.

name = None

The name of the current Enum entry, same as

value = None

The value of the current Enum entry, same as enum.Enum.value()

classmethod values()

Get all the possible values for the enum.


the list of all possible values for the enum

Return type:


class CoreWarnings

Bases: object

Some common warnings which are raised by core functionalities within BuildStream are found in this class.

OVERLAPS = 'overlaps'

This warning will be produced when buildstream detects an overlap on an element which is not whitelisted. See Overlap Whitelist

UNSTAGED_FILES = 'unstaged-files'

This warning will be produced when a file cannot be staged. This can happen when a file overlaps with a directory in the sandbox that is not empty.

REF_NOT_IN_TRACK = 'ref-not-in-track'

This warning will be produced when a source is configured with a reference which is found to be invalid based on the configured track

UNALIASED_URL = 'unaliased-url'

A URL used for fetching a sources was specified without specifying any alias

class OverlapAction

Bases: FastEnum

Defines what action to take when files staged into the sandbox overlap.


This only dictates what happens when functions such as Element.stage_artifact() and Element.stage_dependency_artifacts() are called multiple times in an Element’s Element.stage() implementation, and the files staged from one function call result in overlapping files staged from previous invocations.

If multiple staged elements overlap eachother within a single call to Element.stage_dependency_artifacts(), then the overlap whitelist will be ovserved, and warnings will be issued for overlapping files, which will be fatal warnings if CoreWarnings.OVERLAPS is specified as a fatal warning.

ERROR = <buildstream.types.OverlapAction object>

It is an error to overlap previously staged files

WARNING = <buildstream.types.OverlapAction object>

A warning will be issued for previously staged files, which will fatal if CoreWarnings.OVERLAPS is specified as a fatal warning in the project.

IGNORE = <buildstream.types.OverlapAction object>

Overlapping files are acceptable, and do not cause any warning or error.


A simple python object used to describe and exact set of sources

This can be None in order to represent an absense of a source reference, otherwise it can be int, str, or a complex list or dict consisting of int, str, list and dict types.

The order of elements in list objects is meaningful and should be produced deterministically by Source implementations, as this order will effect cache keys.

See the source documentation for more detils on how Source implementations are expected to handle the source ref.

alias of None | int | str | List[Any] | Dict[str, Any]