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())
    value_different = next(api.consume(SomeModel), 'yadda')

def some_function_now():
    value = api.consume_first(SomeModel)
    value_other api.consume_first_default(SomeModel)
    value_different = api.consume_first(SomeModel, 'yadda')
```

Signed-off-by: Vinzenz Feenstra <vfeenstr@redhat.com>

leapp/actors/__init__.py

@@ -324,6 +324,35 @@ def produce(self, *models):
                                      'explicitely in the actor\'s "produces" tuple. The message will be ignored'.format(
                                          type(model)))
 
+    def consume_first_default(self, model):
+        """
+        Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+        types by model. This additionally returns as fallback value an instance of model with the default
+        initialization
+
+        :param model: Model to use as a filter for the messages to return
+        :type model: A derived class from :py:class:`leapp.models.Model`
+        :return: The first message of the specified model produced by other a fallback instance of model
+        :rtype: The message or a default initialized instance of the model type.
+        """
+        return self.consume_first(model, default=model())
+
+    def consume_first(self, model, default=None):
+        """
+        Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+        types by model.
+
+        :param model: Model to use as a filter for the messages to return
+        :type model: A derived class from :py:class:`leapp.models.Model`
+        :param default: Fallback value in case there are no messages
+        :type default: Any
+        :return: The first message of the specified model 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.
+        return next((message for message in self.consume(model)), 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,35 @@ def produce(*model_instances):
     return current_actor().produce(*model_instances)
 
 
+def consume_first_default(model):
+    """
+    Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+    types by model. This additionally returns as fallback value an instance of model with the default
+    initialization
+
+    :param model: Model to use as a filter for the messages to return
+    :type model: A derived class from :py:class:`leapp.models.Model`
+    :return: The first message of the specified model produced by other a fallback instance of model
+    :rtype: The message or a default initialized instance of the model type.
+    """
+    return current_actor().consume_first_default(model)
+
+
+def consume_first(model, default=None):
+    """
+    Retrieves the first message found as specified in the actors :py:attr:`consumes` attribute, and filter message
+    types by model.
+
+    :param model: Model to use as a filter for the messages to return
+    :type model: A derived class from :py:class:`leapp.models.Model`
+    :param default: Fallback value in case there are no messages
+    :type default: Any
+    :return: The first message of the specified model produced by other actors or the value passed as `default`
+    :rtype: The message or the value passed as ``default``
+    """
+    return current_actor().consume_first(model=model, default=default)
+
+
 def consume(*models):
     """
     Retrieve messages specified in the actors :py:attr:`consumes` attribute, and filter message types by

tests/data/actor-api-tests/models/apitest.py

@@ -5,7 +5,7 @@
 class ApiTest(Model):
     topic = ApiTestTopic
 
-    data = fields.String()
+    data = fields.String(default='not-filled')
 
 
 class ApiTestProduce(ApiTest):

tests/scripts/test_actor_api.py

@@ -72,13 +72,24 @@ 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 api.consume_first_default(ApiTestConsume).data == 'not-filled'
+        assert actor.consume_first_default(ApiTestConsume).data == 'not-filled'
+        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)