exceptions: Expose ErrorDomain, ErrorLoadReason

Plugin tests are already accessing this API, but using imports from
private modules. For motivation for this to be exposed publicly, note
that ErrorDomain is an argument for most things in runcli.py, and
LoadErrorReason may be another.

27 files changed, 190 insertions, 128 deletions

diff --git a/src/buildstream/_context.py b/src/buildstream/_context.py
index 513754a4c..c3ea52f0e 100644
--- a/src/buildstream/_context.py
+++ b/src/buildstream/_context.py
@@ -22,7 +22,8 @@ import shutil
 from . import utils
 from . import _site
 from . import _yaml
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 from ._messenger import Messenger
 from ._profile import Topics, PROFILER
 from ._platform import Platform
diff --git a/src/buildstream/_exceptions.py b/src/buildstream/_exceptions.py
index 51f542783..e9599d225 100644
--- a/src/buildstream/_exceptions.py
+++ b/src/buildstream/_exceptions.py
@@ -18,9 +18,10 @@
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 #        Tiago Gomes <tiago.gomes@codethink.co.uk>
 
-from enum import Enum, unique
 import os
 
+from .exceptions import ErrorDomain
+
 # Disable pylint warnings for whole file here:
 # pylint: disable=global-statement
 
@@ -79,27 +80,6 @@ def set_last_task_error(domain, reason):
         _last_task_error_reason = reason
 
 
-@unique
-class ErrorDomain(Enum):
-    PLUGIN = 1
-    LOAD = 2
-    IMPL = 3
-    PLATFORM = 4
-    SANDBOX = 5
-    ARTIFACT = 6
-    PIPELINE = 7
-    UTIL = 8
-    SOURCE = 9
-    ELEMENT = 10
-    APP = 11
-    STREAM = 12
-    VIRTUAL_FS = 13
-    CAS = 14
-    PROG_NOT_FOUND = 15
-    REMOTE = 16
-    PROFILE = 17
-
-
 # BstError is an internal base exception class for BuildStream
 # exceptions.
 #
@@ -148,88 +128,6 @@ class PluginError(BstError):
         super().__init__(message, domain=ErrorDomain.PLUGIN, reason=reason, temporary=False)
 
 
-# LoadErrorReason
-#
-# Describes the reason why a :class:`.LoadError` was raised.
-#
-class LoadErrorReason(Enum):
-
-    # A file was not found.
-    MISSING_FILE = 1
-
-    # The parsed data was not valid YAML.
-    INVALID_YAML = 2
-
-    # Data was malformed, a value was not of the expected type, etc
-    INVALID_DATA = 3
-
-    # An error occurred during YAML dictionary composition.
-    #
-    # This can happen by overriding a value with a new differently typed
-    # value, or by overwriting some named value when that was not allowed.
-    ILLEGAL_COMPOSITE = 4
-
-    # An circular dependency chain was detected
-    CIRCULAR_DEPENDENCY = 5
-
-    # A variable could not be resolved. This can happen if your project
-    # has cyclic dependencies in variable declarations, or, when substituting
-    # a string which refers to an undefined variable.
-    UNRESOLVED_VARIABLE = 6
-
-    # BuildStream does not support the required project format version
-    UNSUPPORTED_PROJECT = 7
-
-    # Project requires a newer version of a plugin than the one which was loaded
-    UNSUPPORTED_PLUGIN = 8
-
-    # A conditional expression failed to resolve
-    EXPRESSION_FAILED = 9
-
-    # An assertion was intentionally encoded into project YAML
-    USER_ASSERTION = 10
-
-    # A list composition directive did not apply to any underlying list
-    TRAILING_LIST_DIRECTIVE = 11
-
-    # Conflicting junctions in subprojects
-    CONFLICTING_JUNCTION = 12
-
-    # Failure to load a project from a specified junction
-    INVALID_JUNCTION = 13
-
-    # Subproject has no ref
-    SUBPROJECT_INCONSISTENT = 15
-
-    # An invalid symbol name was encountered
-    INVALID_SYMBOL_NAME = 16
-
-    # A project.conf file was missing
-    MISSING_PROJECT_CONF = 17
-
-    # Try to load a directory not a yaml file
-    LOADING_DIRECTORY = 18
-
-    # A project path leads outside of the project directory
-    PROJ_PATH_INVALID = 19
-
-    # A project path points to a file of the not right kind (e.g. a
-    # socket)
-    PROJ_PATH_INVALID_KIND = 20
-
-    # A recursive include has been encountered.
-    RECURSIVE_INCLUDE = 21
-
-    # A recursive variable has been encountered
-    RECURSIVE_VARIABLE = 22
-
-    # An attempt so set the value of a protected variable
-    PROTECTED_VARIABLE_REDEFINED = 23
-
-    # A duplicate dependency was detected
-    DUPLICATE_DEPENDENCY = 24
-
-
 # LoadError
 #
 # Raised while loading some YAML.
diff --git a/src/buildstream/_frontend/app.py b/src/buildstream/_frontend/app.py
index cd05b7f8d..8ce5493ee 100644
--- a/src/buildstream/_frontend/app.py
+++ b/src/buildstream/_frontend/app.py
@@ -32,7 +32,8 @@ from .. import Scope
 # Import various buildstream internals
 from .._context import Context
 from .._project import Project
-from .._exceptions import BstError, StreamError, LoadError, LoadErrorReason, AppError
+from .._exceptions import BstError, StreamError, LoadError, AppError
+from ..exceptions import LoadErrorReason
 from .._message import Message, MessageType, unconditional_messages
 from .._stream import Stream
 from .._versions import BST_FORMAT_VERSION
diff --git a/src/buildstream/_includes.py b/src/buildstream/_includes.py
index bc0d7718b..b49560947 100644
--- a/src/buildstream/_includes.py
+++ b/src/buildstream/_includes.py
@@ -1,7 +1,8 @@
 import os
 from . import _yaml
 from .node import MappingNode, ScalarNode, SequenceNode
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 
 
 # Includes()
diff --git a/src/buildstream/_loader/loader.py b/src/buildstream/_loader/loader.py
index 531655c09..3200920b9 100644
--- a/src/buildstream/_loader/loader.py
+++ b/src/buildstream/_loader/loader.py
@@ -19,7 +19,8 @@
 
 import os
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from .. import _yaml
 from ..element import Element
 from ..node import Node
diff --git a/src/buildstream/_loader/types.pyx b/src/buildstream/_loader/types.pyx
index 42a7b801f..1f264789a 100644
--- a/src/buildstream/_loader/types.pyx
+++ b/src/buildstream/_loader/types.pyx
@@ -17,7 +17,8 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from ..node cimport MappingNode, Node, ProvenanceInformation, ScalarNode, SequenceNode
 
 
diff --git a/src/buildstream/_options/optionarch.py b/src/buildstream/_options/optionarch.py
index 2d663f0ef..651afbea5 100644
--- a/src/buildstream/_options/optionarch.py
+++ b/src/buildstream/_options/optionarch.py
@@ -17,7 +17,8 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-from .._exceptions import LoadError, LoadErrorReason, PlatformError
+from .._exceptions import LoadError, PlatformError
+from ..exceptions import LoadErrorReason
 from .._platform import Platform
 from .optionenum import OptionEnum
 
diff --git a/src/buildstream/_options/optionbool.py b/src/buildstream/_options/optionbool.py
index c7289b936..f6159825c 100644
--- a/src/buildstream/_options/optionbool.py
+++ b/src/buildstream/_options/optionbool.py
@@ -17,7 +17,8 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from .option import Option, OPTION_SYMBOLS
 
 
diff --git a/src/buildstream/_options/optionenum.py b/src/buildstream/_options/optionenum.py
index d30f45696..12ec7cb63 100644
--- a/src/buildstream/_options/optionenum.py
+++ b/src/buildstream/_options/optionenum.py
@@ -17,7 +17,8 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from .option import Option, OPTION_SYMBOLS
 
 
diff --git a/src/buildstream/_options/optionflags.py b/src/buildstream/_options/optionflags.py
index 82ede5649..b19a22738 100644
--- a/src/buildstream/_options/optionflags.py
+++ b/src/buildstream/_options/optionflags.py
@@ -17,7 +17,8 @@
 #  Authors:
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from .option import Option, OPTION_SYMBOLS
 
 
diff --git a/src/buildstream/_options/optionpool.py b/src/buildstream/_options/optionpool.py
index f105bb12c..dee038f0b 100644
--- a/src/buildstream/_options/optionpool.py
+++ b/src/buildstream/_options/optionpool.py
@@ -20,7 +20,8 @@
 
 import jinja2
 
-from .._exceptions import LoadError, LoadErrorReason
+from .._exceptions import LoadError
+from ..exceptions import LoadErrorReason
 from ..node import MappingNode, SequenceNode, _assert_symbol_name
 from ..types import FastEnum
 from .optionbool import OptionBool
diff --git a/src/buildstream/_plugincontext.py b/src/buildstream/_plugincontext.py
index 295482574..3a195e239 100644
--- a/src/buildstream/_plugincontext.py
+++ b/src/buildstream/_plugincontext.py
@@ -20,7 +20,8 @@
 import os
 import inspect
 
-from ._exceptions import PluginError, LoadError, LoadErrorReason
+from ._exceptions import PluginError, LoadError
+from .exceptions import LoadErrorReason
 from . import utils
 
 
diff --git a/src/buildstream/_project.py b/src/buildstream/_project.py
index 0a9580dbe..ed3810350 100644
--- a/src/buildstream/_project.py
+++ b/src/buildstream/_project.py
@@ -28,7 +28,8 @@ from . import _site
 from . import _yaml
 from ._artifactelement import ArtifactElement
 from ._profile import Topics, PROFILER
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 from ._options import OptionPool
 from ._artifactcache import ArtifactCache
 from ._sourcecache import SourceCache
diff --git a/src/buildstream/_projectrefs.py b/src/buildstream/_projectrefs.py
index aca7c6712..6af470808 100644
--- a/src/buildstream/_projectrefs.py
+++ b/src/buildstream/_projectrefs.py
@@ -20,7 +20,8 @@ import os
 
 from . import _yaml
 from .node import _new_synthetic_file
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 
 
 # ProjectRefStorage()
diff --git a/src/buildstream/_remote.py b/src/buildstream/_remote.py
index f8edd5192..d01b13b32 100644
--- a/src/buildstream/_remote.py
+++ b/src/buildstream/_remote.py
@@ -21,7 +21,8 @@ from urllib.parse import urlparse
 
 import grpc
 
-from ._exceptions import LoadError, LoadErrorReason, ImplError, RemoteError
+from ._exceptions import LoadError, ImplError, RemoteError
+from .exceptions import LoadErrorReason
 from .types import FastEnum
 
 
diff --git a/src/buildstream/_variables.pyx b/src/buildstream/_variables.pyx
index f8662ac61..f9de2a6cc 100644
--- a/src/buildstream/_variables.pyx
+++ b/src/buildstream/_variables.pyx
@@ -23,7 +23,8 @@
 import re
 import sys
 
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 from .node cimport MappingNode
 
 # Variables are allowed to have dashes here
diff --git a/src/buildstream/_workspaces.py b/src/buildstream/_workspaces.py
index 49b76a7b9..5c3b4af8f 100644
--- a/src/buildstream/_workspaces.py
+++ b/src/buildstream/_workspaces.py
@@ -22,7 +22,8 @@ from . import utils
 from . import _yaml
 
 from .node import MappingNode, ScalarNode
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 
 
 BST_WORKSPACE_FORMAT_VERSION = 3
diff --git a/src/buildstream/_yaml.pyx b/src/buildstream/_yaml.pyx
index 797e10d15..373311a47 100644
--- a/src/buildstream/_yaml.pyx
+++ b/src/buildstream/_yaml.pyx
@@ -29,7 +29,8 @@ from collections.abc import Mapping
 
 from ruamel import yaml
 
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 from . cimport node
 from .node cimport MappingNode, ScalarNode, SequenceNode
 
diff --git a/src/buildstream/element.py b/src/buildstream/element.py
index d39135b53..fe7d36649 100644
--- a/src/buildstream/element.py
+++ b/src/buildstream/element.py
@@ -89,7 +89,8 @@ from pyroaring import BitMap  # pylint: disable=no-name-in-module
 from . import _yaml
 from ._variables import Variables
 from ._versions import BST_CORE_ARTIFACT_VERSION
-from ._exceptions import BstError, LoadError, LoadErrorReason, ImplError, ErrorDomain, SourceCacheError
+from ._exceptions import BstError, LoadError, ImplError, SourceCacheError
+from .exceptions import ErrorDomain, LoadErrorReason
 from .utils import FileListResult
 from . import utils
 from . import _cachekey
diff --git a/src/buildstream/exceptions.py b/src/buildstream/exceptions.py
new file mode 100644
index 000000000..123e18d72
--- /dev/null
+++ b/src/buildstream/exceptions.py
@@ -0,0 +1,141 @@
+#
+#  Copyright (C) 2018 Codethink Limited
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public
+#  License as published by the Free Software Foundation; either
+#  version 2 of the License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library. If not, see <http://www.gnu.org/licenses/>.
+#
+#  Authors:
+#        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
+#        Tiago Gomes <tiago.gomes@codethink.co.uk>
+"""
+Exceptions - API for Error Handling
+===================================
+
+This module contains some Enums used in Error Handling which are useful in
+testing external plugins.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class ErrorDomain(Enum):
+    """ErrorDomain
+
+    Describes what the error is related to.
+    """
+
+    PLUGIN = 1
+    LOAD = 2
+    IMPL = 3
+    PLATFORM = 4
+    SANDBOX = 5
+    ARTIFACT = 6
+    PIPELINE = 7
+    UTIL = 8
+    SOURCE = 9
+    ELEMENT = 10
+    APP = 11
+    STREAM = 12
+    VIRTUAL_FS = 13
+    CAS = 14
+    PROG_NOT_FOUND = 15
+    REMOTE = 16
+    PROFILE = 17
+
+
+class LoadErrorReason(Enum):
+    """LoadErrorReason
+
+    Describes the reason why a :class:`.LoadError` was raised.
+    """
+
+    MISSING_FILE = 1
+    """A file was not found."""
+
+    INVALID_YAML = 2
+    """The parsed data was not valid YAML."""
+
+    INVALID_DATA = 3
+    """Data was malformed, a value was not of the expected type, etc"""
+
+    ILLEGAL_COMPOSITE = 4
+    """An error occurred during YAML dictionary composition.
+
+    This can happen by overriding a value with a new differently typed
+    value, or by overwriting some named value when that was not allowed.
+    """
+
+    CIRCULAR_DEPENDENCY = 5
+    """A circular dependency chain was detected"""
+
+    UNRESOLVED_VARIABLE = 6
+    """A variable could not be resolved. This can happen if your project
+    has cyclic dependencies in variable declarations, or, when substituting
+    a string which refers to an undefined variable.
+    """
+
+    UNSUPPORTED_PROJECT = 7
+    """BuildStream does not support the required project format version"""
+
+    UNSUPPORTED_PLUGIN = 8
+    """Project requires a newer version of a plugin than the one which was
+    loaded
+    """
+
+    EXPRESSION_FAILED = 9
+    """A conditional expression failed to resolve"""
+
+    USER_ASSERTION = 10
+    """An assertion was intentionally encoded into project YAML"""
+
+    TRAILING_LIST_DIRECTIVE = 11
+    """A list composition directive did not apply to any underlying list"""
+
+    CONFLICTING_JUNCTION = 12
+    """Conflicting junctions in subprojects"""
+
+    INVALID_JUNCTION = 13
+    """Failure to load a project from a specified junction"""
+
+    SUBPROJECT_INCONSISTENT = 15
+    """Subproject has no ref"""
+
+    INVALID_SYMBOL_NAME = 16
+    """An invalid symbol name was encountered"""
+
+    MISSING_PROJECT_CONF = 17
+    """A project.conf file was missing"""
+
+    LOADING_DIRECTORY = 18
+    """Try to load a directory not a yaml file"""
+
+    PROJ_PATH_INVALID = 19
+    """A project path leads outside of the project directory"""
+
+    PROJ_PATH_INVALID_KIND = 20
+    """A project path points to a file of the not right kind (e.g. a
+    socket)
+    """
+
+    RECURSIVE_INCLUDE = 21
+    """A recursive include has been encountered"""
+
+    RECURSIVE_VARIABLE = 22
+    """A recursive variable has been encountered"""
+
+    PROTECTED_VARIABLE_REDEFINED = 23
+    """An attempt was made to set the value of a protected variable"""
+
+    DUPLICATE_DEPENDENCY = 24
+    """A duplicate dependency was detected"""
diff --git a/src/buildstream/node.pyx b/src/buildstream/node.pyx
index 58fd0f33d..87c2ab6d1 100644
--- a/src/buildstream/node.pyx
+++ b/src/buildstream/node.pyx
@@ -50,7 +50,8 @@ Class Reference
 
 import string
 
-from ._exceptions import LoadError, LoadErrorReason
+from ._exceptions import LoadError
+from .exceptions import LoadErrorReason
 
 
 # A sentinel to be used as a default argument for functions that need
diff --git a/src/buildstream/source.py b/src/buildstream/source.py
index 4839cf0fe..a221d30a4 100644
--- a/src/buildstream/source.py
+++ b/src/buildstream/source.py
@@ -166,7 +166,8 @@ from . import _yaml, utils
 from .node import MappingNode
 from .plugin import Plugin
 from .types import SourceRef, Union, List
-from ._exceptions import BstError, ImplError, PluginError, ErrorDomain
+from ._exceptions import BstError, ImplError, PluginError
+from .exceptions import ErrorDomain
 from ._loader.metasource import MetaSource
 from ._projectrefs import ProjectRefStorage
 from ._cachekey import generate_key
diff --git a/src/buildstream/storage/directory.py b/src/buildstream/storage/directory.py
index 89d20c433..2d3dfd4da 100644
--- a/src/buildstream/storage/directory.py
+++ b/src/buildstream/storage/directory.py
@@ -34,7 +34,8 @@ See also: :ref:`sandboxing`.
 
 from typing import Callable, Optional, Union
 
-from .._exceptions import BstError, ErrorDomain
+from .._exceptions import BstError
+from ..exceptions import ErrorDomain
 from ..types import FastEnum
 from ..utils import BST_ARBITRARY_TIMESTAMP, FileListResult
 
diff --git a/src/buildstream/testing/__init__.py b/src/buildstream/testing/__init__.py
index 67e96885a..46cadbbfa 100644
--- a/src/buildstream/testing/__init__.py
+++ b/src/buildstream/testing/__init__.py
@@ -21,6 +21,7 @@ This package contains various utilities which make it easier to test plugins.
 
 import os
 from collections import OrderedDict
+from buildstream.exceptions import ErrorDomain, LoadErrorReason
 from .repo import Repo
 from .runcli import cli, cli_integration, cli_remote_execution
 from .integration import integration_cache
diff --git a/src/buildstream/testing/_sourcetests/mirror.py b/src/buildstream/testing/_sourcetests/mirror.py
index 3ff3fb981..de05b894c 100644
--- a/src/buildstream/testing/_sourcetests/mirror.py
+++ b/src/buildstream/testing/_sourcetests/mirror.py
@@ -23,7 +23,7 @@ import os
 import pytest
 
 from buildstream import _yaml
-from buildstream._exceptions import ErrorDomain
+from buildstream.exceptions import ErrorDomain
 from .._utils import generate_junction
 from .. import create_repo
 from .. import cli  # pylint: disable=unused-import
diff --git a/src/buildstream/testing/_sourcetests/track.py b/src/buildstream/testing/_sourcetests/track.py
index 623045cd9..ecb508b1a 100644
--- a/src/buildstream/testing/_sourcetests/track.py
+++ b/src/buildstream/testing/_sourcetests/track.py
@@ -23,7 +23,7 @@ import os
 import pytest
 
 from buildstream import _yaml
-from buildstream._exceptions import ErrorDomain
+from buildstream.exceptions import ErrorDomain
 from .._utils import generate_junction
 from .. import create_repo
 from .. import cli  # pylint: disable=unused-import
diff --git a/src/buildstream/utils.py b/src/buildstream/utils.py
index 545816e89..88314b263 100644
--- a/src/buildstream/utils.py
+++ b/src/buildstream/utils.py
@@ -41,7 +41,8 @@ from typing import Callable, IO, Iterable, Iterator, Optional, Tuple, Union
 import psutil
 
 from . import _signals
-from ._exceptions import BstError, ErrorDomain
+from ._exceptions import BstError
+from .exceptions import ErrorDomain
 from ._protos.build.bazel.remote.execution.v2 import remote_execution_pb2
 
 # Contains utils that have been rewritten in Cython for speed benefits