api: Add consume_first for convenience

A lot of actors are expecting only one type and are using next to
retrieve the value. This patch introduces a convenience function that is
simplifying the usage for actors that have a need for this.

Additionally it covers some gotchas that are mostly not handled, mainly
if there is no message available then an empty tuple is returned that is
not iterable by next.

Usage example:
--------------

```
from leapp.libraries.stdlib import api
from leapp.models import SomeModel

def some_function_previously():
    value = next(api.consume(SomeModel), None)
    value_other = next(api.consume(SomeModel), SomeModel())

def some_function_now():
    value = api.consume_first(SomeModel)
    value_other api.consume_first(SomeModel, default=SomeModel())
```

Signed-off-by: Vinzenz Feenstra <[email protected]>

leapp/actors/__init__.py

@@ -324,6 +324,23 @@ def produce(self, *models):
                                      'explicitely in the actor\'s "produces" tuple. The message will be ignored'.format(
                                          type(model)))
 
+    def consume_first(self, *models, **kwargs):
+        """
+        Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+        types by models.
+
+        :param models: Models to use as a filter for the messages to return
+        :type models: Variable number of the derived classes from :py:class:`leapp.models.Model`
+        :param default: Fallback value in case there are no messages
+        :type default: Any
+        :return: One messages of the specified model(s) produced by other actors or the value passed as `default`
+        :rtype: The message or the value passed as ``default``
+        """
+        # One cannot iterate over tuples, so we make a generator that iterates over the value returned by self.consume.
+        # This way we can workaround both cases.
+        default = kwargs.get('default')
+        return next((message for message in self.consume(*models)), default)
+
     def consume(self, *models):
         """
         Retrieve messages specified in the actors :py:attr:`consumes` attribute, and filter message types by

leapp/libraries/stdlib/api.py

@@ -65,6 +65,21 @@ def produce(*model_instances):
     return current_actor().produce(*model_instances)
 
 
+def consume_first(*models, **kwargs):
+    """
+    Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+    types by models.
+
+    :param models: Models to use as a filter for the messages to return
+    :type models: Variable number of the derived classes from :py:class:`leapp.models.Model`
+    :param default: Fallback value in case there are no messages
+    :type default: Any
+    :return: One messages of the specified model(s) produced by other actors or the value passed as `default`
+    :rtype: The message or the value passed as ``default``
+    """
+    return current_actor().consume_first(*models, **kwargs)
+
+
 def consume(*models):
     """
     Retrieve messages specified in the actors :py:attr:`consumes` attribute, and filter message types by

tests/scripts/test_actor_api.py

@@ -72,13 +72,22 @@ def test_actor_messaging_paths(leapp_forked, repository, actor_name):
     messaging = _TestableMessaging()
     with _with_loaded_actor(repository, actor_name, messaging) as (_unused, actor):
         from leapp.models import ApiTestConsume, ApiTestProduce
+        assert len(list(actor.consume(ApiTestConsume))) == 0
+        assert next(actor.consume(ApiTestConsume), None) is None
+        assert actor.consume_first(ApiTestConsume) is None
+        assert api.consume_first(ApiTestConsume) is None
+        assert actor.consume_first(ApiTestConsume, default='default') == 'default'
+        assert api.consume_first(ApiTestConsume, default='default') == 'default'
+
         messaging.feed(ApiTestConsume(data='prefilled'), actor)
 
         assert len(list(actor.consume(ApiTestConsume))) == 1
         assert next(actor.consume(ApiTestConsume)).data == 'prefilled'
+        assert actor.consume_first(ApiTestConsume).data == 'prefilled'
 
         assert len(list(api.consume(ApiTestConsume))) == 1
         assert next(api.consume(ApiTestConsume)).data == 'prefilled'
+        assert api.consume_first(ApiTestConsume).data == 'prefilled'
 
         actor_message = 'Actor {} sent message via Actor'.format(actor_name)
         api_message = 'Actor {} sent message via API'.format(actor_name)