Added documentation, improved docstrings and rearranged some code

Fixes nedbat#2.

Author: agronholm

README.rst

@@ -1,3 +1,6 @@
+.. image:: https://readthedocs.org/projects/anyio/badge/?version=latest
+  :target: https://anyio.readthedocs.io/en/latest/?badge=latest
+  :alt: Documentation
 .. image:: https://travis-ci.com/agronholm/anyio.svg?branch=master
   :target: https://travis-ci.com/agronholm/anyio
   :alt: Build Status
@@ -15,6 +18,9 @@ It bridges the following functionality:
 * Synchronization primitives (locks, conditions, events, semaphores, queues)
 * High level networking (TCP, UDP and UNIX sockets)
 
+You can even use it together with native libraries from your selected backend in applications.
+Doing this in libraries is not advisable however since it limits the usefulness of your library.
+
 .. _asyncio: https://docs.python.org/3/library/asyncio.html
 .. _curio: https://github.com/dabeaz/curio
 .. _trio: https://github.com/python-trio/trio

anyio/__init__.py

@@ -23,6 +23,41 @@
 _local = threading.local()
 
 
+#
+# Event loop
+#
+
+def run(func: Callable[..., Coroutine[Any, Any, T_Retval]], *args,
+        backend: str = BACKENDS[0], backend_options: Optional[Dict[str, Any]] = None) -> T_Retval:
+    """
+    Run the given coroutine function in an asynchronous event loop.
+
+    The current thread must not be already running an event loop.
+
+    :param func: a coroutine function
+    :param args: positional arguments to ``func``
+    :param backend: name of the asynchronous event loop implementation – one of ``asyncio``,
+        ``curio`` and ``trio``
+    :param backend_options: keyword arguments to call the backend ``run()`` implementation with
+    :return: the return value of the coroutine function
+    :raises RuntimeError: if an asynchronous event loop is already running in this thread
+    :raises LookupError: if the named backend is not found
+
+    """
+    asynclib_name = detect_running_asynclib()
+    if asynclib_name:
+        raise RuntimeError('Already running {} in this thread'.format(asynclib_name))
+
+    try:
+        asynclib = import_module('{}._backends.{}'.format(__name__, backend))
+    except ImportError as exc:
+        raise LookupError('No such backend: {}'.format(backend)) from exc
+
+    backend_options = backend_options or {}
+    with claim_current_thread(asynclib):
+        return asynclib.run(func, *args, **backend_options)
+
+
 @contextmanager
 def claim_current_thread(asynclib) -> None:
     assert ismodule(asynclib)
@@ -33,11 +68,24 @@ def claim_current_thread(asynclib) -> None:
         reset_detected_asynclib()
 
 
-def reset_detected_asynclib():
+def reset_detected_asynclib() -> None:
+    """
+    Reset the cached information about the currently running async library.
+
+    This is only needed in case you need to run AnyIO code on two or more different async libraries
+    using their native ``run()`` functions one after another in the same thread.
+
+    """
     _local.__dict__.clear()
 
 
 def detect_running_asynclib() -> Optional[str]:
+    """
+    Return the name of the asynchronous framework running in the current thread.
+
+    :return: the name of the framework, or ``None`` if no supported framework is running
+
+    """
     if 'trio' in sys.modules:
         from trio.hazmat import current_trio_token
         try:
@@ -76,37 +124,6 @@ def _get_asynclib():
         return _local.asynclib
 
 
-def run(func: Callable[..., Coroutine[Any, Any, T_Retval]], *args,
-        backend: str = BACKENDS[0], backend_options: Optional[Dict[str, Any]] = None) -> T_Retval:
-    """
-    Run the given coroutine function in an asynchronous event loop.
-
-    The current thread must not be already running an event loop.
-
-    :param func: a coroutine function
-    :param args: positional arguments to ``func``
-    :param backend: name of the asynchronous event loop implementation – one of ``asyncio``,
-        ``curio`` and ``trio``
-    :param backend_options: keyword arguments to call the backend ``run()`` implementation with
-    :return: the return value of the coroutine function
-    :raises RuntimeError: if an asynchronous event loop is already running in this thread
-    :raises LookupError: if the named backend is not found
-
-    """
-    asynclib_name = detect_running_asynclib()
-    if asynclib_name:
-        raise RuntimeError('Already running {} in this thread'.format(asynclib_name))
-
-    try:
-        asynclib = import_module('{}._backends.{}'.format(__name__, backend))
-    except ImportError as exc:
-        raise LookupError('No such backend: {}'.format(backend)) from exc
-
-    backend_options = backend_options or {}
-    with claim_current_thread(asynclib):
-        return asynclib.run(func, *args, **backend_options)
-
-
 def is_in_event_loop_thread() -> bool:
     """
     Determine whether the current thread is running a recognized asynchronous event loop.
@@ -117,6 +134,11 @@ def is_in_event_loop_thread() -> bool:
     return detect_running_asynclib() is not None
 
 
+#
+# Miscellaneous
+#
+
+
 def finalize(resource: T_Agen) -> 'typing.AsyncContextManager[T_Agen]':
     """
     Return a context manager that automatically closes an asynchronous resource on exit.
@@ -130,10 +152,6 @@ def finalize(resource: T_Agen) -> 'typing.AsyncContextManager[T_Agen]':
     return _get_asynclib().finalize(resource)
 
 
-#
-# Timeouts and cancellation
-#
-
 def sleep(delay: float) -> Awaitable[None]:
     """
     Pause the current task for the specified duration.
@@ -144,6 +162,11 @@ def sleep(delay: float) -> Awaitable[None]:
     return _get_asynclib().sleep(delay)
 
 
+#
+# Timeouts and cancellation
+#
+
+
 def open_cancel_scope(*, shield: bool = False) -> 'typing.AsyncContextManager[CancelScope]':
     """
     Open a cancel scope.
@@ -190,7 +213,15 @@ def move_on_after(delay: Optional[float], *,
         return _get_asynclib().move_on_after(delay, shield=shield)
 
 
-def current_effective_deadline() -> Awaitable[float]:
+def current_effective_deadline() -> Coroutine[Any, Any, float]:
+    """
+    Return the nearest deadline among all the cancel scopes effective for the current task.
+
+    :return: a clock value from the event loop's internal clock (``float('inf')`` if there is no
+        deadline in effect)
+    :rtype: float
+
+    """
     return _get_asynclib().current_effective_deadline()
 
 
@@ -252,6 +283,7 @@ def aopen(file: Union[str, Path, int], mode: str = 'r', buffering: int = -1,
     The arguments are exactly the same as for the builtin :func:`open`.
 
     :return: an asynchronous file object
+    :rtype: AsyncFile
 
     """
     if isinstance(file, Path):
@@ -261,7 +293,7 @@ def aopen(file: Union[str, Path, int], mode: str = 'r', buffering: int = -1,
 
 
 #
-# Networking
+# Sockets and networking
 #
 
 def wait_socket_readable(sock: Union[socket.SocketType, ssl.SSLSocket]) -> Awaitable[None]:
@@ -512,7 +544,7 @@ def create_queue(capacity: int) -> Queue:
 
 
 #
-# Signal handling
+# Operating system signals
 #
 
 def receive_signals(*signals: int) -> 'typing.ContextManager[typing.AsyncIterator[int]]':

anyio/_backends/asyncio.py

@@ -103,7 +103,7 @@ def get_running_loop():
 
 
 #
-# Main entry point
+# Event loop
 #
 
 def run(func: Callable[..., T_Retval], *args, debug: bool = False,
@@ -126,6 +126,18 @@ async def wrapper():
         return retval
 
 
+#
+# Miscellaneous
+#
+
+finalize = aclosing
+
+
+async def sleep(delay: float) -> None:
+    check_cancelled()
+    await asyncio.sleep(delay)
+
+
 #
 # Timeouts and cancellation
 #
@@ -441,7 +453,7 @@ async def aopen(*args, **kwargs):
 
 
 #
-# Networking
+# Sockets and networking
 #
 
 
@@ -577,7 +589,7 @@ def put(self, item):
 
 
 #
-# Signal handling
+# Operating system signals
 #
 
 @asynccontextmanager
@@ -605,17 +617,6 @@ async def process_signal_queue():
             loop.remove_signal_handler(sig)
 
 
-#
-# Miscellaneous functions
-#
-
-async def sleep(delay: float) -> None:
-    check_cancelled()
-    await asyncio.sleep(delay)
-
-finalize = aclosing
-
-
 #
 # Testing and debugging
 #

anyio/_backends/curio.py

@@ -15,7 +15,7 @@
 
 
 #
-# Main entry point
+# Event loop
 #
 
 def run(func: Callable[..., T_Retval], *args, **curio_options) -> T_Retval:
@@ -34,6 +34,18 @@ async def wrapper():
         return retval
 
 
+#
+# Miscellaneous functions
+#
+
+finalize = curio.meta.finalize
+
+
+async def sleep(seconds: int):
+    await check_cancelled()
+    await curio.sleep(seconds)
+
+
 #
 # Timeouts and cancellation
 #
@@ -274,7 +286,7 @@ async def aopen(*args, **kwargs):
 
 
 #
-# Networking
+# Sockets and networking
 #
 
 class Socket(BaseSocket):
@@ -381,7 +393,7 @@ async def put(self, item):
 
 
 #
-# Signal handling
+# Operating system signals
 #
 
 @asynccontextmanager
@@ -391,18 +403,6 @@ async def receive_signals(*signals: int):
         await yield_(queue)
 
 
-#
-# Miscellaneous functions
-#
-
-async def sleep(seconds: int):
-    await check_cancelled()
-    await curio.sleep(seconds)
-
-
-finalize = curio.meta.finalize
-
-
 #
 # Testing and debugging
 #