docs: Update README and API docs

LICENSE

@@ -19,11 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-
-
-<Additional Notice>
-
-This project includes parts of other open source software as listed below:
-
-- EdgeDB (under Apache 2.0), as src/aiotools/taskgroup.py

LICENSE-EXTRA

@@ -0,0 +1,5 @@
+<Additional Notice about License>
+
+This project includes parts of other open source software as listed below:
+
+- EdgeDB (under Apache 2.0), as src/aiotools/taskgroup.py

README.md

@@ -3,7 +3,7 @@ aiotools
 
 [![PyPI release version](https://badge.fury.io/py/aiotools.svg)](https://pypi.org/project/aiotools/)
 ![Supported Python versions](https://img.shields.io/pypi/pyversions/aiotools.svg)
-[![Build Status](https://travis-ci.org/achimnol/aiotools.svg?branch=master)](https://travis-ci.org/achimnol/aiotools)
+![Test Status](https://github.com/achimnol/aiotools/workflows/Test%20with%20pytest/badge.svg)
 [![Code Coverage](https://codecov.io/gh/achimnol/aiotools/branch/master/graph/badge.svg)](https://codecov.io/gh/achimnol/aiotools)
 
 Idiomatic asyncio utilties
@@ -18,6 +18,7 @@ Modules
 * [Async Functools](http://aiotools.readthedocs.io/en/latest/aiotools.func.html)
 * [Async Itertools](http://aiotools.readthedocs.io/en/latest/aiotools.iter.html)
 * [Async Server](http://aiotools.readthedocs.io/en/latest/aiotools.server.html)
+* [Async TaskGroup](http://aiotools.readthedocs.io/en/latest/aiotools.taskgroup.html)
 * [Async Timer](http://aiotools.readthedocs.io/en/latest/aiotools.timer.html)
 
 I also recommend to try the following asyncio libraries for your happier life.
@@ -129,6 +130,27 @@ It handles SIGINT/SIGTERM signals automatically to stop the server,
 as well as lifecycle management of event loops running on multiple processes.
 
 
+### Async TaskGroup
+
+A `TaskGroup` object manages the lifecycle of sub-tasks spawned via its `create_task()`
+method by guarding them with an async context manager which exits only when all sub-tasks
+are either completed or cancelled.
+
+This is motivated from [trio's nursery API](https://trio.readthedocs.io/en/stable/reference-core.html#nurseries-and-spawning)
+and a draft implementation is adopted from [EdgeDB's Python client library](https://github.com/edgedb/edgedb-python).
+
+```python
+import aiotools
+
+async def do():
+    async with aiotools.TaskGroup() as tg:
+        tg.create_task(...)
+        tg.create_task(...)
+        ...
+    # at this point, all subtasks are either cancelled or done.
+```
+
+
 ### Async Timer
 
 ```python
@@ -174,3 +196,25 @@ async def somewhere():
    t.cancel()
    await t
 ```
+
+#### Virtual Clock
+
+It provides a virtual clock that advances the event loop time instantly upon
+any combination of `asyncio.sleep()` calls in multiple coroutine tasks,
+by temporarily patching the event loop selector.
+
+This is also used in [our timer test suite](https://github.com/achimnol/aiotools/blob/master/tests/test_timer.py).
+
+```python
+import aiotools
+import pytest
+
+@pytest.mark.asyncio
+async def test_sleeps():
+    loop = aiotools.compat.get_running_loop()
+    vclock = aiotools.VirtualClock()
+    with vclock.patch_loop():
+        print(loop.time())  # -> prints 0
+        await asyncio.sleep(99999999999)
+        print(loop.time())  # -> prints 99999999999
+```

docs/aiotools.taskgroup.rst

@@ -0,0 +1,6 @@
+Task Group
+==========
+
+.. automodule:: aiotools.taskgroup
+    :members:
+    :undoc-members:

docs/index.rst

@@ -16,6 +16,7 @@ aiotools Documentation
    aiotools.func
    aiotools.iter
    aiotools.server
+   aiotools.taskgroup
    aiotools.timer
 
 

src/aiotools/taskgroup.py

@@ -38,6 +38,13 @@
 
 
 class TaskGroup:
+    """
+    Provides a guard against a group of tasks spawend via its :meth:`create_task`
+    method instead of the vanilla fire-and-forgetting :meth:`asyncio.create_task`.
+
+    See the motivation and rationale in `the trio's documentation
+    <https://trio.readthedocs.io/en/stable/reference-core.html#nurseries-and-spawning>`_.
+    """
 
     def __init__(self, *, name=None):
         if name is None:
@@ -280,6 +287,10 @@ def _on_task_done(self, task):
 
 
 class MultiError(Exception):
+    """
+    Represents a collection of errors raised inside a task group.
+    Callers may iterate over the errors using the ``__erros__`` attribute.
+    """
 
     def __init__(self, msg, *args, errors=()):
         if errors:
@@ -302,6 +313,9 @@ def __reduce__(self):
 
 
 class TaskGroupError(MultiError):
+    """
+    An alias to :exc:`MultiError`.
+    """
     pass