Test Revisions for Requirements output (#101)

*Adjusted device-iothub client tests (except for auth - that's a future PR)
*Adjusted device-common tests
*Added additional tests
*Made minor adjustments to implementation

Author: cartertinney

azure-iot-device/azure/iot/device/common/async_adapter.py

@@ -10,8 +10,10 @@
 
 
 def emulate_async(fn):
-    """Apply as a decorator to emulate async behavior with a sync function/method
-    via usage of multithreading.
+    """Returns a coroutine function that calls a given function with emulated asynchronous
+    behavior via use of mulithreading.
+
+    Can be applied as a decorator.
 
     :param fn: The sync function to be run in async.
     :returns: A coroutine function that will call the given sync function.

azure-iot-device/azure/iot/device/common/sastoken.py

@@ -11,8 +11,6 @@
 import time
 import six.moves.urllib as urllib
 
-__all__ = ["SasToken", "SasTokenError"]
-
 
 class SasTokenError(Exception):
     """Error in SasToken"""
@@ -55,7 +53,7 @@ def __init__(self, uri, key, key_name=None, ttl=3600):
         self.ttl = ttl
         self.refresh()
 
-    def __repr__(self):
+    def __str__(self):
         return self._token
 
     def refresh(self):

azure-iot-device/azure/iot/device/iothub/aio/async_clients.py

@@ -243,7 +243,7 @@ def sync_callback():
 
         callback = async_adapter.AwaitableCallback(sync_callback)
 
-        await send_output_event_async(message, callback)
+        await send_output_event_async(message, callback=callback)
         await callback.completion()
 
     async def receive_input_message(self, input_name):

azure-iot-device/azure/iot/device/iothub/models/message.py

@@ -7,6 +7,7 @@
 """
 
 
+# TODO: Revise this class. Does all of this REALLY need to be here?
 class Message(object):
     """Represents a message to or from IoTHub
 
@@ -52,3 +53,6 @@ def __init__(
         self.content_encoding = content_encoding
         self.content_type = content_type
         self.output_name = output_name
+
+    def __str__(self):
+        return str(self.data)

azure-iot-device/azure/iot/device/iothub/sync_clients.py

@@ -8,7 +8,7 @@
 """
 
 import logging
-from threading import Event
+import threading
 from .abstract_clients import (
     AbstractIoTHubClient,
     AbstractIoTHubDeviceClient,
@@ -66,7 +66,7 @@ def connect(self):
         """
         logger.info("Connecting to Hub...")
 
-        connect_complete = Event()
+        connect_complete = threading.Event()
 
         def callback():
             connect_complete.set()
@@ -83,7 +83,7 @@ def disconnect(self):
         """
         logger.info("Disconnecting from Hub...")
 
-        disconnect_complete = Event()
+        disconnect_complete = threading.Event()
 
         def callback():
             disconnect_complete.set()
@@ -108,7 +108,7 @@ def send_event(self, message):
             message = Message(message)
 
         logger.info("Sending message to Hub...")
-        send_complete = Event()
+        send_complete = threading.Event()
 
         def callback():
             send_complete.set()
@@ -155,7 +155,7 @@ def send_method_response(self, method_response):
         :type method_response: MethodResponse
         """
         logger.info("Sending method response to Hub...")
-        send_complete = Event()
+        send_complete = threading.Event()
 
         def callback():
             send_complete.set()
@@ -174,7 +174,7 @@ def _enable_feature(self, feature_name):
         See azure.iot.device.common.pipeline.constant for possible values
         """
         logger.info("Enabling feature:" + feature_name + "...")
-        enable_complete = Event()
+        enable_complete = threading.Event()
 
         def callback():
             enable_complete.set()
@@ -312,13 +312,13 @@ def send_to_output(self, message, output_name):
         message.output_name = output_name
 
         logger.info("Sending message to output:" + output_name + "...")
-        send_complete = Event()
+        send_complete = threading.Event()
 
         def callback():
             logger.info("Successfully sent message to output: " + output_name)
             send_complete.set()
 
-        self._pipeline.send_output_event(message, callback)
+        self._pipeline.send_output_event(message, callback=callback)
         send_complete.wait()
 
     def receive_input_message(self, input_name, block=True, timeout=None):

azure-iot-device/tests/common/test_async_adapter.py

@@ -24,15 +24,16 @@ def mock_function(mocker, dummy_value):
     return mock_fn
 
 
+@pytest.mark.describe("emulate_async()")
 class TestEmulateAsync(object):
+    @pytest.mark.it("Returns a coroutine function when given a function")
     async def test_returns_coroutine(self, mock_function):
         async_fn = async_adapter.emulate_async(mock_function)
         assert inspect.iscoroutinefunction(async_fn)
 
-    async def test_coroutine_has_input_function_docstring(self, mock_function):
-        async_fn = async_adapter.emulate_async(mock_function)
-        assert async_fn.__doc__ == mock_function.__doc__
-
+    @pytest.mark.it(
+        "Returns a coroutine function that returns the result of the input function when called"
+    )
     async def test_coroutine_returns_input_function_result(
         self, mocker, mock_function, dummy_value
     ):
@@ -42,8 +43,34 @@ async def test_coroutine_returns_input_function_result(
         assert mock_function.call_args == mocker.call(dummy_value)
         assert result == mock_function.return_value
 
+    @pytest.mark.it("Copies the input function docstring to resulting coroutine function")
+    async def test_coroutine_has_input_function_docstring(self, mock_function):
+        async_fn = async_adapter.emulate_async(mock_function)
+        assert async_fn.__doc__ == mock_function.__doc__
 
+    @pytest.mark.it("Can be applied as a decorator")
+    async def test_applied_as_decorator(self):
+
+        # Define a function with emulate_async applied as a decorator
+        @async_adapter.emulate_async
+        def some_function():
+            return "foo"
+
+        # Call the function as a coroutine
+        result = await some_function()
+        assert result == "foo"
+
+
+@pytest.mark.describe("AwaitableCallback")
 class TestAwaitableCallback(object):
+    @pytest.mark.it("Instantiates from a provided callback function")
+    async def test_instantiates(self, mock_function):
+        callback = async_adapter.AwaitableCallback(mock_function)
+        assert isinstance(callback, async_adapter.AwaitableCallback)
+
+    @pytest.mark.it(
+        "Invokes the callback function associated with an instance and returns its result when a call is invoked the instance"
+    )
     async def test_calling_object_calls_input_function_and_returns_result(
         self, mocker, mock_function
     ):
@@ -53,27 +80,31 @@ async def test_calling_object_calls_input_function_and_returns_result(
         assert mock_function.call_args == mocker.call()
         assert result == mock_function.return_value
 
+    @pytest.mark.it("Completes the instance Future when a call is invoked on the instance")
     async def test_calling_object_completes_future(self, mock_function):
         callback = async_adapter.AwaitableCallback(mock_function)
         assert not callback.future.done()
         callback()
         await asyncio.sleep(0.1)  # wait to give time to complete the callback
         assert callback.future.done()
 
-    async def test_can_be_called_using_args(self, mocker, mock_function):
+    @pytest.mark.it("Can be called using positional arguments")
+    async def test_can_be_called_using_positional_args(self, mocker, mock_function):
         callback = async_adapter.AwaitableCallback(mock_function)
         result = callback(1, 2, 3)
         assert mock_function.call_count == 1
         assert mock_function.call_args == mocker.call(1, 2, 3)
         assert result == mock_function.return_value
 
-    async def test_can_be_called_using_kwargs(self, mocker, mock_function):
+    @pytest.mark.it("Can be called using explicit keyword arguments")
+    async def test_can_be_called_using_explicit_kwargs(self, mocker, mock_function):
         callback = async_adapter.AwaitableCallback(mock_function)
         result = callback(a=1, b=2, c=3)
         assert mock_function.call_count == 1
         assert mock_function.call_args == mocker.call(a=1, b=2, c=3)
         assert result == mock_function.return_value
 
+    @pytest.mark.it("Can have its callback completion awaited upon")
     async def test_awaiting_completion_of_callback_returns_result(self, mock_function):
         callback = async_adapter.AwaitableCallback(mock_function)
         callback()

azure-iot-device/tests/common/test_asyncio_compat.py

@@ -20,7 +20,9 @@ async def coro():
     return coro
 
 
+@pytest.mark.describe("get_running_loop()")
 class TestGetRunningLoop(object):
+    @pytest.mark.it("Returns the currently running Event Loop in Python 3.7 or higher")
     @pytest.mark.skipif(sys.version_info < (3, 7), reason="Requires Python 3.7+")
     async def test_returns_currently_running_event_loop_(self, mocker, event_loop):
         spy_get_running_loop = mocker.spy(asyncio, "get_running_loop")
@@ -29,12 +31,16 @@ async def test_returns_currently_running_event_loop_(self, mocker, event_loop):
         assert spy_get_running_loop.call_count == 1
         assert spy_get_running_loop.call_args == mocker.call()
 
+    @pytest.mark.it(
+        "Raises a RuntimeError if there is no running Event Loop in Python 3.7 or higher"
+    )
     @pytest.mark.skipif(sys.version_info < (3, 7), reason="Requires Python 3.7+")
     async def test_raises_runtime_error_if_no_running_event_loop(self, mocker):
         mocker.patch.object(asyncio, "get_running_loop", side_effect=RuntimeError)
         with pytest.raises(RuntimeError):
             asyncio_compat.get_running_loop()
 
+    @pytest.mark.it("Returns the currently running Event Loop in Python 3.6 or below")
     @pytest.mark.skipif(sys.version_info >= (3, 7), reason="Requires Python 3.6 or below")
     async def test_returns_currently_running_event_loop_py36orless_compat(self, mocker, event_loop):
         spy_get_event_loop = mocker.spy(asyncio, "_get_running_loop")
@@ -43,14 +49,21 @@ async def test_returns_currently_running_event_loop_py36orless_compat(self, mock
         assert spy_get_event_loop.call_count == 1
         assert spy_get_event_loop.call_args == mocker.call()
 
+    @pytest.mark.it(
+        "Raises a RuntimeError if there is no running Event Loop in Python 3.6 or below"
+    )
     @pytest.mark.skipif(sys.version_info >= (3, 7), reason="Requires Python 3.6 or below")
     async def test_raises_runtime_error_if_no_running_event_loop_py36orless_compat(self, mocker):
         mocker.patch.object(asyncio, "_get_running_loop", return_value=None)
         with pytest.raises(RuntimeError, message="Expecting Runtime Error"):
             asyncio_compat.get_running_loop()
 
 
+@pytest.mark.describe("create_task()")
 class TestCreateTask(object):
+    @pytest.mark.it(
+        "Returns a Task that wraps a given coroutine, and schedules its execution, in Python 3.7 or higher"
+    )
     @pytest.mark.skipif(sys.version_info < (3, 7), reason="Requires Python 3.7+")
     async def test_returns_task_wrapping_given_coroutine(self, mocker, dummy_coroutine):
         spy_create_task = mocker.spy(asyncio, "create_task")
@@ -60,6 +73,9 @@ async def test_returns_task_wrapping_given_coroutine(self, mocker, dummy_corouti
         assert spy_create_task.call_count == 1
         assert spy_create_task.call_args == mocker.call(coro_obj)
 
+    @pytest.mark.it(
+        "Returns a Task that wraps a given coroutine, and schedules its execution, in Python 3.6 or below"
+    )
     @pytest.mark.skipif(sys.version_info >= (3, 7), reason="Requires Python 3.6 or below")
     async def test_returns_task_wrapping_given_coroutine_py36orless_compat(
         self, mocker, dummy_coroutine
@@ -72,7 +88,11 @@ async def test_returns_task_wrapping_given_coroutine_py36orless_compat(
         assert spy_ensure_future.call_args == mocker.call(coro_obj)
 
 
+@pytest.mark.describe("create_future()")
 class TestCreateFuture(object):
+    @pytest.mark.it(
+        "Returns a new Future object attached to the given Event Loop, in Python 3.5.2 or higher"
+    )
     @pytest.mark.skipif(sys.version_info < (3, 5, 2), reason="Requires Python 3.5.2+")
     async def test_create_future_for_given_loop(self, mocker, event_loop):
         spy_create_future = mocker.spy(event_loop, "create_future")
@@ -82,6 +102,9 @@ async def test_create_future_for_given_loop(self, mocker, event_loop):
         assert spy_create_future.call_count == 1
         assert spy_create_future.call_args == mocker.call()
 
+    @pytest.mark.it(
+        "Returns a new Future object attached to the given Event Loop, in Python 3.5.1 or below"
+    )
     @pytest.mark.skipif(sys.version_info >= (3, 5, 1), reason="Requires Python 3.5.1 or below")
     async def test_create_future_for_given_loop_py351orless_compat(self, mocker, event_loop):
         spy_future = mocker.spy(asyncio, "Future")