trcks 0.2.0__py3-none-any.whl

trcks/__init__.py

@@ -0,0 +1,123 @@
+"""Typesafe railway-oriented programming (ROP).
+
+This package provides
+
+- the generic (return) types `trcks.Result` and `trcks.AwaitableResult` and
+- the subpackages `trcks.fp` and `trcks.oop` for working with these types
+  in a functional and object-oriented way, respectively.
+
+See:
+    https://fsharpforfunandprofit.com/posts/recipe-part2/
+"""
+
+from collections.abc import Awaitable
+from typing import Literal, Union
+
+from trcks._typing import TypeAlias, TypeVar
+
+__docformat__ = "google"
+
+_F_co = TypeVar("_F_co", covariant=True)
+_S_co = TypeVar("_S_co", covariant=True)
+
+
+Failure: TypeAlias = tuple[Literal["failure"], _F_co]
+"""`tuple` of length 2 containing ``"failure"`` followed by a value of type `_F_co`.
+
+Example:
+    >>> failure: Failure[str] = ("failure", "File does not exist")
+
+Note:
+    This generic type is called "Left" in
+    some functional programming languages and packages (e.g. Haskell and fp-ts).
+"""
+
+Success: TypeAlias = tuple[Literal["success"], _S_co]
+"""`tuple` of length 2 containing ``"success"`` followed by a value of type `_S_co`.
+
+Example:
+    >>> success: Success[int] = ("success", 42)
+
+Note:
+    This generic type is called "Right" in
+    some functional programming languages and packages (e.g. Haskell and fp-ts).
+"""
+
+Result: TypeAlias = Union[Failure[_F_co], Success[_S_co]]
+"""Discriminated union of the generic types `_F_co` and `_S_co`.
+
+Can be used as a return type of a function
+instead of returning `_S_co` and raising `_F_co`.
+
+Example:
+    >>> def divide(a: float, b: float) -> Result[ZeroDivisionError, float]:
+    ...     try:
+    ...         return ("success", a/b)
+    ...     except ZeroDivisionError as e:
+    ...         return ("failure", e)
+    ...
+    >>> divide(5.0, 2.0)
+    ('success', 2.5)
+    >>> divide(3.5, 0.0)
+    ('failure', ZeroDivisionError('float division by zero'))
+
+Note:
+    This generic type is called "Either" in
+    some functional programming languages and packages (e.g. Haskell and fp-ts).
+"""
+
+AwaitableFailure: TypeAlias = Awaitable[Failure[_F_co]]
+"""`collections.abc.Awaitable` that returns a `Failure`
+when used in an ``await`` expression.
+"""
+
+AwaitableSuccess: TypeAlias = Awaitable[Success[_S_co]]
+"""`collections.abc.Awaitable` that returns a `Success`
+when used in an ``await`` expression.
+"""
+
+AwaitableResult: TypeAlias = Awaitable[Result[_F_co, _S_co]]
+"""`collections.abc.Awaitable` that returns a `Result`
+when used in an ``await`` expression.
+
+Examples:
+    Can be used to annotate the non-awaited return value of an async function:
+
+        >>> import asyncio
+        >>> async def divide_slowly(
+        ...     a: float, b: float
+        ... ) -> Result[ZeroDivisionError, float]:
+        ...     await asyncio.sleep(0.001)
+        ...     try:
+        ...         return ("success", a / b)
+        ...     except ZeroDivisionError as e:
+        ...         return ("failure", e)
+        ...
+        >>> async def main() -> None:
+        ...     a_rslt: AwaitableResult[ZeroDivisionError, float] = (
+        ...         divide_slowly(3.0, 0.0)
+        ...     )
+        ...     rslt: Result[ZeroDivisionError, float] = await a_rslt
+        ...     print(rslt)
+        ...
+        >>> asyncio.run(main())
+        ('failure', ZeroDivisionError('float division by zero'))
+
+    Can also be used to annotate an async function:
+
+        >>> import asyncio
+        >>> from collections.abc import Callable
+        >>>
+        >>> async def divide_slowly(
+        ...     a: float, b: float
+        ... ) -> Result[ZeroDivisionError, float]:
+        ...     await asyncio.sleep(0.001)
+        ...     try:
+        ...         return ("success", a / b)
+        ...     except ZeroDivisionError as e:
+        ...         return ("failure", e)
+        ...
+        >>> copy_of_divide_slowly: Callable[
+        ...     [float, float], AwaitableResult[ZeroDivisionError, float]
+        ... ] = divide_slowly
+"""

trcks/_typing.py

@@ -0,0 +1,31 @@
+"""Recent features from `typing`.
+
+Imported from `typing_extensions` if necessary in older Python versions.
+This helps to avoid `sys.version_info` checks in the codebase.
+"""
+
+import sys
+
+if sys.version_info >= (3, 13):  # pragma: no cover
+    from typing import TypeVar  # Argument "default" has been added in Python 3.13.
+else:  # pragma: no cover
+    from typing_extensions import TypeVar
+
+if sys.version_info >= (3, 12):  # pragma: no cover
+    from typing import override
+else:  # pragma: no cover
+    from typing_extensions import override
+
+if sys.version_info >= (3, 11):  # pragma: no cover
+    from typing import Never, TypeAlias, assert_never
+else:  # pragma: no cover
+    from typing_extensions import Never, TypeAlias, assert_never
+
+__all__ = [
+    "Never",
+    "TypeAlias",
+    "TypeVar",
+    "assert_never",
+    "override",
+]
+__docformat__ = "google"

trcks/fp/__init__.py

@@ -0,0 +1,64 @@
+"""Functional interface for `trcks`.
+
+This package provides functions for processing values of the following types
+in a functional style:
+
+- `collections.abc.Awaitable`
+- `trcks.AwaitableResult`
+- `trcks.Result`
+
+Example:
+    This example uses the modules `trcks.fp.composition` and `trcks.fp.monads.result`
+    to create and further process a value of type `trcks.Result`:
+
+        >>> import math
+        >>> from typing import Literal
+        >>> from trcks import Result
+        >>> from trcks.fp.composition import pipe
+        >>> from trcks.fp.monads import result as r
+        >>> GetSquareRootResult = Result[Literal["negative value"], float]
+        >>> def get_square_root(x: float) -> GetSquareRootResult:
+        ...     return pipe(
+        ...         (
+        ...             x,
+        ...             lambda xx:
+        ...                 ("success", xx)
+        ...                 if xx >= 0
+        ...                 else ("failure", "negative value"),
+        ...             r.map_success(math.sqrt),
+        ...         )
+        ...     )
+        ...
+        >>> get_square_root(25.0)
+        ('success', 5.0)
+        >>> get_square_root(-25.0)
+        ('failure', 'negative value')
+
+    If your static type checker cannot infer the type of
+    the argument passed to `trcks.fp.composition.pipe`,
+    you can explicitly assign a type:
+
+        >>> import math
+        >>> from typing import Literal
+        >>> from trcks import Result
+        >>> from trcks.fp.composition import Pipeline2, pipe
+        >>> from trcks.fp.monads import result as r
+        >>> GetSquareRootResult = Result[Literal["negative value"], float]
+        >>> def get_square_root(x: float) -> GetSquareRootResult:
+        ...     p: Pipeline2[float, GetSquareRootResult, GetSquareRootResult] = (
+        ...         x,
+        ...         lambda xx:
+        ...             ("success", xx)
+        ...             if xx >= 0
+        ...             else ("failure", "negative value"),
+        ...         r.map_success(math.sqrt),
+        ...     )
+        ...     return pipe(p)
+        ...
+        >>> get_square_root(25.0)
+        ('success', 5.0)
+        >>> get_square_root(-25.0)
+        ('failure', 'negative value')
+"""
+
+__docformat__ = "google"

trcks/fp/composition.py

@@ -0,0 +1,268 @@
+"""Types and higher order functions for function composition.
+
+Attributes:
+    Composable:
+        Up to seven compatible functions that can be applied sequentially
+        from first to last.
+    Composable1:
+        A single function.
+    Composable2:
+        Two compatible functions that can be applied sequentially from first to last.
+    Composable3:
+        Three compatible functions that can be applied sequentially from first to last.
+    Composable4:
+        Four compatible functions that can be applied sequentially from first to last.
+    Composable5:
+        Five compatible functions that can be applied sequentially from first to last.
+    Composable6:
+        Six compatible functions that can be applied sequentially from first to last.
+    Composable7:
+        Seven compatible functions that can be applied sequentially from first to last.
+    Pipeline:
+        A single value followed by up to seven compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline0:
+        A single value.
+    Pipeline1:
+        A single value followed by a single compatible function
+        that can be applied.
+    Pipeline2:
+        A single value followed by two compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline3:
+        A single value followed by three compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline4:
+        A single value followed by four compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline5:
+        A single value followed by five compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline6:
+        A single value followed by six compatible functions
+        that can be applied sequentially from first to last.
+    Pipeline7:
+        A single value followed by seven compatible functions
+        that can be applied sequentially from first to last.
+
+Example:
+    Sequentially apply two functions to one input value
+    in three different ways:
+
+        >>> def to_length_string(n: int) -> str:
+        ...     return f"Length: {n}"
+        ...
+        >>> input_ = "Hello, world!"
+        >>> to_length_string(len(input_))
+        'Length: 13'
+        >>> get_length_string = compose((len, to_length_string))
+        >>> get_length_string(input_)
+        'Length: 13'
+        >>> pipe((input_, len, to_length_string))
+        'Length: 13'
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Union
+
+from trcks._typing import TypeAlias, TypeVar, assert_never
+
+__docformat__ = "google"
+
+
+_IN = TypeVar("_IN")
+_OUT = TypeVar("_OUT")
+_T0 = TypeVar("_T0")
+_T1 = TypeVar("_T1")
+_T2 = TypeVar("_T2")
+_T3 = TypeVar("_T3")
+_T4 = TypeVar("_T4")
+_T5 = TypeVar("_T5")
+_T6 = TypeVar("_T6")
+_T7 = TypeVar("_T7")
+
+# Tuple type unpacking does not work correctly in Python 3.9 and 3.10
+# (see https://github.com/python/typing_extensions/issues/103).
+# Therefore, the following tuple type definitions contain a lot of repetitions:
+
+Composable1: TypeAlias = tuple[Callable[[_T0], _T1],]
+
+Composable2: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+]
+
+Composable3: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+]
+
+Composable4: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+]
+
+Composable5: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+]
+
+Composable6: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+    Callable[[_T5], _T6],
+]
+
+Composable7: TypeAlias = tuple[
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+    Callable[[_T5], _T6],
+    Callable[[_T6], _T7],
+]
+
+Composable: TypeAlias = Union[
+    Composable7[_IN, _T1, _T2, _T3, _T4, _T5, _T6, _OUT],
+    Composable6[_IN, _T1, _T2, _T3, _T4, _T5, _OUT],
+    Composable5[_IN, _T1, _T2, _T3, _T4, _OUT],
+    Composable4[_IN, _T1, _T2, _T3, _OUT],
+    Composable3[_IN, _T1, _T2, _OUT],
+    Composable2[_IN, _T1, _OUT],
+    Composable1[_IN, _OUT],
+]
+
+Pipeline0: TypeAlias = tuple[_T0,]
+
+Pipeline1: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+]
+
+Pipeline2: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+]
+
+Pipeline3: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+]
+
+Pipeline4: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+]
+
+Pipeline5: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+]
+
+Pipeline6: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+    Callable[[_T5], _T6],
+]
+
+Pipeline7: TypeAlias = tuple[
+    _T0,
+    Callable[[_T0], _T1],
+    Callable[[_T1], _T2],
+    Callable[[_T2], _T3],
+    Callable[[_T3], _T4],
+    Callable[[_T4], _T5],
+    Callable[[_T5], _T6],
+    Callable[[_T6], _T7],
+]
+
+Pipeline: TypeAlias = Union[
+    Pipeline7[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _OUT],
+    Pipeline6[_T0, _T1, _T2, _T3, _T4, _T5, _OUT],
+    Pipeline5[_T0, _T1, _T2, _T3, _T4, _OUT],
+    Pipeline4[_T0, _T1, _T2, _T3, _OUT],
+    Pipeline3[_T0, _T1, _T2, _OUT],
+    Pipeline2[_T0, _T1, _OUT],
+    Pipeline1[_T0, _OUT],
+    Pipeline0[_OUT],
+]
+
+
+def compose(  # noqa: PLR0911
+    c: Composable[_IN, _T1, _T2, _T3, _T4, _T5, _T6, _OUT],
+) -> Callable[[_IN], _OUT]:
+    """Compose a tuple of compatible functions from first to last.
+
+    Args:
+        c: Compatible functions that can be applied sequentially from first to last.
+
+    Returns:
+        Function that applies the given functions from first to last.
+
+    Example:
+        >>> get_length_string = compose((len, lambda n: f"Length: {n}"))
+        >>> get_length_string("Hello, world!")
+        'Length: 13'
+    """
+    if len(c) == 1:
+        return lambda in_: c[0](in_)
+    if len(c) == 2:  # noqa: PLR2004
+        return lambda in_: c[1](c[0](in_))
+    if len(c) == 3:  # noqa: PLR2004
+        return lambda in_: c[2](c[1](c[0](in_)))
+    if len(c) == 4:  # noqa: PLR2004
+        return lambda in_: c[3](c[2](c[1](c[0](in_))))
+    if len(c) == 5:  # noqa: PLR2004
+        return lambda in_: c[4](c[3](c[2](c[1](c[0](in_)))))
+    if len(c) == 6:  # noqa: PLR2004
+        return lambda in_: c[5](c[4](c[3](c[2](c[1](c[0](in_))))))
+    if len(c) == 7:  # noqa: PLR2004
+        return lambda in_: c[6](c[5](c[4](c[3](c[2](c[1](c[0](in_)))))))
+    return assert_never(c)  # type: ignore [unreachable]  # pragma: no cover
+
+
+def pipe(p: Pipeline[_T0, _T1, _T2, _T3, _T4, _T5, _T6, _OUT]) -> _OUT:
+    """Evaluate a `Pipeline`.
+
+    Args:
+        p:
+            Single value followed by up to seven compatible functions
+            that can be applied sequentially from first to last.
+
+    Returns:
+        Result of sequentially applying the given functions from first to last
+        to the given value.
+
+    Example:
+        >>> pipe(("Hello, world!", len, lambda n: f"Length: {n}"))
+        'Length: 13'
+    """
+    if len(p) == 1:
+        return p[0]
+    return compose(p[1:])(p[0])

trcks/fp/monads/__init__.py

@@ -0,0 +1,3 @@
+"""Monadic functions for generic types."""
+
+__docformat__ = "google"

trcks/fp/monads/awaitable.py

@@ -0,0 +1,182 @@
+"""Monadic functions for `collections.abc.Awaitable`.
+
+Provides utilities for functional composition of asynchronous functions.
+
+Example:
+    >>> import asyncio
+    >>> from trcks.fp.composition import pipe
+    >>> from trcks.fp.monads import awaitable as a
+    >>> async def read_from_disk() -> str:
+    ...     await asyncio.sleep(0.001)
+    ...     input_ = "Hello, world!"
+    ...     print(f"Read '{input_}' from disk.")
+    ...     return input_
+    ...
+    >>> def transform(s: str) -> str:
+    ...     return f"Length: {len(s)}"
+    ...
+    >>> async def write_to_disk(output: str) -> None:
+    ...     await asyncio.sleep(0.001)
+    ...     print(f"Wrote '{output}' to disk.")
+    ...
+    >>> async def main() -> None:
+    ...     awaitable_str = read_from_disk()
+    ...     return await pipe(
+    ...         (awaitable_str, a.map_(transform), a.map_to_awaitable(write_to_disk))
+    ...     )
+    ...
+    >>> asyncio.run(main())
+    Read 'Hello, world!' from disk.
+    Wrote 'Length: 13' to disk.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from trcks._typing import TypeVar
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Awaitable, Callable
+
+__docformat__ = "google"
+
+_T = TypeVar("_T")
+_T1 = TypeVar("_T1")
+_T2 = TypeVar("_T2")
+
+
+async def _construct(value: _T) -> _T:
+    return value
+
+
+def construct(value: _T) -> Awaitable[_T]:
+    """Create an `Awaitable` from a value.
+
+    Args:
+        value: The value to create the `Awaitable` from.
+
+    Returns:
+        The `Awaitable` created from the value.
+
+    Example:
+        >>> import asyncio
+        >>> from collections.abc import Awaitable
+        >>> from trcks.fp.monads import awaitable as a
+        >>> awtbl = a.construct("Hello, world!")
+        >>> isinstance(awtbl, Awaitable)
+        True
+        >>> asyncio.run(a.to_coroutine(awtbl))
+        'Hello, world!'
+    """
+    return _construct(value)
+
+
+def map_(f: Callable[[_T1], _T2]) -> Callable[[Awaitable[_T1]], Awaitable[_T2]]:
+    """Turn synchronous function into function expecting and returning `Awaitable`.
+
+    Args:
+        f:
+            The synchronous function to be transformed into
+            a function expecting and returning an `Awaitable`.
+
+    Returns:
+        The given function transformed into
+        a function expecting and returning an `Awaitable`.
+
+    Note:
+        The underscore in the function name helps to avoid collisions
+        with the built-in function `map`.
+
+    Example:
+        >>> import asyncio
+        >>> from collections.abc import Awaitable
+        >>> from trcks.fp.monads import awaitable as a
+        >>> def transform(s: str) -> str:
+        ...     return f"Length: {len(s)}"
+        ...
+        >>> transform_mapped = a.map_(transform)
+        >>> awaitable_input = a.construct("Hello, world!")
+        >>> awaitable_output = transform_mapped(awaitable_input)
+        >>> isinstance(awaitable_output, Awaitable)
+        True
+        >>> asyncio.run(a.to_coroutine(awaitable_output))
+        'Length: 13'
+
+    """
+
+    def composed_f(value: _T1) -> Awaitable[_T2]:
+        return construct(f(value))
+
+    return map_to_awaitable(composed_f)
+
+
+def map_to_awaitable(
+    f: Callable[[_T1], Awaitable[_T2]],
+) -> Callable[[Awaitable[_T1]], Awaitable[_T2]]:
+    """Turn `Awaitable`-returning func. into func. expecting and returning `Awaitable`.
+
+    Args:
+        f:
+            The `Awaitable`-returning function to be transformed into
+            a function expecting and returning an `Awaitable`.
+
+    Returns:
+        The given function transformed into
+        a function expecting and returning an `Awaitable`.
+
+
+    Example:
+        >>> import asyncio
+        >>> from collections.abc import Awaitable
+        >>> from trcks.fp.monads import awaitable as a
+        >>> async def write_to_disk(output: str) -> None:
+        ...     await asyncio.sleep(0.001)
+        ...     print(f"Wrote '{output}' to disk.")
+        ...
+        >>> write_to_disk_mapped = a.map_to_awaitable(write_to_disk)
+        >>> awaitable_input = a.construct("Hello, world!")
+        >>> awaitable_output = write_to_disk_mapped(awaitable_input)
+        >>> isinstance(awaitable_output, Awaitable)
+        True
+        >>> asyncio.run(a.to_coroutine(awaitable_output))
+        Wrote 'Hello, world!' to disk.
+    """
+
+    async def mapped_f(awaitable: Awaitable[_T1]) -> _T2:
+        return await f(await awaitable)
+
+    return mapped_f
+
+
+async def to_coroutine(awtbl: Awaitable[_T]) -> _T:
+    """Turn an `Awaitable` into a `collections.abc.Coroutine`.
+
+    This is useful for functions that expect a coroutine (e.g. `asyncio.run`).
+
+    Args:
+        awtbl: The `Awaitable` to be transformed into a `collections.abc.Coroutine`.
+
+    Returns:
+        The given `Awaitable` transformed into a `collections.abc.Coroutine`.
+
+    Note:
+        The type `Awaitable` is a supertype of `collections.abc.Coroutine`.
+
+    Example:
+        Transform an `asyncio.Future` into a `collections.abc.Coroutine` and run it:
+
+            >>> import asyncio
+            >>> from trcks.fp.monads import awaitable as a
+            >>> asyncio.set_event_loop(asyncio.new_event_loop())
+            >>> future = asyncio.Future[str]()
+            >>> future.set_result("Hello, world!")
+            >>> future
+            <Future finished result='Hello, world!'>
+            >>> coro = a.to_coroutine(future)
+            >>> coro
+            <coroutine object to_coroutine at 0x...>
+            >>> asyncio.run(coro)
+            'Hello, world!'
+    """
+    return await awtbl