types.py: Moved Consistency definition here from source.py

And slightly touch up the doc strings for Consistency and Scope.

3 files changed, 33 insertions, 27 deletions

diff --git a/buildstream/__init__.py b/buildstream/__init__.py
index 658166a99..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
+    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 .buildelement import BuildElement
     from .scriptelement import ScriptElement
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/types.py b/buildstream/types.py
index 3c27d583a..7bc7a1664 100644
--- a/buildstream/types.py
+++ b/buildstream/types.py
@@ -28,7 +28,10 @@ from enum import Enum
 
 
 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
@@ -46,6 +49,32 @@ class Scope(Enum):
     """
 
 
+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