element.py: Hide dependencies which are irrelevant to the Element

This is a large breaking change, a summary of the changes are that:

  * The Scope type is now private, since Element plugins do not have
    the choice to view any other scopes.

  * Element.dependencies() API change

    Now it accepts a "selection" (sequence) of dependency elements, so
    that Element.dependencies() can iterate over a collection of dependencies,
    ensuring that we iterate over every element only once even when we
    need to iterate over multiple element's dependencies.

    The old API is moved to Element._dependencies() and still used internally.

  * Element.stage_dependency_artifacts() API change

    This gets the same treatment as Element.dependencies(), and the old
    API is also preserved as Element._stage_dependency_artifacts(), so
    that the CLI can stage things for `bst artifact checkout` and such.

  * Element.search() API change

    The Scope argument is removed, and the old API is preserved as
    Element._search() temporarily, until we can remove this completely.

1 files changed, 28 insertions, 26 deletions

diff --git a/src/buildstream/types.py b/src/buildstream/types.py
index cf76defbd..3b1f7a4db 100644
--- a/src/buildstream/types.py
+++ b/src/buildstream/types.py
@@ -88,32 +88,6 @@ class FastEnum(metaclass=MetaFastEnum):
         return self.__class__, (self.value,)
 
 
-class Scope(FastEnum):
-    """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
-    all elements required for building. Including the element itself.
-    """
-
-    BUILD = 2
-    """All elements required for building the element, including their
-    respective run dependencies. Not including the given element itself.
-    """
-
-    RUN = 3
-    """All elements required for running the element. Including the element
-    itself.
-    """
-
-    NONE = 4
-    """Just the element itself, no dependencies.
-    """
-
-
 class CoreWarnings:
     """CoreWarnings()
 
@@ -145,6 +119,34 @@ class CoreWarnings:
     """
 
 
+# _Scope():
+#
+# Defines the scope of dependencies to include for a given element
+# when iterating over the dependency graph in APIs like
+# Element._dependencies().
+#
+class _Scope(FastEnum):
+
+    # All elements which the given element depends on, following
+    # all elements required for building. Including the element itself.
+    #
+    ALL = 1
+
+    # All elements required for building the element, including their
+    # respective run dependencies. Not including the given element itself.
+    #
+    BUILD = 2
+
+    # All elements required for running the element. Including the element
+    # itself.
+    #
+    RUN = 3
+
+    # Just the element itself, no dependencies.
+    #
+    NONE = 4
+
+
 # _KeyStrength():
 #
 # Strength of cache key