Merge branch 'tristan/refactor-types-api' into 'master'

Refactor types api

See merge request BuildStream/buildstream!870

6 files changed, 54 insertions, 47 deletions

diff --git a/buildstream/__init__.py b/buildstream/__init__.py
index 0f6efb0da..af2122ef7 100644
--- a/buildstream/__init__.py
+++ b/buildstream/__init__.py
@@ -28,9 +28,9 @@ if "_BST_COMPLETION" not in os.environ:
 
     from .utils import UtilError, ProgramNotFoundError
     from .sandbox import Sandbox, SandboxFlags
+    from .types import Scope, Consistency
     from .plugin import Plugin
-    from .source import Source, SourceError, Consistency, SourceFetcher
+    from .source import Source, SourceError, SourceFetcher
     from .element import Element, ElementError
-    from .element_enums import Scope
     from .buildelement import BuildElement
     from .scriptelement import ScriptElement
diff --git a/buildstream/_artifactcache/artifactcache.py b/buildstream/_artifactcache/artifactcache.py
index 6a9b57f2c..ecb5738d7 100644
--- a/buildstream/_artifactcache/artifactcache.py
+++ b/buildstream/_artifactcache/artifactcache.py
@@ -21,7 +21,7 @@ import os
 import string
 from collections import Mapping, namedtuple
 
-from ..element_enums import _KeyStrength
+from ..types import _KeyStrength
 from .._exceptions import ArtifactError, ImplError, LoadError, LoadErrorReason
 from .._message import Message, MessageType
 from .. import utils
diff --git a/buildstream/element.py b/buildstream/element.py
index aff185405..a77550f9d 100644
--- a/buildstream/element.py
+++ b/buildstream/element.py
@@ -86,7 +86,7 @@ from ._variables import Variables
 from ._versions import BST_CORE_ARTIFACT_VERSION
 from ._exceptions import BstError, LoadError, LoadErrorReason, ImplError, ErrorDomain
 from .utils import UtilError
-from . import Plugin, Consistency
+from . import Plugin, Consistency, Scope
 from . import SandboxFlags
 from . import utils
 from . import _cachekey
@@ -96,11 +96,11 @@ from ._platform import Platform
 from .plugin import CoreWarnings
 from .sandbox._config import SandboxConfig
 from .sandbox._sandboxremote import SandboxRemote
+from .types import _KeyStrength
 
 from .storage.directory import Directory
 from .storage._filebaseddirectory import FileBasedDirectory
 from .storage.directory import VirtualDirectoryError
-from .element_enums import _KeyStrength, Scope
 
 
 class ElementError(BstError):
diff --git a/buildstream/source.py b/buildstream/source.py
index 6768f6cfc..30883430a 100644
--- a/buildstream/source.py
+++ b/buildstream/source.py
@@ -145,35 +145,12 @@ import os
 from collections import Mapping
 from contextlib import contextmanager
 
-from . import Plugin
+from . import Plugin, Consistency
 from . import _yaml, utils
 from ._exceptions import BstError, ImplError, ErrorDomain
 from ._projectrefs import ProjectRefStorage
 
 
-class Consistency():
-    INCONSISTENT = 0
-    """Inconsistent
-
-    Inconsistent sources have no explicit reference set. They cannot
-    produce a cache key, be fetched or staged. They can only be tracked.
-    """
-
-    RESOLVED = 1
-    """Resolved
-
-    Resolved sources have a reference and can produce a cache key and
-    be fetched, however they cannot be staged.
-    """
-
-    CACHED = 2
-    """Cached
-
-    Cached sources have a reference which is present in the local
-    source cache. Only cached sources can be staged.
-    """
-
-
 class SourceError(BstError):
     """This exception should be raised by :class:`.Source` implementations
     to report errors to the user.
diff --git a/buildstream/element_enums.py b/buildstream/types.py
index 2f2fb54d2..7bc7a1664 100644
--- a/buildstream/element_enums.py
+++ b/buildstream/types.py
@@ -19,31 +19,19 @@
 #        Jim MacArthur <jim.macarthur@codethink.co.uk>
 
 """
-Element - Globally visible enumerations
-=======================================
+Foundation types
+================
 
 """
 
 from enum import Enum
 
 
-# _KeyStrength():
-#
-# Strength of cache key
-#
-class _KeyStrength(Enum):
-
-    # Includes strong cache keys of all build dependencies and their
-    # runtime dependencies.
-    STRONG = 1
-
-    # Includes names of direct build dependencies but does not include
-    # cache keys of dependencies.
-    WEAK = 2
-
-
 class Scope(Enum):
-    """Types of scope for a given element"""
+    """Defines the scope of dependencies to include for a given element
+    when iterating over the dependency graph in APIs like
+    :func:`Element.dependencies() <buildstream.element.Element.dependencies>`
+    """
 
     ALL = 1
     """All elements which the given element depends on, following
@@ -59,3 +47,44 @@ class Scope(Enum):
     """All elements required for running the element. Including the element
     itself.
     """
+
+
+class Consistency():
+    """Defines the various consistency states of a :class:`.Source`.
+    """
+
+    INCONSISTENT = 0
+    """Inconsistent
+
+    Inconsistent sources have no explicit reference set. They cannot
+    produce a cache key, be fetched or staged. They can only be tracked.
+    """
+
+    RESOLVED = 1
+    """Resolved
+
+    Resolved sources have a reference and can produce a cache key and
+    be fetched, however they cannot be staged.
+    """
+
+    CACHED = 2
+    """Cached
+
+    Cached sources have a reference which is present in the local
+    source cache. Only cached sources can be staged.
+    """
+
+
+# _KeyStrength():
+#
+# Strength of cache key
+#
+class _KeyStrength(Enum):
+
+    # Includes strong cache keys of all build dependencies and their
+    # runtime dependencies.
+    STRONG = 1
+
+    # Includes names of direct build dependencies but does not include
+    # cache keys of dependencies.
+    WEAK = 2
diff --git a/doc/source/core_framework.rst b/doc/source/core_framework.rst
index c3b84a9b1..a66f3640f 100644
--- a/doc/source/core_framework.rst
+++ b/doc/source/core_framework.rst
@@ -12,6 +12,7 @@ useful for working on BuildStream itself.
 .. toctree::
    :maxdepth: 1
 
+   buildstream.types
    buildstream.plugin
    buildstream.source
    buildstream.element