WIP

Author: thepabloaguilar

docs/index.rst

@@ -39,6 +39,7 @@ Contents
   pages/functions.rst
   pages/curry.rst
   pages/types.rst
+  pages/transducers.rst
 
 .. toctree::
   :maxdepth: 2

docs/pages/transducers.rst

@@ -0,0 +1,14 @@
+.. transducers:
+
+Transducers
+===========
+
+API Reference
+-------------
+
+.. automodule:: returns.transducers.transducers
+   :members:
+
+.. autofunction:: returns.transducers.tmap
+
+.. autofunction:: returns.transducers.tfilter

returns/transducers/__init__.py

@@ -0,0 +1,6 @@
+from returns.transducers.tfilter import tfilter as tfilter
+from returns.transducers.tmap import tmap as tmap
+from returns.transducers.transducers import Missing as Missing
+from returns.transducers.transducers import Reduced as Reduced
+from returns.transducers.transducers import reduce as reduce
+from returns.transducers.transducers import transduce as transduce

returns/transducers/tfilter.py

@@ -0,0 +1,41 @@
+from typing import Callable, TypeVar
+
+_ValueType = TypeVar('_ValueType')
+_AccValueType = TypeVar('_AccValueType')
+
+
+def tfilter(
+    predicate: Callable[[_ValueType], bool],
+) -> Callable[
+    [Callable[[_AccValueType, _ValueType], _AccValueType]],
+    Callable[[_AccValueType, _ValueType], _AccValueType],
+]:
+    """
+    :py:func:`filter <filter>` implementation on a transducer form.
+
+    .. code:: python
+
+      >>> from typing import List
+      >>> from returns.transducers import tfilter, reduce
+
+      >>> def is_even(number: int) -> bool:
+      ...     return number % 2 == 0
+
+      >>> def append(collection: List[int], item: int) -> List[int]:
+      ...     collection.append(item)
+      ...     return collection
+
+      >>> my_list = [0, 1, 2, 3, 4, 5, 6]
+      >>> xform = tfilter(is_even)(append)
+      >>> assert reduce(xform, my_list, []) == [0, 2, 4, 6]
+
+    """
+    def reducer(
+        step: Callable[[_AccValueType, _ValueType], _AccValueType],
+    ) -> Callable[[_AccValueType, _ValueType], _AccValueType]:
+        def filter_(acc: _AccValueType, value: _ValueType) -> _AccValueType:
+            if predicate(value):
+                return step(acc, value)
+            return acc
+        return filter_
+    return reducer

returns/transducers/tmap.py

@@ -0,0 +1,41 @@
+from typing import Callable, TypeVar
+
+_ValueType = TypeVar('_ValueType')
+_NewValueType = TypeVar('_NewValueType')
+
+_AccValueType = TypeVar('_AccValueType')
+
+
+def tmap(
+    function: Callable[[_ValueType], _NewValueType],
+) -> Callable[
+    [Callable[[_AccValueType, _NewValueType], _AccValueType]],
+    Callable[[_AccValueType, _ValueType], _AccValueType],
+]:
+    """
+    A map implementation on a transducer form.
+
+    .. code:: python
+
+      >>> from typing import List
+      >>> from returns.transducers import tmap, reduce
+
+      >>> def add_one(number: int) -> int:
+      ...     return number + 1
+
+      >>> def append(collection: List[int], item: int) -> List[int]:
+      ...     collection.append(item)
+      ...     return collection
+
+      >>> my_list = [0, 1]
+      >>> xformaa = tmap(add_one)(append)
+      >>> assert reduce(xformaa, my_list, []) == [1, 2]
+
+    """
+    def reducer(
+        step: Callable[[_AccValueType, _NewValueType], _AccValueType],
+    ) -> Callable[[_AccValueType, _ValueType], _AccValueType]:
+        def map_(acc: _AccValueType, value: _ValueType) -> _AccValueType:
+            return step(acc, function(value))
+        return map_
+    return reducer

returns/transducers/transducers.py

@@ -0,0 +1,139 @@
+from typing import Any, Callable, Iterable, Optional, TypeVar, overload
+
+_ValueType = TypeVar('_ValueType')
+_NewValueType = TypeVar('_NewValueType')
+
+_AccValueType = TypeVar('_AccValueType')
+
+
+class Reduced(object):
+    """
+    Sentinel for early termination inside transducer.
+
+    .. code:: python
+
+      >>> from returns.transducers import tmap, transduce, Reduced
+
+      >>> def add_one(number: int) -> int:
+      ...     return number + 1
+
+      >>> def add(acc: int, number: int) -> int:
+      ...     if acc == 3:
+      ...         return Reduced(acc)
+      ...     return acc + number
+
+      >>> my_list = [0, 1, 2]
+      >>> assert transduce(tmap(add_one), add, 0, my_list) == 3
+
+    """
+
+    _inner_value: Any
+
+    def __init__(self, inner_value: Any) -> None:
+        self._inner_value = inner_value
+
+    @property
+    def value(self) -> Any:
+        return self._inner_value
+
+
+class _Missing(object):
+    """Represents a missing value for reducers."""
+
+    _instance: Optional['_Missing'] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> '_Missing':
+        if cls._instance is None:
+            cls._instance = object.__new__(cls)  # noqa: WPS609
+        return cls._instance
+
+
+#: A singleton representing any missing value
+Missing = _Missing()
+
+
+def transduce(
+    xform: Callable[
+        [Callable[[_AccValueType, _ValueType], _AccValueType]],
+        Callable[[_AccValueType, _ValueType], _AccValueType],
+    ],
+    reducing_function: Callable[[_AccValueType, _ValueType], _AccValueType],
+    initial: _AccValueType,
+    iterable: Iterable[_ValueType],
+) -> _AccValueType:
+    """
+    Process information with transducers.
+
+    .. code:: python
+
+      >>> from returns.transducers import tmap, transduce
+
+      >>> def add_one(number: int) -> int:
+      ...     return number + 1
+
+      >>> def add(acc: int, number: int) -> int:
+      ...     return acc + number
+
+      >>> my_list = [0, 1, 2]
+      >>> assert transduce(tmap(add_one), add, 0, my_list) == 6
+    """
+    reducer = xform(reducing_function)
+    return reduce(reducer, iterable, initial)
+
+
+@overload
+def reduce(
+    function: Callable[[_ValueType, _ValueType], _ValueType],
+    iterable: Iterable[_ValueType],
+    initial: _Missing = Missing,
+) -> _ValueType:
+    """Reduce without an initial value."""
+
+
+@overload
+def reduce(
+    function: Callable[[_AccValueType, _ValueType], _AccValueType],
+    iterable: Iterable[_ValueType],
+    initial: _AccValueType,
+) -> _AccValueType:
+    """Reduce with an initial value."""
+
+
+def reduce(function, iterable, initial=Missing):
+    """
+    A rewritten version of :func:`reduce <functools.reduce>`.
+
+    This version considers some features borrowed from Clojure:
+
+    - Early termination
+    - Function initializer [TODO]
+
+    You can use it as a normal reduce if you want:
+
+    .. code:: python
+
+      >>> from returns.transducers import reduce
+
+      >>> def add(acc: int, value: int) -> int:
+      ...     return acc + value
+
+      >>> assert reduce(add, [1, 2, 3]) == 6
+
+    """
+    it = iter(iterable)
+
+    if initial is Missing:
+        try:
+            acc_value = next(it)
+        except StopIteration:
+            raise TypeError(
+                'reduce() of empty iterable with no initial value',
+            ) from None
+    else:
+        acc_value = initial
+
+    for value in it:  # noqa: WPS110
+        acc_value = function(acc_value, value)
+        if isinstance(acc_value, Reduced):
+            return acc_value.value
+    return acc_value

setup.cfg

@@ -62,6 +62,7 @@ per-file-ignores =
   returns/methods/__init__.py: F401, WPS201
   returns/pipeline.py: F401
   returns/context/__init__.py: F401, WPS201
+  returns/transducers/__init__.py: F401
   # Disable some quality checks for the most heavy parts:
   returns/io.py: WPS402
   returns/iterables.py: WPS234

tests/test_transducers/test_transducers/test_missing_singleton.py

@@ -0,0 +1,6 @@
+from returns.transducers.transducers import _Missing
+
+
+def test_missing_singleton():
+    """Ensures `_Missing` is a singleton."""
+    assert _Missing() is _Missing()

tests/test_transducers/test_transducers/test_reduce.py

@@ -0,0 +1,9 @@
+import pytest
+
+from returns.transducers import reduce
+
+
+def test_reduce():
+    """Should fail when iterable is empty and non initial value is given."""
+    with pytest.raises(TypeError):
+        reduce(lambda acc, val: acc + val, [])

typesafety/test_transducers/test_tfilter.yml

@@ -0,0 +1,73 @@
+- case: tfilter
+  disable_cache: false
+  main: |
+    from returns.transducers import tfilter
+
+    def is_even(number: int) -> bool:
+        ...
+
+    reveal_type(tfilter(is_even))  # N: Revealed type is 'def [_AccType] (def (_AccType`-2, builtins.int*) -> _AccType`-2) -> def (_AccType`-2, builtins.int*) -> _AccType`-2'
+
+
+- case: tfilter_reducer
+  disable_cache: false
+  main: |
+    from typing import List
+    from returns.transducers import tfilter
+
+    def is_even(number: int) -> bool:
+        ...
+
+    def append(collection: List[int], item: int) -> List[int]:
+        ...
+
+    reveal_type(tfilter(is_even)(append))  # N: Revealed type is 'def (builtins.list*[builtins.int], builtins.int) -> builtins.list*[builtins.int]'
+
+
+- case: tfilter_reducer_filter_
+  disable_cache: false
+  main: |
+    from typing import List
+    from returns.transducers import tfilter, reduce
+
+    def is_even(number: int) -> bool:
+        ...
+
+    def append(collection: List[int], item: int) -> List[int]:
+        ...
+
+    my_list: List[int]
+    reveal_type(tfilter(is_even)(append)(my_list, 2))  # N: Revealed type is 'builtins.list*[builtins.int]'
+
+
+- case: tfilter_composition_one
+  disable_cache: false
+  main: |
+    from typing import List
+    from returns.transducers import tfilter, reduce
+
+    def is_even(number: int) -> bool:
+        ...
+
+    def append(collection: List[int], item: int) -> List[int]:
+        ...
+
+    composed = tfilter(is_even)(tfilter(is_even)(append))
+    reveal_type(composed)  # N: Revealed type is 'def (builtins.list*[builtins.int], builtins.int) -> builtins.list*[builtins.int]'
+
+
+- case: tfilter_composition_two
+  disable_cache: false
+  main: |
+    from typing import List
+    from returns.transducers import tfilter, reduce
+
+    def is_even(number: int) -> bool:
+        ...
+
+    def append(collection: List[int], item: int) -> List[int]:
+        ...
+
+    composed = tfilter(is_even)(tfilter(is_even)(append))
+    my_list: List[int]
+    reveal_type(composed(my_list, 42))  # N: Revealed type is 'builtins.list*[builtins.int]'