Migrates legacy launch API tests

launch/launch/action.py

@@ -56,7 +56,21 @@ def describe(self) -> Text:
     def visit(self, context: LaunchContext) -> Optional[List[LaunchDescriptionEntity]]:
         """Override visit from LaunchDescriptionEntity so that it executes."""
         if self.__condition is None or self.__condition.evaluate(context):
-            return cast(Optional[List[LaunchDescriptionEntity]], self.execute(context))
+            try:
+                return cast(Optional[List[LaunchDescriptionEntity]], self.execute(context))
+            finally:
+                from .events import ExecutionComplete  # noqa
+                future = self.get_asyncio_future()
+                if future is not None:
+                    future.add_done_callback(
+                        lambda _: context.emit_event_sync(
+                            ExecutionComplete(action=self)
+                        )
+                    )
+                else:
+                    context.emit_event_sync(
+                        ExecutionComplete(action=self)
+                    )
         return None
 
     def execute(self, context: LaunchContext) -> Optional[List['Action']]:

launch/launch/actions/__init__.py

@@ -20,6 +20,7 @@
 from .group_action import GroupAction
 from .include_launch_description import IncludeLaunchDescription
 from .log_info import LogInfo
+from .opaque_coroutine import OpaqueCoroutine
 from .opaque_function import OpaqueFunction
 from .pop_launch_configurations import PopLaunchConfigurations
 from .push_launch_configurations import PushLaunchConfigurations
@@ -36,6 +37,7 @@
     'GroupAction',
     'IncludeLaunchDescription',
     'LogInfo',
+    'OpaqueCoroutine',
     'OpaqueFunction',
     'PopLaunchConfigurations',
     'PushLaunchConfigurations',

launch/launch/actions/execute_process.py

@@ -42,7 +42,7 @@
 from ..event_handler import EventHandler
 from ..event_handlers import OnShutdown
 from ..events import Shutdown
-from ..events.process import matches_action
+from ..events import matches_action
 from ..events.process import ProcessExited
 from ..events.process import ProcessStarted
 from ..events.process import ProcessStderr

launch/launch/actions/opaque_coroutine.py

@@ -0,0 +1,89 @@
+# Copyright 2019 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module for the OpaqueCoroutine action."""
+
+import asyncio
+import collections.abc
+from typing import Any
+from typing import Coroutine
+from typing import Dict
+from typing import Iterable
+from typing import List
+from typing import Optional
+from typing import Text
+
+from ..action import Action
+from ..launch_context import LaunchContext
+from ..utilities import ensure_argument_type
+
+
+class OpaqueCoroutine(Action):
+    """
+    Action that adds a Python coroutine to the launch run loop.
+
+    The signature of a coroutine should be:
+
+    .. code-block:: python
+
+        async def coroutine(
+            context: LaunchContext,  # iff ignore_context is False
+            *args,
+            **kwargs
+        ):
+            ...
+    """
+
+    def __init__(
+        self, *,
+        coroutine: Coroutine,
+        args: Optional[Iterable[Any]] = None,
+        kwargs: Optional[Dict[Text, Any]] = None,
+        ignore_context: bool = False,
+        **left_over_kwargs
+    ) -> None:
+        """Constructor."""
+        super().__init__(**left_over_kwargs)
+        if not asyncio.iscoroutinefunction(coroutine):
+            raise TypeError("OpaqueCoroutine expected a couroutine function for 'couroutine', got '{}'".format(
+                type(function)
+            ))
+        ensure_argument_type(
+            args, (collections.abc.Iterable, type(None)), 'args', 'OpaqueCoroutine'
+        )
+        ensure_argument_type(kwargs, (dict, type(None)), 'kwargs', 'OpaqueCoroutine')
+        ensure_argument_type(ignore_context, bool, 'ignore_context', 'OpaqueCoroutine')
+        self.__coroutine = coroutine
+        self.__args = []  # type: Iterable
+        if args is not None:
+            self.__args = args
+        self.__kwargs = {}  # type: Dict[Text, Any]
+        if kwargs is not None:
+            self.__kwargs = kwargs
+        self.__ignore_context = ignore_context  # type: bool
+        self.__future = None  # type: Optional[asyncio.Future]
+
+    def execute(self, context: LaunchContext) -> Optional[List[Action]]:
+        """Execute the action."""
+        args = self.__args
+        if not self.__ignore_context:
+            args = [context, *self.__args]
+        self.__future = context.asyncio_loop.create_task(
+            self.__coroutine(*args, **self.__kwargs)
+        )
+        return None
+
+    def get_asyncio_future(self) -> Optional[asyncio.Future]:
+        """Return an asyncio Future, used to let the launch system know when we're done."""
+        return self.__future

launch/launch/event_handlers/__init__.py

@@ -15,13 +15,15 @@
 """Package for event_handlers."""
 
 from .event_named import event_named
+from .on_execution_complete import OnExecutionComplete
 from .on_include_launch_description import OnIncludeLaunchDescription
 from .on_process_exit import OnProcessExit
 from .on_process_io import OnProcessIO
 from .on_shutdown import OnShutdown
 
 __all__ = [
     'event_named',
+    'OnExecutionComplete',
     'OnIncludeLaunchDescription',
     'OnProcessExit',
     'OnProcessIO',

launch/launch/event_handlers/on_execution_complete.py

@@ -0,0 +1,122 @@
+# Copyright 2019 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import collections.abc
+from typing import Callable
+from typing import cast
+from typing import List  # noqa
+from typing import Optional
+from typing import overload
+from typing import Text
+
+from ..event import Event
+from ..events import ExecutionComplete
+from ..event_handler import EventHandler
+from ..launch_context import LaunchContext
+from ..launch_description_entity import LaunchDescriptionEntity
+from ..some_actions_type import SomeActionsType
+
+
+class OnExecutionComplete(EventHandler):
+    """
+    Convenience class for handling an action completion event.
+
+    It may be configured to only handle the completion of a specific action,
+    or to handle them all.
+    """
+
+    @overload
+    def __init__(
+        self, *,
+        target_action: Optional['Action'] = None,
+        on_completion: SomeActionsType,
+        **kwargs
+    ) -> None:
+        """Overload which takes just actions."""
+        ...
+
+    @overload  # noqa: F811
+    def __init__(
+        self,
+        *,
+        target_action: Optional['Action'] = None,
+        on_completion: Callable[[int], Optional[SomeActionsType]],
+        **kwargs
+    ) -> None:
+        """Overload which takes a callable to handle completion."""
+        ...
+
+    def __init__(self, *, target_action=None, on_completion, **kwargs) -> None:  # noqa: F811
+        """Constructor."""
+        from ..action import Action  # noqa
+        if not isinstance(target_action, (Action, type(None))):
+            raise RuntimeError("OnExecutionComplete requires an 'Action' as the target")
+        super().__init__(
+            matcher=(
+                lambda event: (
+                    isinstance(event, ExecutionComplete) and (
+                        target_action is None or
+                        event.action == target_action
+                    )
+                )
+            ),
+            entities=None,
+            **kwargs,
+        )
+        self.__target_action = target_action
+        # TODO(wjwwood) check that it is not only callable, but also a callable that matches
+        # the correct signature for a handler in this case
+        self.__on_completion = on_completion
+        self.__actions_on_completion = []  # type: List[LaunchDescriptionEntity]
+        if callable(on_completion):
+            # Then on_completion is a function or lambda, so we can just call it, but
+            # we don't put anything in self.__actions_on_completion because we cannot
+            # know what the function will return.
+            pass
+        else:
+            # Otherwise, setup self.__actions_on_completion
+            if isinstance(on_completion, collections.abc.Iterable):
+                for entity in on_completion:
+                    if not isinstance(entity, LaunchDescriptionEntity):
+                        raise ValueError(
+                            "expected all items in 'on_completion' iterable to be of type "
+                            "'LaunchDescriptionEntity' but got '{}'".format(type(entity)))
+                self.__actions_on_completion = list(on_completion)
+            else:
+                self.__actions_on_completion = [on_completion]
+            # Then return it from a lambda and use that as the self.__on_completion callback.
+            self.__on_completion = lambda event, context: self.__actions_on_completion
+
+    def handle(self, event: Event, context: LaunchContext) -> Optional[SomeActionsType]:
+        """Handle the given event."""
+        return self.__on_completion(cast(ExecutionComplete, event), context)
+
+    @property
+    def handler_description(self) -> Text:
+        """Return the string description of the handler."""
+        # TODO(jacobperron): revisit how to describe known actions that are passed in.
+        #                    It would be nice if the parent class could output their description
+        #                    via the 'entities' property.
+        if self.__actions_on_completion:
+            return '<actions>'
+        return '{}'.format(self.__on_exit)
+
+    @property
+    def matcher_description(self) -> Text:
+        """Return the string description of the matcher."""
+        if self.__target_action is None:
+            return 'event == ExecutionComplete'
+        return 'event == ExecutionComplete and event.action == Action({})'.format(
+            hex(id(self.__target_action))
+        )

launch/launch/events/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2018 Open Source Robotics Foundation, Inc.
+# Copyright 2018-2019 Open Source Robotics Foundation, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,12 +15,16 @@
 """Package for events."""
 
 from . import process
+from .execution_complete import ExecutionComplete
 from .include_launch_description import IncludeLaunchDescription
+from .matchers import matches_action
 from .shutdown import Shutdown
 from .timer_event import TimerEvent
 
 __all__ = [
+    'matches_action',
     'process',
+    'ExecutionComplete',
     'IncludeLaunchDescription',
     'Shutdown',
     'TimerEvent',

launch/launch/events/execution_complete.py

@@ -0,0 +1,32 @@
+# Copyright 2019 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module for ExecutionComplete event."""
+
+from ..event import Event
+
+
+class ExecutionComplete(Event):
+    """Event that is emitted on action execution completion."""
+
+    name = 'launch.events.ExecutionComplete'
+
+    def __init__(self, *, action: 'Action') -> None:
+        """Constructor."""
+        self.__action = action
+
+    @property
+    def action(self):
+        """Getter for action."""
+        return self.__action

launch/launch/events/matchers.py

@@ -0,0 +1,24 @@
+# Copyright 2018 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module for standard "matchers", which are used with Events."""
+
+from typing import Callable
+
+from ..action import Action
+
+
+def matches_action(target_action: 'Action') -> Callable[['Action'], bool]:
+    """Return a matcher which matches based on an exact given ExecuteProcess action."""
+    return lambda action: action == target_action

launch/launch/events/process/__init__.py

@@ -16,7 +16,6 @@
 
 from .process_exited import ProcessExited
 from .process_io import ProcessIO
-from .process_matchers import matches_action
 from .process_matchers import matches_executable
 from .process_matchers import matches_name
 from .process_matchers import matches_pid
@@ -30,7 +29,6 @@
 from .signal_process import SignalProcess
 
 __all__ = [
-    'matches_action',
     'matches_executable',
     'matches_name',
     'matches_pid',

launch/launch/events/process/process_matchers.py

@@ -22,11 +22,6 @@
     from ...actions import ExecuteProcess  # noqa
 
 
-def matches_action(execute_process_action: 'ExecuteProcess') -> Callable[['ExecuteProcess'], bool]:
-    """Return a matcher which matches based on an exact given ExecuteProcess action."""
-    return lambda action: action == execute_process_action
-
-
 def matches_pid(pid: int) -> Callable[['ExecuteProcess'], bool]:
     """Return a matcher which matches based on the pid of the process."""
     def matcher(action: 'ExecuteProcess') -> bool:

launch/launch/events/process/process_targeted_event.py

@@ -34,7 +34,7 @@ def __init__(self, *, process_matcher: Callable[['ExecuteProcess'], bool]) -> No
 
         Some standard matchers are also available, like:
 
-        - :func:`launch.events.process.matches_action()`
+        - :func:`launch.events.matches_action()`
         - :func:`launch.events.process.matches_pid()`
         - :func:`launch.events.process.matches_name()`
         - :func:`launch.events.process.matches_executable()`