document test loop

Author: maxfischer2781

docs/index.rst

@@ -57,6 +57,7 @@ The missing ``async`` toolbox
    :hidden:
 
    source/devel/contributing
+   source/devel/testloop
    source/devel/publishing
 
 The ``asyncstdlib`` library re-implements functions and classes of the Python

docs/source/devel/testloop.rst

@@ -0,0 +1,32 @@
+===============
+Test Event Loop
+===============
+
+.. py:module:: unittests.utility
+    :synopsis: testing utilities
+
+To facilitate event loop agnostic features, :py:mod:`asyncstdlib` includes
+its own custom event loop implementation for testing.
+This is provided as a simple decorator that is compatible with :py:mod:`pytest`,
+as well as a number of `async` commands specific to the event loop.
+
+Event Loops
+===========
+
+There are currently two event loops available for either simplicity or concurrency.
+In case of doubt, prefer :py:func:`~.multi_sync`.
+
+.. autofunction:: sync(test_case: (...) -> (await) None) -> (...) -> None
+
+.. autofunction:: multi_sync(test_case: (...) -> (await) None) -> (...) -> None
+
+Async commands
+==============
+
+.. autoclass:: PingPong
+
+.. autoclass:: Schedule(*await Any)
+
+.. autoclass:: Switch
+
+.. autoclass:: Lock

unittests/utility.py

@@ -50,7 +50,7 @@ class PingPong:
 
     The coroutine yields to the event loop but is resumed
     immediately, without running others in the meantime.
-    This is mainly useful for debugging the event loop.
+    This is mainly useful for ensuring the event loop is used.
     """
 
     def __await__(self) -> "Generator[PingPong, Any, Any]":
@@ -68,7 +68,8 @@ def sync(test_case: Callable[..., Coroutine[None, Any, Any]]) -> Callable[..., N
     Mark an ``async def`` test case to be run synchronously
 
     This emulates a primitive "event loop" which only responds
-    to the :py:class:`PingPong` by sending it back.
+    to the :py:class:`PingPong` by sending it back. This loop
+    is appropriate for tests that do not check concurrency.
     """
 
     @wraps(test_case)
@@ -145,14 +146,21 @@ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any):
 
 
 def multi_sync(
-    test_case: Callable[..., Coroutine[None, Any, Any]]
+    test_case: Callable[..., Coroutine[None, Any, Any]], /
 ) -> Callable[..., None]:
     """
     Mark an ``async def`` test case to be run synchronously with children
 
-    This emulates a primitive "event loop" which only responds
+    This provides a primitive "event loop" which only responds
     to the :py:class:`PingPong`, :py:class:`Schedule`, :py:class:`Switch`
-    and :py:class:`Lock`.
+    and :py:class:`Lock`. This loop is appropriate for tests that need
+    to check concurrency.
+
+    It should be applied as a decorator on an ``async def`` function, which
+    is then turned into a synchronous callable that will run the ``async def``
+    function and all tasks it spawns.
+    Other decorators, most prominently :py:func:`pytest.mark.parametrize`,
+    can be applied around it.
     """
 
     @wraps(test_case)