Allow TaskExtensions to control TaskContext creation (#725)

This non-breaking API change to the TaskExtension plugin allows tasks to
control the creation of TaskContext instances, which are then used to
create Job instances for execution.

In particular this allows tasks to schedule any number of jobs, where
they currently always schedule one.

Author: cottsay

colcon_core/task/__init__.py

@@ -1,6 +1,7 @@
 # Copyright 2016-2018 Dirk Thomas
 # Licensed under the Apache License, Version 2.0
 
+from collections import OrderedDict
 import os
 import shutil
 import sys
@@ -60,7 +61,33 @@ class TaskExtensionPoint:
     """
 
     """The version of the task extension interface."""
-    EXTENSION_POINT_VERSION = '1.0'
+    EXTENSION_POINT_VERSION = '1.1'
+
+    @classmethod
+    def create_contexts(cls, *, pkg, args, dependencies):
+        """
+        Construct TaskContext instances for a package.
+
+        A :py:class:`~colcon_core.executor.Job` will be created for each
+        :py:class:`~colcon_core.task.TaskContext` that is returned from this
+        method, with :py:attr:`~colcon_core.executor.Job.identifier`
+        corresponding to the key. Implementations may return any number of
+        jobs, but care should be taken to ensure that only one of the jobs is
+        executed at any given time, presumably by ensuring that dependencies
+        exist between them.
+
+        :param pkg: The package descriptor
+        :param args: The parsed command line arguments
+        :param dependencies: The ordered dictionary mapping dependency names to
+          their paths
+        :returns: Mapping of job identifier to task context
+        :rtype: collections.OrderedDict
+        """
+        return OrderedDict((
+            (pkg.name, TaskContext(
+                pkg=pkg, args=args,
+                dependencies=dependencies)),
+        ))
 
     def add_arguments(self, *, parser):
         """

colcon_core/verb/build.py

@@ -25,7 +25,6 @@
 from colcon_core.shell import get_shell_extensions
 from colcon_core.task import add_task_arguments
 from colcon_core.task import get_task_extension
-from colcon_core.task import TaskContext
 from colcon_core.verb import check_and_mark_build_tool
 from colcon_core.verb import check_and_mark_install_layout
 from colcon_core.verb import logger
@@ -201,16 +200,17 @@ def _get_jobs(self, args, decorators, install_base):
             logger.debug(
                 f"Building package '{pkg.name}' with the following arguments: "
                 f'{{{ordered_package_args}}}')
-            task_context = TaskContext(
+            task_contexts = extension.create_contexts(
                 pkg=pkg, args=package_args,
                 dependencies=recursive_dependencies)
 
-            job = Job(
-                identifier=pkg.name,
-                dependencies=set(recursive_dependencies.keys()),
-                task=extension, task_context=task_context)
+            for identifier, task_context in task_contexts.items():
+                job = Job(
+                    identifier=identifier,
+                    dependencies=set(task_context.dependencies.keys()),
+                    task=extension, task_context=task_context)
 
-            jobs[pkg.name] = job
+                jobs[identifier] = job
         return jobs, unselected_packages
 
     def _create_prefix_scripts(self, install_base, merge_install):

colcon_core/verb/test.py

@@ -24,7 +24,6 @@
 from colcon_core.plugin_system import satisfies_version
 from colcon_core.task import add_task_arguments
 from colcon_core.task import get_task_extension
-from colcon_core.task import TaskContext
 from colcon_core.verb import check_and_mark_build_tool
 from colcon_core.verb import check_and_mark_install_layout
 from colcon_core.verb import update_object
@@ -211,16 +210,18 @@ def _get_jobs(self, args, decorators, install_base):
             logger.debug(
                 f"Testing package '{pkg.name}' with the following arguments: "
                 f'{{{ordered_package_args}}}')
-            task_context = TaskContext(
+            task_contexts = extension.create_contexts(
                 pkg=pkg, args=package_args,
                 dependencies=recursive_dependencies)
 
-            job = Job(
-                identifier=pkg.name,
-                dependencies=set(
-                    () if drop_test_deps else recursive_dependencies.keys()
-                ),
-                task=extension, task_context=task_context)
+            for identifier, task_context in task_contexts.items():
+                job = Job(
+                    identifier=identifier,
+                    dependencies=set(
+                        () if drop_test_deps
+                        else task_context.dependencies.keys()
+                    ),
+                    task=extension, task_context=task_context)
 
-            jobs[pkg.name] = job
+                jobs[identifier] = job
         return jobs