AsyncMock

Enhance :class:`Mock` with features allowing to mock
an async function.

The :class:`AsyncMock` object will behave so the object is
recognized as an async function, and the result of a call is an awaitable:

>>> mock = AsyncMock()
>>> inspect.iscoroutinefunction(mock)
True
>>> inspect.isawaitable(mock())
True


The result of ``mock()`` is an async function which will have the outcome
of ``side_effect`` or ``return_value``:

- if ``side_effect`` is a function, the async function will return the
  result of that function,
- if ``side_effect`` is an exception, the async function will raise the
  exception,
- if ``side_effect`` is an iterable, the async function will return the
  next value of the iterable, however, if the sequence of result is
  exhausted, ``StopIteration`` is raised immediately,
- if ``side_effect`` is not defined, the async function will return the
  value defined by ``return_value``, hence, by default, the async function
  returns a new :class:`AsyncMock` object.

If the outcome of ``side_effect`` or ``return_value`` is an async function,
the mock async function obtained when the mock object is called will be this
async function itself (and not an async function returning an async
function).

The test author can also specify a wrapped object with ``wraps``. In this
case, the :class:`Mock` object behavior is the same as with an
:class:`.Mock` object: the wrapped object may have methods
defined as async function functions.

Based on Martin Richard's asynctest project.