Documentation Maintenance 072022 (#97)

* documented reusing sync primitives for async

* reworded async neutral explanation

* expanded async neutral glossary

Author: maxfischer2781

docs/index.rst

@@ -48,6 +48,7 @@ The missing ``async`` toolbox
    :hidden:
 
    source/notes/iter_scope
+   source/notes/compatible
    source/glossary
 
 .. toctree::
@@ -120,12 +121,12 @@ Async Neutral Arguments
 
 Many objects of :py:mod:`asyncstdlib` are :term:`async neutral` -- they accept
 *both* regular and async arguments.
-Type annotations use *(async)* to denote async neutral objects.
-For example, the annotation *(int, ...) → (async) bool* denotes a call that takes an
-:py:class:`int` and either returns a boolean directly *or* requires ``await`` to
-return a boolean.
+Type annotations use parentheses to denote this;
+for example, "*(async) iter T*" in the signature **zip(**\ *\*iterables: (async) iter T*\ **)**
+means that :py:mod:`asyncstdlib`'s :py:func:`~builtins.zip`
+can handle both synchronous and asynchronous iterables.
 
-Whether a call is regular or async is determined by inspecting its
+Whether a callable is regular or async is determined by inspecting its
 return type at runtime.
 This supports async-producing factories, such as an ``async def``
 function wrapped in :py:class:`functools.partial`.

docs/source/glossary.rst

@@ -10,9 +10,11 @@ Glossary of Terms
 .. glossary::
 
    async neutral
-      An object that may provide either of a regular or asynchronous implementation.
-      For example, an async neutral iterable may support either regular
+      Types that support either of a regular or asynchronous implementation.
+      For example, an async neutral iterable may provide either regular
       ``for _ in iterable`` or asynchronous ``async for _ in iterable`` iteration.
+      Commonly, callables have async neutral parameters to simplify using them
+      with a mixture of synchronous and regular arguments.
 
    borrowing
    borrowed object

docs/source/notes/compatible.rst

@@ -0,0 +1,69 @@
+.. _guide_compatible:
+
+================
+Sync/Async Reuse
+================
+
+The :py:mod:`asyncstdlib` only re-implements functions and classes
+that benefit from an async implementation.
+In some cases, a synchronous implementation is already
+sufficient to cover the async case as well.
+
+Example: async property
+=======================
+
+A prominent example is an "``async`` ``property``":
+a computed attribute that allows to run ``async`` code as well.
+This is useful for example to fetch data for the attribute
+from a remote database or server.
+
+As it turns out, we can directly use the builtin :py:class:`property` for this!
+
+.. code-block:: python3
+
+    # python3 -m asyncio
+    class Remote:
+        _count = 0
+        @property                   # <== builtin @property ...
+        async def attribute(self):  # ... around an async method
+            await asyncio.sleep(1)  # let's pretend to do some work...
+            self._count += 1
+            return "Na" * self._count
+
+    instance = Remote()
+    print(await instance.attribute)  # waits 1 second, prints Na
+    print(await instance.attribute)  # waits 1 second, prints NaNa
+
+In principle, we could also define setters and deleters
+– however, Python has no syntax for async assignment or deletion
+which limits the advantage of using a :py:class:`property` in the first place. [1]_
+
+Identifying reusability
+=======================
+
+In general, a utility is sync/async compatible when it takes a callable but does not
+depend on the concrete result.
+For example, a `property` getter just prepares some attribute value
+– which may as well be an awaitable.
+In contrast, the similar :py:func:`~asyncstdlib.functools.cached_property` must access
+the concrete result to store it – this requires async capabilities for the async case.
+
+Some examples for async compatible parts of the standard library include:
+
+* Factory descriptors such as :py:class:`property`, :py:class:`classmethod` and :py:class:`staticmethod`
+* Factories such as :py:func:`functools.partial` and :py:func:`functools.partialmethod`
+* Selectors such as :py:func:`functools.singledispatch` and :py:func:`functools.singledispatchmethod`
+* Modifiers such as :py:func:`functools.wraps` and :py:func:`functools.update_wrapper`
+* Special method operators not enforcing result types such as :py:func:`reversed` and :py:func:`~operator.__add__`
+
+Most of these merely wrap a callable to either modify it directly
+(such as :py:func:`functools.wraps`)
+or call it regardless of the return type
+(such as :py:func:`functools.partial`).
+Note that some functions such as :py:func:`~operator.__add__` *usually* work for the
+`async` case, but may fail in some subtle edge case – such as not being able to see
+a :py:data:`NotImplemented` return value.
+
+.. [1] Using `setattr` and `delattr` one can asynchronously run a setter/getter,
+       for example `await setattr(instance, "attribute")`. However, with the lack
+       of specific syntax this offers little to no advantage over using a method.

setup.cfg

@@ -1,6 +1,6 @@
 [flake8]
 statistics = True
 max-line-length = 80
-ignore = E501, B008, B011, W503
+ignore = E501, B008, B011, B905, W503
 select = C,E,F,W,B,B9
 exclude = docs,.svn,CVS,.bzr,.hg,.git,__pycache__,.tox,.eggs,*.egg