chore(patch): deprecate sghi.task.Consume for removal (#35)

This class has not proven to be useful. Removing it will reduce the
maintenance burden and allow more useful tasks to be added.

src/sghi/task/__init__.py

@@ -16,7 +16,7 @@
 from logging import Logger, getLogger
 from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast, final
 
-from typing_extensions import override
+from typing_extensions import deprecated, override
 
 from ..disposable import Disposable, ResourceDisposedError
 from ..disposable import not_disposed as _nd_factory
@@ -224,13 +224,18 @@ def execute(self, an_input: Callable[[_IT], _OT]) -> Chain[_OT]:
         return Chain(bind(self._value))
 
 
+@deprecated("To be removed in v2.x")
 @final
 class Consume(Task[_IT, _IT], Generic[_IT]):
     """A :class:`Task` that applies an action to it's inputs.
 
     This ``Task`` wraps a callable and applies it to its input. It returns
     its input value as is on execution and is better suited for
     operations with side effects.
+
+    .. deprecated:: 1.4
+       To be removed in v2.
+
     """
 
     __slots__ = ("_accept",)
@@ -248,15 +253,19 @@ def __init__(self, accept: Callable[[_IT], Any]) -> None:
         ensure_callable(accept, "'accept' MUST be a callable.")
         self._accept: Callable[[_IT], Any] = accept
 
-    def __add__(self, __an_input: Callable[[_IT], Any], /) -> Consume[_IT]:
-        return self.and_then(accept=__an_input)
+    def __add__(self, __an_input: Callable[[_IT], Any], /) -> Consume[_IT]:  # type: ignore[reportDeprecated]
+        return self.and_then(accept=__an_input)  # type: ignore[reportDeprecated]
 
-    def and_then(self, accept: Callable[[_IT], Any]) -> Consume[_IT]:
+    @deprecated("To be removed in v2.x")
+    def and_then(self, accept: Callable[[_IT], Any]) -> Consume[_IT]:  # type: ignore[reportDeprecated]
         """Compose this :class:`Consume` action with the provided action.
 
         This creates a new ``Consume`` instance that performs both this task's
         action and the provided action.
 
+        .. deprecated:: 1.4
+           To be removed in v2.
+
         :param accept: The action to compose with this task's action. This
             MUST be a callable object.
 
@@ -270,7 +279,7 @@ def _compose_accept(an_input: _IT) -> None:
             self._accept(an_input)
             accept(an_input)
 
-        return Consume(accept=_compose_accept)
+        return Consume(accept=_compose_accept)  # type: ignore[reportDeprecated]
 
     @override
     def execute(self, an_input: _IT) -> _IT:
@@ -339,7 +348,7 @@ def execute(self, an_input: _IT) -> _OT:
 
 chain = Chain
 
-consume = Consume
+consume = Consume  # type: ignore[reportDeprecated]
 
 pipe = Pipe
 

test/sghi/task_tests.py

@@ -91,7 +91,7 @@ def test_and_then_method_returns_expected_value(self) -> None:
         collection2: set[int] = set()
 
         collector: consume[int]
-        collector = consume(collection1.append).and_then(collection2.add)
+        collector = consume(collection1.append).and_then(collection2.add)  # type: ignore[reportDeprecated]
 
         assert isinstance(collector, consume)
 
@@ -153,7 +153,7 @@ def test_different_and_then_method_invocation_styles_return_same_value(
 
         # Style 1, explicit invocation
         collector1: consume[int]
-        collector1 = consume(collection1.append).and_then(collection2.add)
+        collector1 = consume(collection1.append).and_then(collection2.add)  # type: ignore[reportDeprecated]
         # Style 2, using the plus operator
         collector2: consume[int]
         collector2 = consume(collection3.append) + collection4.add