v0.8.0

dev_tools/update_readme.py

@@ -6,8 +6,7 @@
 import attrs
 
 from danom import (
-    Err,
-    Ok,
+    Result,
     Stream,
     all_of,
     any_of,
@@ -34,7 +33,7 @@ def to_readme(self) -> str:
 def create_readme_lines() -> str:
     readme_lines = []
 
-    for ent in [Stream, Ok, Err]:
+    for ent in [Stream, Result]:
         readme_lines.append(f"## {ent.__name__}")
         readme_lines.append(strip_doc(ent.__doc__))
         readme_docs = [

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "danom"
-version = "0.7.0"
+version = "0.8.0"
 description = "Functional streams and monads"
 readme = "README.md"
 license = "MIT"

src/danom/__init__.py

@@ -1,7 +1,5 @@
-from danom._err import Err
 from danom._new_type import new_type
-from danom._ok import Ok
-from danom._result import Result
+from danom._result import Err, Ok, Result
 from danom._safe import safe, safe_method
 from danom._stream import Stream
 from danom._utils import all_of, any_of, compose, identity, invert, none_of

src/danom/_new_type.py

@@ -19,6 +19,7 @@ def new_type(  # noqa: ANN202
     """Create a NewType based on another type.
 
     ```python
+    >>> from danom import new_type
     >>> def is_positive(value):
     ...     return value >= 0
 
@@ -35,6 +36,7 @@ def new_type(  # noqa: ANN202
     The methods of the given `base_type` will be forwarded to the specialised type.
     Alternatively the map method can be used to return a new type instance with the transformation.
     ```python
+    >>> from danom import new_type
     >>> def has_len(email: str) -> bool:
     ... return len(email) > 0
 

src/danom/_result.py

@@ -2,33 +2,171 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Callable
+from types import TracebackType
 from typing import (
-    ParamSpec,
+    Any,
+    Literal,
     Self,
-    TypeVar,
 )
 
 import attrs
 
-T = TypeVar("T")
-P = ParamSpec("P")
-
 
 @attrs.define
-class Result(ABC):
+class Result[T, U](ABC):
+    """`Result` monad. Consists of `Ok` and `Err` for successful and failed operations respectively.
+    Each monad is a frozen instance to prevent further mutation.
+    """
+
+    @classmethod
+    def unit(cls, inner: T) -> Ok[T]:
+        """Unit method. Given an item of type `T` return `Ok(T)`
+
+        ```python
+        >>> from danom import Err, Ok, Result
+        >>> Result.unit(0) == Ok(inner=0)
+        >>> Ok.unit(0) == Ok(inner=0)
+        >>> Err.unit(0) == Ok(inner=0)
+        ```
+        """
+        return Ok(inner)
+
     @abstractmethod
-    def is_ok(self) -> bool: ...
+    def is_ok(self) -> bool:
+        """Returns `True` if the result type is `Ok`.
+        Returns `False` if the result type is `Err`.
+
+        ```python
+        >>> from danom import Err, Ok
+        >>> Ok().is_ok() == True
+        >>> Err().is_ok() == False
+        ```
+        """
+        ...
 
     @abstractmethod
-    def and_then(self, func: Callable[[T], Result], **kwargs: dict) -> Result: ...
+    def map(self, func: Callable[[T], U], **kwargs: dict) -> Result[U]:
+        """Pipe a pure function and wrap the return value with `Ok`.
+        Given an `Err` will return self.
+
+        ```python
+        >>> from danom import Err, Ok
+        >>> Ok(1).map(add_one) == Ok(2)
+        >>> Err(error=TypeError()).map(add_one) == Err(error=TypeError())
+        ```
+        """
+        ...
 
     @abstractmethod
-    def unwrap(self) -> T: ...
+    def and_then(self, func: Callable[[T], Result[U]], **kwargs: dict) -> Result[U]:
+        """Pipe another function that returns a monad. For `Err` will return original error.
+
+        ```python
+        >>> from danom import Err, Ok
+        >>> Ok(1).and_then(add_one) == Ok(2)
+        >>> Ok(1).and_then(raise_err) == Err(error=TypeError())
+        >>> Err(error=TypeError()).and_then(add_one) == Err(error=TypeError())
+        >>> Err(error=TypeError()).and_then(raise_value_err) == Err(error=TypeError())
+        ```
+        """
+        ...
+
+    @abstractmethod
+    def unwrap(self) -> T:
+        """Unwrap the `Ok` monad and get the inner value.
+        Unwrap the `Err` monad will raise the inner error.
+        ```python
+        >>> from danom import Err, Ok
+        >>> Ok().unwrap() == None
+        >>> Ok(1).unwrap() == 1
+        >>> Ok("ok").unwrap() == 'ok'
+        >>> Err(error=TypeError()).unwrap() raise TypeError(...)
+        ```
+        """
+        ...
 
     @abstractmethod
     def match(
-        self, if_ok_func: Callable[[T], Result], _if_err_func: Callable[[T], Result]
-    ) -> Result: ...
+        self, if_ok_func: Callable[[T], Result], if_err_func: Callable[[T], Result]
+    ) -> Result:
+        """Map `ok_func` to `Ok` and `err_func` to `Err`
+
+        ```python
+        >>> from danom import Err, Ok
+        >>> Ok(1).match(add_one, mock_get_error_type) == Ok(inner=2)
+        >>> Ok("ok").match(double, mock_get_error_type) == Ok(inner='okok')
+        >>> Err(error=TypeError()).match(double, mock_get_error_type) == Ok(inner='TypeError')
+        ```
+        """
+        ...
 
     def __class_getitem__(cls, _params: tuple) -> Self:
         return cls
+
+
+@attrs.define(frozen=True)
+class Ok[T, U](Result):
+    inner: Any = attrs.field(default=None)
+
+    def is_ok(self) -> Literal[True]:
+        return True
+
+    def map(self, func: Callable[[T], U], **kwargs: dict) -> Result[U]:
+        return Ok(func(self.inner, **kwargs))
+
+    def and_then(self, func: Callable[[T], Result[U]], **kwargs: dict) -> Result[U]:
+        return func(self.inner, **kwargs)
+
+    def unwrap(self) -> T:
+        return self.inner
+
+    def match(
+        self, if_ok_func: Callable[[T], Result], _if_err_func: Callable[[T], Result]
+    ) -> Result:
+        return if_ok_func(self.inner)
+
+
+@attrs.define(frozen=True)
+class Err[T, U, E](Result):
+    error: E | Exception | None = attrs.field(default=None)
+    input_args: tuple[T] = attrs.field(default=None, repr=False)
+    details: list[dict[str, Any]] = attrs.field(factory=list, init=False, repr=False)
+
+    def __attrs_post_init__(self) -> None:
+        if isinstance(self.error, Exception):
+            # little hack explained here: https://www.attrs.org/en/stable/init.html#post-init
+            object.__setattr__(self, "details", self._extract_details(self.error.__traceback__))
+
+    def _extract_details(self, tb: TracebackType | None) -> list[dict[str, Any]]:
+        trace_info = []
+        while tb:
+            frame = tb.tb_frame
+            trace_info.append(
+                {
+                    "file": frame.f_code.co_filename,
+                    "func": frame.f_code.co_name,
+                    "line_no": tb.tb_lineno,
+                    "locals": frame.f_locals,
+                },
+            )
+            tb = tb.tb_next
+        return trace_info
+
+    def is_ok(self) -> Literal[False]:
+        return False
+
+    def map(self, _: Callable[[T], U], **_kwargs: dict) -> Result[U]:
+        return self
+
+    def and_then(self, _: Callable[[T], Result[U]], **_kwargs: dict) -> Self:
+        return self
+
+    def unwrap(self) -> None:
+        if isinstance(self.error, Exception):
+            raise self.error
+        raise ValueError(f"Err does not have a caught error to raise: {self.error = }")
+
+    def match(
+        self, _if_ok_func: Callable[[T], Result], if_err_func: Callable[[T], Result]
+    ) -> Result:
+        return if_err_func(self.error)