errorz 0.1.0__py3-none-any.whl

errorz/__init__.py

@@ -0,0 +1,1003 @@
+"""
+Copyright (c) 2026, Fábio Macêdo Mendes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This is the main errorz module. It is implemented in a single Python file to
+help vendorizing it. It is distributed as a package, instead of a errorz.py file,
+to allow for py.typed marker.
+"""
+
+import builtins
+import functools
+from types import NotImplementedType
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    Optional,
+    Protocol,
+    Self,
+    TypeIs,
+    TypeVar,
+    cast,
+    final,
+    overload,
+)
+
+# Raised when trying to unwrap a None value. It is an alias for ValueError to allow
+# mocking it in tests (or global mokey-patching if you are feelling adventurous).
+UnwrapError = ValueError
+
+__version__ = "0.1.0"
+__author__ = "Fábio Macêdo Mendes"
+__all__ = (
+    "Result",
+    "UnwrapError",
+    "unwrap",
+    "unwrap_lazy",
+    "expect",
+    "map",
+    "coalesce",
+    "values",
+    "zip",
+    "elements",
+    "getattr",
+    "call",
+    "iter",
+)
+
+MISSING: NotImplementedType = cast(NotImplementedType, object())
+
+E_co = TypeVar("E_co", covariant=True, default=Any, bound=object)
+T_co = TypeVar("T_co", covariant=True)
+
+# type Result[T_co, E_co = Any] = Err[E_co] | T_co
+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
+    error values in a way that they can be distinguished from regular values.
+    """
+
+    __is_errorz_error__ = True
+
+    @property
+    def error(self) -> E_co:
+        return self._error
+
+    def __init__(self, error: E_co) -> None:
+        self._error = error
+
+    def __repr__(self) -> str:
+        return f"Err({self._error!r})"
+
+    #
+    # Python magic methods
+    #
+    def __bool__(self) -> bool:
+        return False
+
+    # Arithmetic operations
+    def __add__(self, other: Any) -> Self:
+        return self
+
+    def __radd__(self, other: Any) -> Self:
+        return self
+
+    def __mul__(self, other: Any) -> Self:
+        return self
+
+    def __rmul__(self, other: Any) -> Self:
+        return self
+
+    def __matmul__(self, other: Any) -> Self:
+        return self
+
+    def __rmatmul__(self, other: Any) -> Self:
+        return self
+
+    def __sub__(self, other: Any) -> Self:
+        return self
+
+    def __rsub__(self, other: Any) -> Self:
+        return self
+
+    def __truediv__(self, other: Any) -> Self:
+        return self
+
+    def __rtruediv__(self, other: Any) -> Self:
+        return self
+
+    def __floordiv__(self, other: Any) -> Self:
+        return self
+
+    def __rfloordiv__(self, other: Any) -> Self:
+        return self
+
+    def __mod__(self, other: Any) -> Self:
+        return self
+
+    def __rmod__(self, other: Any) -> Self:
+        return self
+
+    def __pow__(self, other: Any) -> Self:
+        return self
+
+    def __rpow__(self, other: Any) -> Self:
+        return self
+
+    def __or__(self, other: Any) -> Self:
+        return self
+
+    def __ror__(self, other: Any) -> Self:
+        return self
+
+    def __and__(self, other: Any) -> Self:
+        return self
+
+    def __rand__(self, other: Any) -> Self:
+        return self
+
+    def __xor__(self, other: Any) -> Self:
+        return self
+
+    def __rxor__(self, other: Any) -> Self:
+        return self
+
+    def __rshift__(self, other: Any) -> Self:
+        return self
+
+    def __rrshift__(self, other: Any) -> Self:
+        return self
+
+    def __lshift__(self, other: Any) -> Self:
+        return self
+
+    def __rlshift__(self, other: Any) -> Self:
+        return self
+
+    def __gt__(self, other: Any) -> Self:
+        return self
+
+    def __ge__(self, other: Any) -> Self:
+        return self
+
+    def __le__(self, other: Any) -> Self:
+        return self
+
+    def __lt__(self, other: Any) -> Self:
+        return self
+
+    #
+    # Public methods
+    #
+    def exception(self) -> BaseException:
+        """
+        Return the error as an exception.
+
+        Non-exceptional values are converted to a UnwrapError with self.error
+        as an argument.
+        """
+        e = self._error
+        if isinstance(e, BaseException):
+            return e
+        if isinstance(e, type) and issubclass(e, BaseException):
+            return UnwrapError(e)
+        return UnwrapError(e)
+
+
+def _any(x: object) -> Any:
+    return x
+
+
+_getattr = builtins.getattr
+
+
+#
+# Constructors
+#
+@overload
+def err[E](error: E, /) -> Result[Any, E]: ...
+
+
+@overload
+def err[T, E](error: E, /, type: type[T]) -> Result[T, E]: ...
+
+
+def err(error: Any, /, type: Any = None) -> Any:
+    """
+    Creates an error value.
+
+    Args:
+        error: The error value to wrap.
+
+    Examples:
+        >>> rz.err('error') # type is Result[Any, str]
+        Err('error')
+        >>> rz.err('error', type=int) # type is Result[int, str]
+        Err('error')
+    """
+    return Err(error)
+
+
+@overload
+def ok[T](value: T, /) -> Result[T, Any]: ...
+
+
+@overload
+def ok[T, E](value: T, /, err: type[E]) -> Result[T, E]: ...
+
+
+def ok[T, E](value: Any, /, err: Any = None) -> Any:
+    """
+    Create a success value. This is just an identity function, but it can be used
+    for symmetry with `err` and to make it clear that a value is intended to be a
+    success value.
+
+    You can also pass the type of the error case to appease the type checker.
+
+    Args:
+        value: The success value to return.
+
+    Examples:
+        >>> rz.ok(42) # type is Result[int, Any]
+        42
+        >>> rz.ok(42, err=str) # type is Result[int, str]
+        42
+    """
+    return value
+
+
+def is_err(value: Result[Any], /) -> TypeIs[Err]:
+    """
+    Check if the value is an error.
+
+    Args:
+        value: The result value to check.
+
+    Examples:
+        >>> rz.is_err(rz.err('error'))
+        True
+        >>> rz.is_err(42)
+        False
+
+    Notes:
+        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:
+
+        >>> value = rz.err(42)
+        >>> print(value or "error")
+        error
+        >>> if value:
+        ...     print("This will never be an error case!")
+
+        The same caveats of Optional types apply here.
+    """
+    return isinstance(value, Err)
+
+
+def is_ok[T](value: Result[T], /) -> TypeIs[T]:
+    """
+    Check if result is in the Ok case.
+
+    Args:
+        value: The result value to check.
+
+    Examples:
+        >>> rz.is_ok(rz.err('error'))
+        False
+        >>> rz.is_ok(42)
+        True
+    """
+    return not isinstance(value, Err)
+
+
+def validate[T](value: Result[T], /) -> TypeIs[T]:
+    """
+    Accept the Ok and return True.
+
+    If the value is an error, raise it or a UnwrapError if E is not an exception.
+
+    Args:
+        value: The result value to validate.
+    """
+    if isinstance(value, Err):
+        raise value.exception()
+    return True
+
+
+#
+# Unwrappers
+#
+def unwrap[T](value: Result[T], /, default: T = MISSING) -> T:
+    """
+    Unwrap a result.
+
+    If the value is an error and no default is provided, raise the
+    :meth:`Err.exception` method associated with it.
+
+    Args:
+        value: The result value to unwrap.
+
+    Examples:
+        >>> rz.unwrap(42)
+        42
+        >>> rz.unwrap(rz.err('error'))
+        Traceback (most recent call last):
+        ...
+        ValueError: error
+
+    See also:
+        - :func:`rz.expect`
+        - :func:`rz.unwrap_lazy`
+    """
+    if isinstance(value, Err):
+        if default is MISSING:
+            raise value.exception()
+        return default
+    return value
+
+
+def unwrap_lazy[T](value: Result[T], /, default: Callable[[], T]) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, return the result of
+    calling the default function.
+
+    This may be used instead of :func:`rz.unwrap` when the default value is
+    expensive to compute or produces side effects.
+
+    Args:
+        value: The optional value to unwrap.
+        default: The function to call if the optional value is None.
+
+    Examples:
+        >>> rz.unwrap_lazy(0, lambda: 42)
+        0
+        >>> rz.unwrap_lazy(rz.err('error'), lambda: 42)
+        42
+
+    See also:
+        - :func:`rz.unwrap`
+    """
+    if isinstance(value, Err):
+        if default is MISSING:
+            raise value.exception()
+        return default()
+    return value
+
+
+def expect[T](value: Result[T], /, error: str | BaseException) -> T:
+    """
+    Unwrap a value that may be None. If the value is None, raise the provided
+    error or raises an UnwrapError (ValueError, usually) if a string is
+    provided instead of an exception.
+
+    Args:
+        value: The optional value to unwrap.
+        error: The error to raise if the value is None.
+
+    Examples:
+        >>> rz.expect(42, "Value is None")
+        42
+        >>> rz.expect(rz.err(ZeroDivisionError()), "Value is an error")
+        Traceback (most recent call last):
+        ...
+        ValueError: Value is an error
+
+    See also:
+        - :func:`rz.unwrap`
+    """
+    if not isinstance(value, Err):
+        return value
+    elif isinstance(error, BaseException):
+        raise error
+    raise UnwrapError(error)
+
+
+def to_optional[T](value: Result[T, Any]) -> Optional[T]:
+    """
+    Convert a Result to an Optional by converting any error to None.
+
+    Args:
+        value: The result value to convert.
+
+    Returns:
+        An Optional containing the unwrapped value if it is Ok, or None if it
+        is an Err.
+    """
+    if isinstance(value, Err):
+        return None
+    return value
+
+
+@overload
+def map[T, E, R](fn: Callable[[T], R], value: Result[T, E], /) -> Result[R, E]: ...
+
+
+@overload
+def map[T1, T2, E, R](
+    fn: Callable[[T1, T2], R], x1: Result[T1, E], x2: Result[T2, E], /
+) -> Result[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, E, R](
+    fn: Callable[[T1, T2, T3], R],
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    /,
+) -> Result[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, E, R](
+    fn: Callable[[T1, T2, T3, T4], R],
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    /,
+) -> Result[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, E, R](
+    fn: Callable[[T1, T2, T3, T4, T5], R],
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    x5: Result[T5, E],
+    /,
+) -> Result[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, E, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6], R],
+    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[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, T7, E, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6, T7], R],
+    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[R, E]: ...
+
+
+@overload
+def map[T1, T2, T3, T4, T5, T6, T7, T8, E, R](
+    fn: Callable[[T1, T2, T3, T4, T5, T6, T7, T8], R],
+    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[R, E]: ...
+
+
+def map(fn: Any, *values: Any) -> Any:
+    """
+    Apply the function to the values if none of them are errors, otherwise
+    return the first error found.
+
+
+    Args:
+        fn:
+            The function to apply to the values if none of them are errors.
+        x1, x2, ...:
+            The result values to apply the function to.
+            It accepts any number of arguments (but only type checks up to 8).
+
+    Examples:
+        >>> rz.map(lambda x: x + 1, 41)
+        42
+        >>> rz.map(lambda x, y: x + y, 40, 2)
+        42
+        >>> rz.map(lambda x, y: x + y, 42, rz.err('error'))
+        Err('error')
+
+    See also:
+        - :func:`rz.zip`
+    """
+    if any(is_err(value) for value in values):
+        return next(value for value in values if is_err(value))
+    return fn(*values)
+
+
+@overload
+def coalesce[T, E](values: Iterable[Result[T, E]], /) -> Result[T, E]: ...
+
+
+@overload
+def coalesce[T1, T2, E1, E2](
+    x1: Result[T1, E1], x2: Result[T2, E2], /
+) -> Result[T1 | T2, E1 | E2]: ...
+
+
+@overload
+def coalesce[T1, T2, T3, E](
+    x1: Result[T1, E], x2: Result[T2, E], x3: Result[T3, E], /
+) -> Result[T1 | T2 | T3, E]: ...
+
+
+@overload
+def coalesce[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 coalesce[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 coalesce[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]: ...
+
+
+@overload
+def coalesce[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 coalesce[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 coalesce(*values: Any) -> Any:
+    """
+    Return the first value that is not an error, or the first error if all values are errors.
+
+    Examples:
+        >>> rz.coalesce(rz.err("e1"), rz.err("e2"), 42, 43, ...)
+        42
+        >>> rz.coalesce(rz.err("e1"), rz.err("e2"))
+        Err('e1')
+        >>> rz.coalesce([rz.err("e1"), rz.err("e2"), 42, 43, ...])
+        42
+
+    See also:
+        - :func:`rz.zip`
+        - :func:`rz.values`
+    """
+    if len(values) == 1:
+        values = values[0]
+
+    err: Err[Any] | None = None
+    for value in values:
+        if not isinstance(value, Err):
+            return value
+        elif err is None:
+            err = value
+    if err is None:
+        raise ValueError("coalesce() expected at least one value")
+    return err
+
+
+def values[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 options to filter.
+
+    Examples:
+        >>> list(rz.values([1, 2, rz.err('error'), 3]))
+        [1, 2, 3]
+        >>> list(rz.values([rz.err("error 1"), rz.err("error 2")]))
+        []
+    """
+    return (x for x in seq if not isinstance(x, Err))
+
+
+@overload
+def zip[T1, T2, E](
+    x1: Result[T1, E], x2: Result[T2, E], /
+) -> Result[tuple[T1, T2], E]: ...
+
+
+@overload
+def zip[T1, T2, T3, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    /,
+) -> Result[tuple[T1, T2, T3], E]: ...
+
+
+@overload
+def zip[T1, T2, T3, T4, E](
+    x1: Result[T1, E],
+    x2: Result[T2, E],
+    x3: Result[T3, E],
+    x4: Result[T4, E],
+    /,
+) -> Result[tuple[T1, T2, T3, T4], E]: ...
+
+
+@overload
+def zip[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[tuple[T1, T2, T3, T4, T5], E]: ...
+
+
+@overload
+def zip[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[tuple[T1, T2, T3, T4, T5, T6], E]: ...
+
+
+@overload
+def zip[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[tuple[T1, T2, T3, T4, T5, T6, T7], E]: ...
+
+
+@overload
+def zip[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[tuple[T1, T2, T3, T4, T5, T6, T7, T8], E]: ...
+
+
+def zip(*args: Any) -> Any:
+    """
+    Return a tuple if no argument is an error and the first error otherwise.
+
+    Args:
+        x1, x2, ...:
+            The optional values to check.
+            It accepts any number of arguments (but only type checks up to 8).
+
+    Examples:
+        >>> rz.zip(1, 2, 3)
+        (1, 2, 3)
+        >>> rz.zip(1, 2, rz.err('error'))
+        Err('error')
+
+    """
+    for arg in args:
+        if isinstance(arg, Err):
+            return arg
+    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
+    ) -> R: ...
+
+
+class _CallFactory:
+    """
+    Call the optional function with the given arguments or return the error.
+
+    Args:
+        fn: The fallible function to call.
+        *args: The positional arguments to pass to the function.
+        **kwargs: The keyword arguments to pass to the function.
+
+    Examples:
+        >>> rz.call(lambda x: x + 1, 41)
+        42
+        >>> rz.call(rz.err('error'), 40, 2)
+        Err('error')
+
+        We can assign the error type using the indexing notation.
+
+        >>> rz.call[ZeroDivisionError](lambda x: 1 / x, 0)
+        Err(ZeroDivisionError('division by zero'))
+    """
+
+    @overload
+    def __getitem__[E: Exception, R, **P](
+        self, type: type[E]
+    ) -> Caller[P, Result[R, E]]: ...
+
+    @overload
+    def __getitem__[E1: Exception, E2: Exception, R, **P](
+        self, type: tuple[type[E1], type[E2]]
+    ) -> Caller[P, Result[R, E1 | E2]]: ...
+
+    @overload
+    def __getitem__[E1: Exception, E2: Exception, E3: Exception, R, **P](
+        self, type: tuple[type[E1], type[E2], type[E3]]
+    ) -> Caller[P, Result[R, E1 | E2 | E3]]: ...
+
+    @overload
+    def __getitem__[E1: Exception, E2: Exception, E3: Exception, E4: Exception, R, **P](
+        self, type: tuple[type[E1], type[E2], type[E3], type[E4]]
+    ) -> Caller[P, Result[R, E1 | E2 | E3 | E4]]: ...
+
+    @overload
+    def __getitem__[E: Exception, R, **P](
+        self, type: tuple[E, ...]
+    ) -> Caller[P, Result[R, E]]: ...
+
+    def __getitem__(self, type: Any) -> Any:
+        def call(*args: Any, **kwargs: Any) -> Any:
+            return call_checked(type, *args, **kwargs)
+
+        try:
+            call.__name__ = f"call[{type.__name__}]"
+        except AttributeError:  # type is given as a tuple
+            call.__name__ = "call[...]"
+
+        return call
+
+    def __call__[**P, R](
+        self, fn: Callable[P, R], /, *args: P.args, **kwargs: P.kwargs
+    ) -> Result[R, BaseException]:
+        if isinstance(fn, Err):
+            return fn
+        try:
+            return fn(*args, **kwargs)
+        except BaseException as e:
+            return Err(e)
+
+
+call = _CallFactory()
+
+
+def call_checked[**P, R, E: Exception](
+    errors: type[E] | tuple[type[E], ...],
+    fn: Callable[P, R],
+    /,
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> Result[R, E]:
+    """
+    Call the function with the given arguments and catch any exception of the given type.
+
+    Args:
+        exception: The type of exception to catch and return as an error.
+        fn: The function to call.
+        *args: The positional arguments to pass to the function.
+        **kwargs: The keyword arguments to pass to the function.
+
+    Examples:
+        >>> rz.call_checked(ZeroDivisionError, lambda x: 1 / x, 0)
+        Err(ZeroDivisionError('division by zero'))
+        >>> rz.call_checked(ValueError, lambda x: 1 / x, 0)
+        Traceback (most recent call last):
+        ...
+        ZeroDivisionError: division by zero
+    """
+    try:
+        return fn(*args, **kwargs)
+    except BaseException as e:
+        if isinstance(e, errors):
+            return Err(e)
+        raise e
+
+
+@overload
+def safe[**P, R]() -> Callable[[Callable[P, R]], Callable[P, Result[R, Exception]]]: ...
+
+
+@overload
+def safe[E: Exception, **P, R](
+    exception: type[E], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E]]]: ...
+
+
+@overload
+def safe[E1: Exception, E2: Exception, R, **P](
+    exception: tuple[type[E1], type[E2]], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1 | E2]]]: ...
+
+
+@overload
+def safe[E1: Exception, E2: Exception, E3: Exception, R, **P](
+    exception: tuple[type[E1], type[E2], type[E3]], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1 | E2 | E3]]]: ...
+
+
+@overload
+def safe[E1: Exception, E2: Exception, E3: Exception, E4: Exception, R, **P](
+    exception: tuple[type[E1], type[E2], type[E3], type[E4]], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E1 | E2 | E3 | E4]]]: ...
+
+
+@overload
+def safe[E: Exception, R, **P](
+    exception: Iterable[type[E]], /
+) -> Callable[[Callable[P, R]], Callable[P, Result[R, E]]]: ...
+
+
+@overload
+def safe(*args: Any) -> Any: ...
+
+
+def safe(*errors: Any) -> Any:
+    if not errors:
+        return lambda fn: _wrap_safe(
+            fn, lambda *args, **kwargs: call(fn, *args, **kwargs)
+        )
+    else:
+        return lambda fn: _wrap_safe(
+            fn, lambda *args, **kwargs: call_checked(errors, fn, *args, **kwargs)
+        )
+
+
+def getattr[T, R: type, E](
+    obj: Result[T, E], attr: str, *, type: type[R] = _any(None)
+) -> Result[R, E | AttributeError]:
+    """
+    Get the attribute of an object if it is not None, otherwise return None.
+
+    It raises an AttributeError if the attribute do not exist.
+
+    You can optionally specify the expected result type to get better type checking.
+
+    Args:
+        obj: The optional object to get the attribute from.
+        attr: The name of the attribute to get.
+        type: The expected type of the attribute (optional).
+
+    Examples:
+        >>> rz.getattr(42, "real")
+        42
+        >>> rz.getattr(rz.err('error'), "imag")
+        Err('error')
+        >>> rz.getattr(42, "non_existent")
+        Err(AttributeError('non_existent'))
+    """
+    if isinstance(obj, Err):
+        return Err(obj.error)
+
+    try:
+        value = cast("R", _getattr(obj, attr))
+    except AttributeError:
+        return Err(AttributeError(attr))
+    if type is not None and not isinstance(value, type):
+        msg = (
+            f"Expected attribute {attr} to be of type {type}, "
+            f"got {builtins.type(value)}"
+        )
+        raise TypeError(msg)
+    return value
+
+
+def _wrap_safe[F: Callable[..., Any]](fn: Any, impl: F) -> F:
+    try:
+        functools.update_wrapper(impl, fn)
+    except Exception:
+        return impl
+    ret_type = impl.__annotations__.get("return", None)
+    if ret_type is not None:
+        impl.__annotations__["return"] = Result[ret_type, Exception]  # type: ignore
+    return impl

errorz/__main__.py

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

errorz/hypothesis.py

@@ -0,0 +1,76 @@
+from string import ascii_letters, digits
+from typing import Any, Iterable, cast
+
+from hypothesis import strategies as st
+from hypothesis.strategies import DrawFn
+
+import errorz as rz
+
+EXCEPTION_LIST = [Exception, ValueError, TypeError, KeyError, IndexError]
+
+
+@st.composite
+def result[T, E = Any](
+    draw: DrawFn, value: st.SearchStrategy[T], error: st.SearchStrategy[E] | None = None
+) -> rz.Result[T, E]:
+    """
+    Generate Results with random values.
+
+    Args:
+        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.
+    """
+
+    is_ok = draw(st.booleans())
+    if is_ok:
+        return rz.ok(draw(value))
+    elif error:
+        return rz.err(draw(error))
+    else:
+        return cast(
+            "rz.Err[E]",
+            rz.err(
+                draw(
+                    st.one_of(
+                        error_messages(),
+                        exceptions(),
+                        st.integers(),
+                    )
+                )
+            ),
+        )
+
+
+def exceptions(
+    exceptions: Iterable[type[BaseException]] | None = None,
+) -> st.SearchStrategy[BaseException]:
+    """
+    Generate exceptions with random messages.
+
+    By default, it generates a random exception from builtin python exceptions
+    with a random message.
+
+    You can also provide a custom list of exception classes to choose from.
+    They must accept a single string argument in their constructor.
+    """
+    if exceptions is None:
+        exceptions = EXCEPTION_LIST
+
+    return st.one_of([st.builds(exc, error_messages()) for exc in exceptions])
+
+
+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.
+    """
+    return st.one_of(
+        st.sampled_from(["error", "fail", "invalid", "..."]),
+        st.text(
+            alphabet=ascii_letters + digits + " ",
+            max_size=5,
+        ),
+    )

errorz/mypy.py

@@ -0,0 +1,53 @@
+from functools import partial
+from typing import Callable
+
+import rich
+from mypy.plugin import AnalyzeTypeContext, FunctionContext, Plugin
+from mypy.types import Type
+
+type TypeAnaliser = Callable[[AnalyzeTypeContext], Type]
+type FunctionAnalyser = Callable[[FunctionContext], Type]
+
+
+class ResultPlugin(Plugin):
+    def get_type_analyze_hook(self, fullname: str) -> TypeAnaliser | None:
+        # if fullname == "errorz.Result":
+        #     return analyse_result_type
+        return None
+
+    def get_function_hook(self, fullname: str) -> FunctionAnalyser | None:
+        if fullname.startswith("builtins."):
+            return None
+
+        return partial(analyse_result_module_function, fullname)
+
+
+def analyse_result_type(ctx: AnalyzeTypeContext) -> Type:
+    if ctx.context.line not in lines:
+        print(f"Analyzing type: {ctx.type}  {ctx.context.line}")
+        lines.add(ctx.context.line)
+
+    try:
+        return ctx.api.analyze_type(ctx.type)
+    except Exception:
+        # print(f"Error analyzing type: {e}")
+        return ctx.type
+
+
+def analyse_result_module_function(name: str, ctx: FunctionContext) -> Type:
+    if ctx.context.line < 840:
+        return ctx.default_return_type
+
+    print(f"Analyzing function: {name} (line {ctx.context.line})")
+    rich.print(ctx)
+
+    # print(vars(ctx))
+    return ctx.default_return_type
+
+
+def plugin(version: str) -> type[ResultPlugin]:
+    print(f"Loading plugin for mypy version {version}")
+    return ResultPlugin
+
+
+lines: set[int] = {842, 843, 844}

errorz-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: errorz
+Version: 0.1.0
+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>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Maintainer: Fábio Macêdo Mendes
+Maintainer-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>
+Requires-Python: >=3.13
+Project-URL: Homepage, http://github.com/fabiommendes/errorz
+Project-URL: Repository, http://github.com/fabiommendes/errorz
+Project-URL: Documentation, https://errorz.readthedocs.io/
+Description-Content-Type: text/markdown
+
+# Errorz
+
+Python officially handle errors using exceptions. This library provides a
+lightweight approach inspired by the `Result` type used in Rust and other
+functional programming languages: `Result` is an union between a success value 
+and an error value.
+
+The main advantage over exceptions is that they are expressed as values in the
+type system. This allows for better static guarantees and make code more
+explicit and easier to compose, since results are just like any other value that
+can be passed around and manipulated without cluncky try/catch blocks.
+Exceptions also break control flow and can be easily forgotten and lead to
+crashes and brittle refactorings.
+
+The cannonical way to implement this pattern is to use a tagged union of `Ok[T]`
+and `Err[E]`. This is what Rust and Haskell do and there are some Python
+libraries that follow this approach, e.g.,
+[returns](https://returns.readthedocs.io/). However, Python don't have native
+tagged unions and using them often feels unergnomic and non-Pythonic. This
+library explores a more lightweight approach that defines `Result[T, E] = T |
+Error[E]`, where `Error[E]` is a special abstract wrapper around an error value.
+This is simular to the approach we used in the
+[optionz](https://optionz.readthedocs.io/) library for nullables, where it was
+more lightweight and in line with established Python idioms.
+
+## Installation
+
+Install Errorz using pip/uv/poetry whatever you like. For example:
+
+```bash
+pip install errorz
+```
+    
+Errorz consists of a single file, so you can also just copy the `__init__.py`
+file to your project as `errorz.py` and import it from there. Our special Error 
+wrapper is defined as a protocol and has some special structure to ensure that
+different copies of the vendorized lib can coexist without conflicts.
+
+
+## Usage
+
+Import `err` and use the functions as needed. 
+
+```python
+import errorz as rz
+
+rz.unwrap(42) # 42
+rz.unwrap(rz.err("error")) # raises ValueError
+```
+
+## Documentation
+
+The documentation is available at https://optionz.rtfd.io/ and includes more 
+examples and explanations of the functions provided by the library.
+
+## License
+
+Optionz is licensed under the MIT License. See [LICENSE](LICENSE) for more details.

errorz-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+errorz/__init__.py,sha256=ahht4Ka5Y5r-C2T7KEPoMefaXbNcoS_lAdt0IzS2ipw,24548
+errorz/__main__.py,sha256=j1z1GICc-gIr49P0hUdd6KkfH2gENhtrhuJ21BtqlwI,108
+errorz/hypothesis.py,sha256=3FSD5koHnE98LNwjpOjnFWcmDlM500S9Meisaum0Yx0,2135
+errorz/mypy.py,sha256=iAuqPkxk879ZurINPLjeUmDZ-XioUTnmFDwymAEL8zc,1511
+errorz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+errorz-0.1.0.dist-info/WHEEL,sha256=8ZlpUMJ7mlDirmlHRhDirEx_nPnARrwDjeE92mlk68E,81
+errorz-0.1.0.dist-info/METADATA,sha256=TRbUywrclPUB_1CZIUgZ_o9QJV9GJAfAUIVqhjAPU7w,3148
+errorz-0.1.0.dist-info/RECORD,,

errorz-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.21
+Root-Is-Purelib: true
+Tag: py3-none-any