errorz 0.1.0__tar.gz → 0.2.1__tar.gz

{errorz-0.1.0 → errorz-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errorz
-Version: 0.1.0
+Version: 0.2.1
 Summary: Represent fallible computations as values, instead of using exceptions.
 Author: Fábio Macêdo Mendes
 Author-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>

{errorz-0.1.0 → errorz-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "errorz"
-version = "0.1.0"
+version = "0.2.1"
 description = "Represent fallible computations as values, instead of using exceptions."
 readme = "README.md"
 authors = [
@@ -53,6 +53,7 @@ dev = [
     "sphinx-mdinclude>=0.6.2",
     "taskipy>=1.14.1",
 ]
+hypothesis = ["hypothesis>=6.155.2"]
 
 [tool.taskipy.tasks]
 docs = { cmd = "sphinx-build -b html docs/source docs/build", help = "Build HTML documentation" }

{errorz-0.1.0 → errorz-0.2.1}/src/errorz/__init__.py

@@ -24,14 +24,22 @@ help vendorizing it. It is distributed as a package, instead of a errorz.py file
 to allow for py.typed marker.
 """
 
+from __future__ import annotations
+
 import builtins
 import functools
+from collections import deque
 from types import NotImplementedType
 from typing import (
     Any,
     Callable,
     Generic,
+    Hashable,
     Iterable,
+    Iterator,
+    Literal,
+    Mapping,
+    NamedTuple,
     Optional,
     Protocol,
     Self,
@@ -56,9 +64,9 @@ __all__ = (
     "expect",
     "map",
     "coalesce",
-    "values",
+    "filter",
     "zip",
-    "elements",
+    "some",
     "getattr",
     "call",
     "iter",
@@ -73,7 +81,6 @@ T_co = TypeVar("T_co", covariant=True)
 type Result[T, E = Any] = T | Err[E]
 
 
-@final
 class Err(Generic[E_co]):
     """
     A simple error wrapper that implements the Error protocol. It is used to wrap
@@ -81,6 +88,7 @@ class Err(Generic[E_co]):
     """
 
     __is_errorz_error__ = True
+    __match_args__ = ("error",)
 
     @property
     def error(self) -> E_co:
@@ -92,10 +100,14 @@ class Err(Generic[E_co]):
     def __repr__(self) -> str:
         return f"Err({self._error!r})"
 
+    def __hash__[E: Hashable](self: Err[E]) -> int:
+        return hash(self._error)
+
     #
     # Python magic methods
     #
-    def __bool__(self) -> bool:
+    @final
+    def __bool__(self) -> Literal[False]:
         return False
 
     # Arithmetic operations
@@ -207,10 +219,20 @@ class Err(Generic[E_co]):
         return UnwrapError(e)
 
 
+class Tagged[T, B: bool](NamedTuple):
+    value: T
+    is_error: B
+
+
+type IsErr[E] = Tagged[E, Literal[True]]
+type IsOk[T] = Tagged[T, Literal[False]]
+
+
 def _any(x: object) -> Any:
     return x
 
 
+_iter = builtins.iter
 _getattr = builtins.getattr
 
 
@@ -283,6 +305,10 @@ def is_err(value: Result[Any], /) -> TypeIs[Err]:
         False
 
     Notes:
+        The corresponding is_ok() does not exist because typecheckers often struggle
+        with type narrowing because Python type system do not include negative
+        bounds (e.g. "T but not Err").
+
         The Err case evaluates to False. If you known that T is never falsy,
         you can just use the common Pythonic ways of checking for nullable
         values:
@@ -298,34 +324,39 @@ def is_err(value: Result[Any], /) -> TypeIs[Err]:
     return isinstance(value, Err)
 
 
-def is_ok[T](value: Result[T], /) -> TypeIs[T]:
+def check[T](value: Result[T], /) -> TypeIs[T]:
     """
-    Check if result is in the Ok case.
+    Check if value is not an Err and return True.
 
-    Args:
-        value: The result value to check.
+    If the value is an error, raise it or a UnwrapError if E is not an exception.
 
-    Examples:
-        >>> rz.is_ok(rz.err('error'))
-        False
-        >>> rz.is_ok(42)
-        True
+    Args:
+        value: The result value to validate.
     """
-    return not isinstance(value, Err)
+    if isinstance(value, Err):
+        raise value.exception()
+    return True
 
 
-def validate[T](value: Result[T], /) -> TypeIs[T]:
+def tagged[T, E](value: Result[T, E], /) -> IsOk[T] | IsErr[E]:
     """
-    Accept the Ok and return True.
-
-    If the value is an error, raise it or a UnwrapError if E is not an exception.
+    Check if the value is an error and return False if it is, True otherwise.
 
     Args:
-        value: The result value to validate.
+        value: The result value to check.
+
+    Returns:
+        True if the value is not an error, False otherwise.
+
+    Examples:
+        >>> rz.tagged(42)
+        Tagged(value=42, is_error=False)
+        >>> rz.tagged(rz.err('error'))
+        Tagged(value='error', is_error=True)
     """
     if isinstance(value, Err):
-        raise value.exception()
-    return True
+        return cast("IsErr[E]", Tagged(value=value.error, is_error=True))
+    return cast("IsOk[T]", Tagged(value=value, is_error=False))
 
 
 #
@@ -416,6 +447,62 @@ def expect[T](value: Result[T], /, error: str | BaseException) -> T:
     raise UnwrapError(error)
 
 
+def extract[T, E](fn: Callable[[E], T], value: Result[T, E], /) -> T:
+    """
+    Extract the value from the result.
+
+    If it is an error, transform it with the given function.
+
+    Args:
+        fn: The function to apply in case of errors.
+        value: The result value to extract the error from.
+
+    Examples:
+        >>> rz.extract(lambda e: f"error: {e}", rz.err(42))
+        'error: 42'
+        >>> rz.extract(lambda e: str(e), "ok")
+        'ok'
+    """
+    return fn(value.error) if isinstance(value, Err) else value
+
+
+def unpack[T, E, R](
+    value: Result[T, E], /, ok: Callable[[T], R], err: Callable[[E], R]
+) -> R:
+    """
+    Unpack a result value using either the ok or err functions.
+
+    This is useful for chaining operations that may return errors without having to
+    check for errors at each step.
+
+    Args:
+        value:
+            The result value to unpack.
+        ok:
+            The function to apply if the value is an ok value.
+        err:
+            The function to apply if the value is an error.
+
+    Examples:
+        >>> rz.unpack(rz.err("error"), ok=str, err=str.upper)
+        'ERROR'
+        >>> rz.unpack(42, ok=str, err=str.upper)
+        '42'
+
+    Notes:
+        This can be used as a poor-man's match statement. Real match statements
+        are supported, but there is no explicit Ok() case:
+
+        >>> result = rz.err("error")
+        >>> match result:
+        ...     case rz.Err(error):
+        ...         pass # code in the error case
+        ...     case value:
+        ...         pass # code in the ok case
+    """
+    return err(value.error) if isinstance(value, Err) else ok(value)
+
+
 def to_optional[T](value: Result[T, Any]) -> Optional[T]:
     """
     Convert a Result to an Optional by converting any error to None.
@@ -432,6 +519,40 @@ def to_optional[T](value: Result[T, Any]) -> Optional[T]:
     return value
 
 
+def error[Any, E](value: Result[Any, E], /) -> Optional[E]:
+    """
+    Get the error value if the result is an error, None otherwise.
+
+    Args:
+        value: The result value to check.
+    Examples:
+        >>> rz.error(42) is None
+        True
+        >>> rz.error(rz.err('error'))
+        'error'
+    """
+    if isinstance(value, Err):
+        return value.error
+    return None
+
+
+def swap[T, E](value: Result[T, E], /) -> Result[E, T]:
+    """
+    Swap the ok and error values of a result.
+
+    Args:
+        value: The result value to swap.
+    Examples:
+        >>> rz.swap(42)
+        Err(42)
+        >>> rz.swap(rz.err('error'))
+        'error'
+    """
+    if isinstance(value, Err):
+        return value.error
+    return Err(value)
+
+
 @overload
 def map[T, E, R](fn: Callable[[T], R], value: Result[T, E], /) -> Result[R, E]: ...
 
@@ -546,6 +667,28 @@ def map(fn: Any, *values: Any) -> Any:
     return fn(*values)
 
 
+def map_err[T, E, R](fn: Callable[[E], R], value: Result[T, E], /) -> Result[T, R]:
+    """
+    Apply the function to the error value if it is an error, otherwise return
+    the ok value.
+
+    Args:
+        fn:
+            The function to apply to the error case.
+        value:
+            The result value to check.
+
+    Examples:
+        >>> rz.map_err(lambda e: f"error: {e}", rz.err(42))
+        Err('error: 42')
+        >>> rz.map_err(lambda e: f"error: {e}", 42)
+        42
+    """
+    if isinstance(value, Err):
+        return Err(fn(value.error))
+    return value
+
+
 @overload
 def coalesce[T, E](values: Iterable[Result[T, E]], /) -> Result[T, E]: ...
 
@@ -620,48 +763,143 @@ def coalesce[T1, T2, T3, T4, T5, T6, T7, T8, E](
 
 def coalesce(*values: Any) -> Any:
     """
-    Return the first value that is not an error, or the first error if all values are errors.
+    Return the first value that is not an error, or the last error if all values
+    are errors.
+
+    This function works as short-circuiting "or" as if Ok values are thruthy
+    and Err values are falsy.
 
     Examples:
         >>> rz.coalesce(rz.err("e1"), rz.err("e2"), 42, 43, ...)
         42
         >>> rz.coalesce(rz.err("e1"), rz.err("e2"))
-        Err('e1')
+        Err('e2')
         >>> rz.coalesce([rz.err("e1"), rz.err("e2"), 42, 43, ...])
         42
 
     See also:
         - :func:`rz.zip`
-        - :func:`rz.values`
+        - :func:`rz.all`
     """
     if len(values) == 1:
         values = values[0]
 
-    err: Err[Any] | None = None
+    value: Any = None
     for value in values:
         if not isinstance(value, Err):
             return value
-        elif err is None:
-            err = value
-    if err is None:
+    if value is None:
         raise ValueError("coalesce() expected at least one value")
-    return err
+    return value
+
+
+@overload
+def all[T, E](values: Iterable[Result[T, E]], /) -> Result[T, E]: ...
+
+
+@overload
+def all[T1, T2, E1, E2](
+    x1: Result[T1, E1], x2: Result[T2, E2], /
+) -> Result[T1 | T2, E1 | E2]: ...
+
+
+@overload
+def all[T1, T2, T3, E](
+    x1: Result[T1, E], x2: Result[T2, E], x3: Result[T3, E], /
+) -> Result[T1 | T2 | T3, E]: ...
+
+
+@overload
+def all[T1, T2, T3, T4, E](
+    x1: Result[T1, E], x2: Result[T2, E], x3: Result[T3, E], x4: Result[T4, E], /
+) -> Result[T1 | T2 | T3 | T4, E]: ...
+
+
+@overload
+def all[T1, T2, T3, T4, T5, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    x5: Result[T5, E],
+    /,
+) -> Result[T1 | T2 | T3 | T4 | T5, E]: ...
+
+
+@overload
+def all[T1, T2, T3, T4, T5, T6, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    x5: Result[T5, E],
+    x6: Result[T6, E],
+    /,
+) -> Result[T1 | T2 | T3 | T4 | T5 | T6, E]: ...
 
 
-def values[T, E](seq: Iterable[Result[T, E]], /) -> Iterable[T]:
+@overload
+def all[T1, T2, T3, T4, T5, T6, T7, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    x5: Result[T5, E],
+    x6: Result[T6, E],
+    x7: Result[T7, E],
+    /,
+) -> Result[T1 | T2 | T3 | T4 | T5 | T6 | T7, E]: ...
+
+
+@overload
+def all[T1, T2, T3, T4, T5, T6, T7, T8, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    x5: Result[T5, E],
+    x6: Result[T6, E],
+    x7: Result[T7, E],
+    x8: Result[T8, E],
+    /,
+) -> Result[T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8, E]: ...
+
+
+def all(*values: Any) -> Any:
     """
-    Return an iterable of the non-error values in the given sequence.
+    Return the first error in the arguments. If no argument is an error, return
+    the last ok value.
+
+    This function works as short-circuiting "and" as if Ok values are thruthy
+    and Err values are falsy.
 
     Args:
-        seq: The sequence of options to filter.
+        x1, x2, ...:
+            The result values to check.
+            It accepts any number of arguments (but only type checks up to 8).
 
     Examples:
-        >>> list(rz.values([1, 2, rz.err('error'), 3]))
-        [1, 2, 3]
-        >>> list(rz.values([rz.err("error 1"), rz.err("error 2")]))
-        []
+        >>> rz.all(1, 2, 3)
+        3
+        >>> rz.all(1, rz.err("e1"), rz.err("e2"))
+        Err('e1')
+
+    See also:
+        - :func:`rz.coalesce`
     """
-    return (x for x in seq if not isinstance(x, Err))
+    if len(values) == 1:
+        values = values[0]
+
+    if len(values) == 1:
+        values = values[0]
+
+    for value in values:
+        if isinstance(value, Err):
+            return value
+    try:
+        return value  # pyright: ignore[reportPossiblyUnboundVariable]
+    except NameError:
+        raise ValueError("all() expected at least one value")
 
 
 @overload
@@ -761,40 +999,6 @@ def zip(*args: Any) -> Any:
     return args
 
 
-def elements[T, E](value: Result[T, E]) -> Iterable[T]:
-    """
-    Yield nothing or the optional value, if it exists.
-
-    Args:
-        value: The optional value to yield.
-
-    Examples:
-        >>> list(rz.elements(42))
-        [42]
-        >>> list(rz.elements(rz.err('error')))
-        []
-    """
-    if not isinstance(value, Err):
-        yield value
-
-
-def iter[T, E](value: Result[Iterable[T], E]) -> Iterable[T]:
-    """
-    Yield nothing or the elements of an iterable.
-
-    Args:
-        value: The optional iterable to yield from.
-
-    Examples:
-        >>> list(rz.iter([42]))
-        [42]
-        >>> list(rz.iter(rz.err('error')))
-        []
-    """
-    if not isinstance(value, Err):
-        yield from value
-
-
 class Caller[**P, R](Protocol):
     def __call__(
         self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
@@ -1001,3 +1205,218 @@ def _wrap_safe[F: Callable[..., Any]](fn: Any, impl: F) -> F:
     if ret_type is not None:
         impl.__annotations__["return"] = Result[ret_type, Exception]  # type: ignore
     return impl
+
+
+#
+# Lists, iterators, and other collections
+#
+def some[T, E](value: Result[T, E]) -> Iterable[T]:
+    """
+    Yield nothing or the ok value, if it exists.
+
+    Args:
+        value: The fallible value to yield.
+
+    Examples:
+        >>> list(rz.some(42))
+        [42]
+        >>> list(rz.some(rz.err('error')))
+        []
+    """
+    if not isinstance(value, Err):
+        yield value
+
+
+def iter[T, E](value: Result[Iterable[T], E]) -> Iterable[T]:
+    """
+    Yield nothing or the elements of an iterable.
+
+    Args:
+        value: The fallible iterable to yield from.
+
+    Examples:
+        >>> list(rz.iter([42]))
+        [42]
+        >>> list(rz.iter(rz.err('error')))
+        []
+    """
+    if not isinstance(value, Err):
+        yield from value
+
+
+def filter[T, E](seq: Iterable[Result[T, E]], /) -> Iterable[T]:
+    """
+    Return an iterable of the non-error values in the given sequence.
+
+    Args:
+        seq: The sequence of fallible values to filter.
+
+    Examples:
+        >>> list(rz.filter([1, 2, rz.err('error'), 3]))
+        [1, 2, 3]
+        >>> list(rz.filter([rz.err("error 1"), rz.err("error 2")]))
+        []
+    """
+    return (x for x in seq if not isinstance(x, Err))
+
+
+def partition[T, E](seq: Iterable[Result[T, E]], /) -> tuple[Iterable[T], Iterable[E]]:
+    """
+    Partition the given sequence into two sequence: one of non-error values and one of error values.
+
+    Args:
+        seq: The sequence of fallible values to partition.
+
+    Examples:
+        >>> oks, errs = rz.partition([1, 2, rz.err('error'), 3])
+        >>> list(oks)
+        [1, 2, 3]
+        >>> list(errs)
+        ['error']
+    """
+    next = _iter(seq).__next__
+    seen_values = deque["T"]()
+    seen_errors = deque["E"]()
+
+    def oks() -> Iterator[T]:
+        while True:
+            try:
+                if seen_values:
+                    yield seen_values.popleft()
+                    continue
+                if isinstance(value := next(), Err):
+                    seen_errors.append(value.error)
+                    continue
+                yield value
+            except StopIteration:
+                return
+
+    def errors() -> Iterator[E]:
+        while True:
+            try:
+                if seen_errors:
+                    yield seen_errors.popleft()
+                    continue
+                if isinstance(value := next(), Err):
+                    seen_errors.append(value.error)
+                    continue
+                seen_values.append(value)
+            except StopIteration:
+                return
+
+    # Is it faster to use itertools.tee?
+    return oks(), errors()
+
+
+def combine[T, E](seq: Iterable[Result[T, E]], /) -> Result[list[T], E]:
+    """
+    Combine the given sequence of fallible values into a single list if all
+    values are non-errors.
+
+    Return the first error found otherwise.
+
+    Args:
+        seq: The sequence of fallible values to combine.
+
+    Examples:
+        >>> rz.combine([1, 2, 3])
+        [1, 2, 3]
+        >>> rz.combine([1, 2, rz.err('error')])
+        Err('error')
+    """
+    values = []
+    for value in seq:
+        if isinstance(value, Err):
+            return value
+        values.append(value)
+    return values
+
+
+def filter_values[K, V, E](seq: Mapping[K, Result[V, E]], /) -> dict[K, V]:
+    """
+    Remove all Err values from the given mapping.
+
+    Args:
+        seq: The mapping of fallible values to filter.
+
+    Examples:
+        >>> rz.filter_values({'a': 1, 'b': rz.err('error'), 'c': 3})
+        {'a': 1, 'c': 3}
+        >>> rz.filter_values({'a': rz.err("error 1"), 'b': rz.err("error 2")})
+        {}
+    """
+    return {k: v for k, v in seq.items() if not isinstance(v, Err)}
+
+
+@overload
+def non_empty[T](seq: Iterable[T], /) -> Result[list[T], IndexError]: ...
+
+
+@overload
+def non_empty[T, E](seq: Iterable[T], /, error: E) -> Result[list[T], E]: ...
+
+
+def non_empty[T](seq: Iterable[T], /, error: Any = MISSING) -> Result[list[T], Any]:
+    """
+    Return the given sequence if it contains at least one non-error value, or an Error otherwise.
+
+    Args:
+        seq: The sequence of values to check.
+        error: The error to return if the sequence is empty (defaults to IndexError).
+
+    Examples:
+        >>> rz.non_empty([1, 2, 3])
+        [1, 2, 3]
+        >>> rz.non_empty([])
+        Err(IndexError(...))
+        >>> rz.non_empty([], error="Sequence is empty")
+        Err('Sequence is empty')
+    """
+    values = list(seq)
+    if values:
+        return values
+    if error is MISSING:
+        return Err(cast(Any, IndexError("Sequence is empty")))
+    return Err(error)
+
+
+@overload
+def single[T](seq: Iterable[T], /) -> Result[T, IndexError]: ...
+
+
+@overload
+def single[T, E](seq: Iterable[T], /, error: E) -> Result[T, E]: ...
+
+
+def single[T](seq: Iterable[T], /, error: Any = MISSING) -> Result[T, Any]:
+    """
+    Return the single element in the given sequence, or an Error otherwise.
+
+    Args:
+        seq: The sequence of values to check.
+        error: The error to return if the sequence does not contain exactly one non-error value (defaults to IndexError).
+
+    Examples:
+        >>> rz.single([42])
+        42
+        >>> rz.single([])
+        Err(IndexError(...))
+        >>> rz.single([1, 2])
+        Err(IndexError(...))
+        >>> rz.single([], error="No single value")
+        Err('No single value')
+    """
+    it = _iter(seq)
+    try:
+        value = next(it)
+    except StopIteration:
+        if error is MISSING:
+            return Err(cast(Any, IndexError("Sequence is empty")))
+        return Err(error)
+    try:
+        next(it)
+        if error is MISSING:
+            return Err(cast(Any, IndexError("Sequence contains more than one value")))
+        return Err(error)
+    except StopIteration:
+        return value

errorz-0.2.1/src/errorz/__main__.py

@@ -0,0 +1,10 @@
+import doctest
+
+import errorz
+
+if __name__ == "__main__":
+    doctest.testmod(
+        errorz,
+        globs={"rz": errorz},
+        optionflags=doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE,
+    )

{errorz-0.1.0 → errorz-0.2.1}/src/errorz/hypothesis.py

@@ -8,6 +8,8 @@ import errorz as rz
 
 EXCEPTION_LIST = [Exception, ValueError, TypeError, KeyError, IndexError]
 
+__all__ = ["result", "exceptions", "errors", "error_messages"]
+
 
 @st.composite
 def result[T, E = Any](
@@ -17,8 +19,10 @@ def result[T, E = Any](
     Generate Results with random values.
 
     Args:
-        value: A strategy to generate the ok values.
-        error: A strategy to generate the err values.
+        value:
+            A strategy to generate the ok values.
+        error:
+            A strategy to generate the err values.
             If None is given, it will generate random exceptions or primitive values as errors.
     """
 
@@ -43,8 +47,8 @@ def result[T, E = Any](
 
 
 def exceptions(
-    exceptions: Iterable[type[BaseException]] | None = None,
-) -> st.SearchStrategy[BaseException]:
+    exceptions: Iterable[type[Exception]] | None = None,
+) -> st.SearchStrategy[Exception]:
     """
     Generate exceptions with random messages.
 
@@ -60,12 +64,26 @@ def exceptions(
     return st.one_of([st.builds(exc, error_messages()) for exc in exceptions])
 
 
+def errors[E = Exception](
+    error: st.SearchStrategy[E] | None = None,
+) -> st.SearchStrategy[rz.Err[E]]:
+    """
+    Generate random error values.
+
+    By default, it generates random exceptions with random messages.
+    """
+    value = cast("st.SearchStrategy[E]", error or exceptions())
+    return value.map(rz.Err)
+
+
 def error_messages() -> st.SearchStrategy[str]:
     """
     Generate random error messages.
 
     Those are small strings with common letters. We are not trying to stress
     test the string handling capabilities of our error types.
+
+    If you want to stress test this, use the builtin st.text() strategy.
     """
     return st.one_of(
         st.sampled_from(["error", "fail", "invalid", "..."]),

errorz-0.1.0/src/errorz/__main__.py

@@ -1,6 +0,0 @@
-import doctest
-
-import errorz
-
-if __name__ == "__main__":
-    doctest.testmod(errorz, globs={"rz": errorz})