feat: add Task interface & its common implementations

Add the `sghi.task.Task` interface together with its common implementations such as:

- `sghi.task.Chain`
- `sghi.task.Consume`
- `sghi.task.Pipe`

Also included is a special kind of `Task`- `sghi.task.ConcurrentExecutor`, used to execute other tasks that share an input concurrently.

docs/conf.py

@@ -60,36 +60,21 @@
     ("py:class", "_DT"),  # type annotation only available when type checking
     ("py:class", "_P"),  # type annotation only available when type checking
     ("py:class", "_RT"),  # type annotation only available when type checking
+    ("py:class", "Chain[Any]"),  # Used as type annotation. Only available when type checking
     ("py:class", "TracebackType"),  # Used as type annotation. Only available when type checking
     ("py:class", "concurrent.futures._base.Executor"),  # sphinx can't find it
     ("py:class", "concurrent.futures._base.Future"),  # sphinx can't find it
-    ("py:class", "sghi.disposable.decorators._D"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators._DE"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators._P"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators._R"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators.not_disposed._D"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators.not_disposed._DE"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators.not_disposed._P"),  # private type annotations
-    ("py:class", "sghi.disposable.decorators.not_disposed._R"),  # private type annotations
-    ("py:class", "sghi.task.task._IT"),  # private type annotations
-    ("py:class", "sghi.task.task._OT"),  # private type annotations
-    ("py:class", "sghi.task.common._IT"),  # private type annotations
-    ("py:class", "sghi.task.common._OT"),  # private type annotations
-    ("py:class", "sghi.task.concurrent._IT"),  # private type annotations
-    ("py:class", "sghi.task.concurrent._OT"),  # private type annotations
+    ("py:class", "sghi.task._IT"),  # private type annotations
+    ("py:class", "sghi.task._OT"),  # private type annotations
     ("py:class", "sghi.utils.checkers._Comparable"),  # private type annotations
     ("py:class", "sghi.utils.checkers._ST"),  # private type annotations
     ("py:class", "sghi.utils.checkers._T"),  # private type annotations
     ("py:class", "sghi.utils.module_loading._T"),  # private type annotations
     ("py:class", "sghi.typing._CT_contra"),  # private type annotations
     ("py:obj", "sghi.disposable.decorators.not_disposed._P"),  # private type annotations
     ("py:obj", "sghi.disposable.decorators.not_disposed._R"),  # private type annotations
-    ("py:obj", "sghi.task.task._IT"),  # private type annotations
-    ("py:obj", "sghi.task.task._OT"),  # private type annotations
-    ("py:obj", "sghi.task.common._IT"),  # private type annotations
-    ("py:obj", "sghi.task.common._OT"),  # private type annotations
-    ("py:obj", "sghi.task.concurrent._IT"),  # private type annotations
-    ("py:obj", "sghi.task.concurrent._OT"),  # private type annotations
+    ("py:obj", "sghi.task._IT"),  # private type annotations
+    ("py:obj", "sghi.task._OT"),  # private type annotations
     ("py:obj", "sghi.typing._CT_contra"),  # private type annotations
 ]
 

docs/index.rst

@@ -43,6 +43,7 @@ API Reference
      sghi.app
      sghi.disposable
      sghi.exceptions
+     sghi.task
      sghi.typing
      sghi.utils
 

src/sghi/disposable/__init__.py

@@ -106,10 +106,11 @@ def dispose(self) -> None:
 
         .. note::
             Unless otherwise specified, trying to use methods of a
-            ``Disposable`` instance decorated with the :func:`not_disposed`
-            decorator after this method returns should generally be considered
-            a programming error and should result in a
-            :exc:`ResourceDisposedError` being raised.
+            ``Disposable`` instance decorated with the
+            :func:`~sghi.disposable.not_disposed` decorator after this method
+            returns should generally be considered a programming error and
+            should result in a :exc:`~sghi.disposable.ResourceDisposedError`
+            being raised.
 
             This method should be idempotent allowing it to be called more
             than once; only the first call, however, should have an effect.