types.py: Adding OverlapAction enumeration

Used to define the behavior of multiple calls to Element.stage_artifact()
and Element.stage_dependency_artifacts()

2 files changed, 41 insertions, 1 deletions

diff --git a/src/buildstream/__init__.py b/src/buildstream/__init__.py
index 4d151873d..606353af0 100644
--- a/src/buildstream/__init__.py
+++ b/src/buildstream/__init__.py
@@ -30,7 +30,7 @@ if "_BST_COMPLETION" not in os.environ:
 
     from .utils import UtilError, ProgramNotFoundError
     from .sandbox import Sandbox, SandboxFlags, SandboxCommandError
-    from .types import CoreWarnings
+    from .types import CoreWarnings, OverlapAction
     from .node import MappingNode, Node, ProvenanceInformation, ScalarNode, SequenceNode
     from .plugin import Plugin
     from .source import Source, SourceError, SourceFetcher
diff --git a/src/buildstream/types.py b/src/buildstream/types.py
index 3b1f7a4db..7ba279374 100644
--- a/src/buildstream/types.py
+++ b/src/buildstream/types.py
@@ -119,6 +119,46 @@ class CoreWarnings:
     """
 
 
+class OverlapAction(FastEnum):
+    """OverlapAction()
+
+    Defines what action to take when files staged into the sandbox overlap.
+
+    .. note::
+
+       This only dictates what happens when functions such as
+       :func:`Element.stage_artifact() <buildstream.element.Element.stage_artifact>` and
+       :func:`Element.stage_dependency_artifacts() <buildstream.element.Element.stage_dependency_artifacts>`
+       are called multiple times in an Element's :func:`Element.stage() <buildstream.element.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
+       :func:`Element.stage_dependency_artifacts() <buildstream.element.Element.stage_dependency_artifacts>`,
+       then the :ref:`overlap whitelist <public_overlap_whitelist>` will be ovserved, and warnings will
+       be issued for overlapping files, which will be fatal warnings if
+       :attr:`CoreWarnings.OVERLAPS <buildstream.types.CoreWarnings.OVERLAPS>` is specified
+       as a :ref:`fatal warning <configurable_warnings>`.
+    """
+
+    ERROR = "error"
+    """
+    It is an error to overlap previously staged files
+    """
+
+    WARNING = "warning"
+    """
+    A warning will be issued for previously staged files, which will fatal if
+    :attr:`CoreWarnings.OVERLAPS <buildstream.types.CoreWarnings.OVERLAPS>` is specified
+    as a :ref:`fatal warning <configurable_warnings>` in the project.
+    """
+
+    IGNORE = "ignore"
+    """
+    Overlapping files are acceptable, and do not cause any warning or error.
+    """
+
+
 # _Scope():
 #
 # Defines the scope of dependencies to include for a given element