fates 0.1.0__tar.gz

fates-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.3
+Name: fates
+Version: 0.1.0
+Summary: A generic Result[T, E] type for explicit error propagation.
+Author: Evgeny Goryachev
+Author-email: Evgeny Goryachev <saladware46@gmail.com>
+Requires-Dist: typing-extensions>=4.0.0 ; python_full_version < '3.12'
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# fates 🔮
+
+A robust, fully-typed, and async-ready Result pattern implementation for Python.
+
+`fates` brings expressive, functional error handling to Python, completely removing the need for defensive `try/except` blocks. It helps you build predictable pipelines with absolute type safety for both synchronous and asynchronous operations.
+
+---
+
+## ✨ Features
+
+- **🛡️ 100% Type Safe:** Full `mypy` / `pyright` compliance using generic protocols and `TypeVar` covariance.
+- **⚡ Async Native:** First-class support for asynchronous mapping and monadic binding.
+- **🧩 Zero Dependencies:** Lightweight and clean, relying only on standard library primitives (and `typing_extensions` for older Python versions).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install fates
+```
+
+---
+
+## 📖 Quick Start
+
+### Synchronous Usage
+
+```python
+from fates import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[float, str]:
+    if b == 0:
+        return Err("Cannot divide by zero")
+    return Ok(a / b)
+
+# Monadic binding and mapping
+result = (
+    divide(10, 2)
+    .map(lambda x: x * 2)
+    .unwrap_or(0.0)
+)
+print(result)  # Output: 10.0
+```
+
+### Asynchronous Pipelines
+
+`fates` shines when working with async databases or HTTP clients. Use `amap` and `abind` to pipe async operations seamlessly.
+
+```python
+import asyncio
+from fates import Ok, Err, Result
+
+async def fetch_user_id(username: str) -> Result[int, str]:
+    # Simulating async DB call
+    await asyncio.sleep(0.1)
+    return Ok(42) if username == "admin" else Err("User not found")
+
+async def get_user_role_async(user_id: int) -> Result[str, str]:
+    await asyncio.sleep(0.1)
+    return Ok("superuser")
+
+async def main():
+    # Chain async functions using abind
+    pipeline = await fetch_user_id("admin").abind(get_user_role_async)
+    
+    print(pipeline)  # Output: Ok('superuser')
+    print(pipeline.unwrap())  # Output: superuser
+
+asyncio.run(main())
+```
+
+---
+
+## 🛠️ API Reference
+
+### Extracting Values
+
+- `.unwrap()` — Returns the success value or raises an `UnwrapError`.
+- `.unwrap_or(default)` — Returns the success value or a fallback value.
+- `.unwrap_err()` — Returns the error value or raises an `UnwrapError`.
+- `.expect(note)` — Returns the success value or crashes with a custom message.
+
+### Transforming Results
+
+- `.map(mapper)` — Transforms the success value inside `Ok`.
+- `.map_err(mapper)` — Transforms the error value inside `Err`.
+- `.bind(binder)` — Monadic bind. Chains another operation that returns a `Result`.
+- `.catch(binder)` — Recovers from an error by returning an alternative `Result`.
+- `.resolve(mapper)` — Merges both paths into a single success-type value.
+
+### Async Operations
+
+- `.amap(async_mapper)` — Asynchronously transforms the success value.
+- `.amap_err(async_mapper)` — Asynchronously transforms the error value.
+- `.abind(async_binder)` — Asynchronously chains another operation returning a `Result`.
+
+---
+
+## ⚖️ License
+
+This project is licensed under the [MIT License](LICENSE).

fates-0.1.0/README.md

@@ -0,0 +1,102 @@
+# fates 🔮
+
+A robust, fully-typed, and async-ready Result pattern implementation for Python.
+
+`fates` brings expressive, functional error handling to Python, completely removing the need for defensive `try/except` blocks. It helps you build predictable pipelines with absolute type safety for both synchronous and asynchronous operations.
+
+---
+
+## ✨ Features
+
+- **🛡️ 100% Type Safe:** Full `mypy` / `pyright` compliance using generic protocols and `TypeVar` covariance.
+- **⚡ Async Native:** First-class support for asynchronous mapping and monadic binding.
+- **🧩 Zero Dependencies:** Lightweight and clean, relying only on standard library primitives (and `typing_extensions` for older Python versions).
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install fates
+```
+
+---
+
+## 📖 Quick Start
+
+### Synchronous Usage
+
+```python
+from fates import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[float, str]:
+    if b == 0:
+        return Err("Cannot divide by zero")
+    return Ok(a / b)
+
+# Monadic binding and mapping
+result = (
+    divide(10, 2)
+    .map(lambda x: x * 2)
+    .unwrap_or(0.0)
+)
+print(result)  # Output: 10.0
+```
+
+### Asynchronous Pipelines
+
+`fates` shines when working with async databases or HTTP clients. Use `amap` and `abind` to pipe async operations seamlessly.
+
+```python
+import asyncio
+from fates import Ok, Err, Result
+
+async def fetch_user_id(username: str) -> Result[int, str]:
+    # Simulating async DB call
+    await asyncio.sleep(0.1)
+    return Ok(42) if username == "admin" else Err("User not found")
+
+async def get_user_role_async(user_id: int) -> Result[str, str]:
+    await asyncio.sleep(0.1)
+    return Ok("superuser")
+
+async def main():
+    # Chain async functions using abind
+    pipeline = await fetch_user_id("admin").abind(get_user_role_async)
+    
+    print(pipeline)  # Output: Ok('superuser')
+    print(pipeline.unwrap())  # Output: superuser
+
+asyncio.run(main())
+```
+
+---
+
+## 🛠️ API Reference
+
+### Extracting Values
+
+- `.unwrap()` — Returns the success value or raises an `UnwrapError`.
+- `.unwrap_or(default)` — Returns the success value or a fallback value.
+- `.unwrap_err()` — Returns the error value or raises an `UnwrapError`.
+- `.expect(note)` — Returns the success value or crashes with a custom message.
+
+### Transforming Results
+
+- `.map(mapper)` — Transforms the success value inside `Ok`.
+- `.map_err(mapper)` — Transforms the error value inside `Err`.
+- `.bind(binder)` — Monadic bind. Chains another operation that returns a `Result`.
+- `.catch(binder)` — Recovers from an error by returning an alternative `Result`.
+- `.resolve(mapper)` — Merges both paths into a single success-type value.
+
+### Async Operations
+
+- `.amap(async_mapper)` — Asynchronously transforms the success value.
+- `.amap_err(async_mapper)` — Asynchronously transforms the error value.
+- `.abind(async_binder)` — Asynchronously chains another operation returning a `Result`.
+
+---
+
+## ⚖️ License
+
+This project is licensed under the [MIT License](LICENSE).

fates-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "fates"
+version = "0.1.0"
+description = "A generic Result[T, E] type for explicit error propagation."
+readme = "README.md"
+authors = [{ name = "Evgeny Goryachev", email = "saladware46@gmail.com" }]
+requires-python = ">=3.7"
+dependencies = ["typing_extensions>=4.0.0; python_version < '3.12'"]
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812"]
+external = ["WPS"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/test_*.py" = ["S101", "D", "PLR2004"]
+
+[tool.ty.rules]
+all = "error"
+
+[tool.mypy]
+strict = true
+packages = ["fates", "tests"]
+
+[tool.pytest.ini_options]
+
+asyncio_mode = "auto"
+addopts = [
+    "--cov=fates",
+    "--cov-report=html",
+    "--cov-report=term",
+    "--xdoc",
+    "--xdoc-global-exec=from fates import Ok, Err, Result",
+]
+
+[tool.coverage.report]
+exclude_also = ["\\A(?s:.*# pragma: exclude file.*)\\Z"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.flake8]
+select = ["WPS"]
+ignore = ["WPS214"]
+allowed-domain-names = ["result"]
+
+[tool.pyrefly]
+project-includes = ["src/fates"]
+
+[tool.taskipy.tasks]
+check = "mypy && ty check && flake8 src && pytest"
+cov = "pytest && python -c 'import webbrowser; webbrowser.open(\"htmlcov/index.html\")'"
+
+[dependency-groups]
+dev = [
+    "flake8-pyproject>=1.2.4",
+    "mypy>=2.1.0",
+    "pyrefly>=0.14.0",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.15",
+    "taskipy>=1.14.1",
+    "ty>=0.0.40",
+    "wemake-python-styleguide>=1.6.2",
+    "xdoctest>=1.1.6",
+]
+docs = [
+    "furo>=2025.12.19",
+    "myst-parser>=5.1.0",
+    "sphinx>=9.1.0",
+    "sphinx-autobuild>=2025.8.25",
+    "sphinx-autodoc-typehints>=3.10.5",
+    "sphinx-autodoc2>=0.5.0",
+]
+
+[tool.uv.dependency-groups]
+docs = { requires-python = ">=3.12" }
+dev = { requires-python = ">=3.12" }

fates-0.1.0/src/fates/__init__.py

@@ -0,0 +1,6 @@
+"""fates — A generic Result[T, E] type for explicit error propagation."""
+
+from fates._err import Err as Err
+from fates._ok import Ok as Ok
+from fates._result import Result as Result
+from fates.exceptions import UnwrapError as UnwrapError

fates-0.1.0/src/fates/_async.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from asyncio import ensure_future
+from typing import TYPE_CHECKING, Generic, cast
+
+from fates._typevars import DefaultT, E_co, NewE, NewT, T_co
+
+if TYPE_CHECKING:
+    from asyncio import Task
+    from collections.abc import Awaitable, Generator
+
+    from fates._result import Result
+    from fates._types import AsyncBinder, AsyncMapper, Binder, Mapper
+
+
+class AsyncResult(Generic[T_co, E_co]):
+    def __init__(self, awaitable: Awaitable[Result[T_co, E_co]]) -> None:
+        self._awaitable = awaitable
+        self._cached_task: Task[Result[T_co, E_co]] | None = None
+
+    def __await__(self) -> Generator[object, None, Result[T_co, E_co]]:
+        if self._cached_task is None:
+            self._cached_task = ensure_future(self._awaitable)
+        return self._cached_task.__await__()
+
+    async def unwrap(self) -> T_co:
+        res = await self
+        return res.unwrap()
+
+    async def unwrap_or(self, default: DefaultT) -> T_co | DefaultT:
+        res = await self
+        return res.unwrap_or(default)
+
+    async def unwrap_err(self) -> E_co:
+        res = await self
+        return res.unwrap_err()
+
+    async def expect(self, note: str) -> T_co:
+        res = await self
+        return res.expect(note)
+
+    def map(self, mapper: Mapper[T_co, NewT]) -> AsyncResult[NewT, E_co]:
+        return AsyncResult(self._map(mapper))
+
+    def map_err(self, mapper: Mapper[E_co, NewE]) -> AsyncResult[T_co, NewE]:
+        return AsyncResult(self._map_err(mapper))
+
+    def bind(
+        self,
+        binder: Binder[T_co, NewT, NewE],
+    ) -> AsyncResult[NewT, E_co | NewE]:
+        return AsyncResult(self._bind(binder))
+
+    def catch(
+        self, binder: Binder[E_co, NewT, NewE]
+    ) -> AsyncResult[NewT, NewE] | AsyncResult[T_co, E_co]:
+        return cast(
+            "AsyncResult[T_co, E_co] | AsyncResult[NewT, NewE]",
+            AsyncResult(self._catch(binder)),
+        )
+
+    async def resolve(self, mapper: Mapper[E_co, NewT]) -> T_co | NewT:
+        res = await self
+        return res.resolve(mapper)
+
+    def amap(self, mapper: AsyncMapper[T_co, NewT]) -> AsyncResult[NewT, E_co]:
+        return AsyncResult(self._amap(mapper))
+
+    def amap_err(self, mapper: AsyncMapper[E_co, NewE]) -> AsyncResult[T_co, NewE]:
+        return AsyncResult(self._amap_err(mapper))
+
+    def abind(
+        self, binder: AsyncBinder[T_co, NewT, NewE]
+    ) -> AsyncResult[NewT, E_co | NewE]:
+        return AsyncResult(self._abind(binder))
+
+    def acatch(
+        self, binder: AsyncBinder[E_co, NewT, NewE]
+    ) -> AsyncResult[T_co, E_co] | AsyncResult[NewT, NewE]:
+        return cast(
+            "AsyncResult[T_co, E_co] | AsyncResult[NewT, NewE]",
+            AsyncResult(self._acatch(binder)),
+        )
+
+    async def aresolve(self, mapper: AsyncMapper[E_co, NewT]) -> T_co | NewT:
+        res = await self
+        return await res.aresolve(mapper)
+
+    async def _catch(
+        self, binder: Binder[E_co, NewT, NewE]
+    ) -> Result[T_co, E_co] | Result[NewT, NewE]:
+        res = await self
+        return res.catch(binder)
+
+    async def _acatch(
+        self, binder: AsyncBinder[E_co, NewT, NewE]
+    ) -> Result[T_co, E_co] | Result[NewT, NewE]:
+        res = await self
+        return await res.acatch(binder)  # ty: ignore[invalid-return-type]
+
+    async def _map(self, mapper: Mapper[T_co, NewT]) -> Result[NewT, E_co]:
+        res = await self
+        return res.map(mapper)
+
+    async def _map_err(self, mapper: Mapper[E_co, NewE]) -> Result[T_co, NewE]:
+        res = await self
+        return res.map_err(mapper)
+
+    async def _bind(
+        self, binder: Binder[T_co, NewT, NewE]
+    ) -> Result[NewT, E_co | NewE]:
+        res = await self
+        return res.bind(binder)
+
+    async def _amap(self, mapper: AsyncMapper[T_co, NewT]) -> Result[NewT, E_co]:
+        res = await self
+        return await res.amap(mapper)
+
+    async def _amap_err(self, mapper: AsyncMapper[E_co, NewE]) -> Result[T_co, NewE]:
+        res = await self
+        return await res.amap_err(mapper)
+
+    async def _abind(
+        self, binder: AsyncBinder[T_co, NewT, NewE]
+    ) -> Result[NewT, E_co | NewE]:
+        res = await self
+        return await res.abind(binder)

fates-0.1.0/src/fates/_err.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Awaitable, cast, final
+
+if sys.version_info >= (3, 12):
+    from typing import Never, Self, override  # pragma: no cover
+else:
+    from typing_extensions import Never, Self, override  # pragma: no cover
+
+
+from fates._async import AsyncResult
+from fates._result import Result
+from fates._typevars import DefaultT, E_co, NewE, NewT
+from fates.exceptions import UnwrapError
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from fates._types import AsyncBinder, AsyncMapper, Binder, Mapper
+
+
+@final
+class Err(Result[Never, E_co]):
+    __slots__ = ("_boxed_err",)
+    __match_args__ = ("_boxed_err",)
+
+    def __init__(self, boxed_err: E_co) -> None:
+        self._boxed_err = boxed_err
+
+    def __repr__(self) -> str:
+        return f"Err({self._boxed_err!r})"
+
+    def __hash__(self) -> int:
+        return self._boxed_err.__hash__()  # pragma: no cover
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Err):
+            other = cast("Err[object]", other)  # ty: ignore[redundant-cast]
+            return self._boxed_err == other._boxed_err
+        return False
+
+    @override
+    def unwrap(self) -> Never:
+        err = UnwrapError(repr(self._boxed_err))
+        if isinstance(self._boxed_err, BaseException):
+            raise err from self._boxed_err
+        raise err
+
+    @override
+    def unwrap_or(self, default: DefaultT) -> DefaultT:
+        return default
+
+    @override
+    def unwrap_err(self) -> E_co:
+        return self._boxed_err
+
+    @override
+    def expect(self, note: str) -> Never:
+        err_msg = f"{note}\nError details: {self._boxed_err!r}"
+        err = UnwrapError(err_msg)
+        if isinstance(self._boxed_err, BaseException):
+            raise err from self._boxed_err
+        raise err
+
+    @override
+    def map(self, mapper: Mapper[Never, object]) -> Self:
+        return self
+
+    @override
+    def map_err(self, mapper: Mapper[E_co, NewE]) -> Err[NewE]:
+        return Err(mapper(self._boxed_err))
+
+    @override
+    def bind(
+        self,
+        binder: Binder[Never, object, object],
+    ) -> Self:
+        return self
+
+    @override
+    def catch(self, binder: Binder[E_co, NewT, NewE]) -> Result[NewT, NewE]:
+        return binder(self._boxed_err)
+
+    @override
+    def resolve(self, mapper: Mapper[E_co, NewT]) -> NewT:
+        return mapper(self._boxed_err)
+
+    @override
+    def amap(self, mapper: AsyncMapper[Never, object]) -> AsyncErr[E_co]:
+        return AsyncErr(self._return_self())
+
+    @override
+    def amap_err(self, mapper: AsyncMapper[E_co, NewE]) -> AsyncErr[NewE]:
+        return AsyncErr(self._async_map_err(mapper))
+
+    @override
+    def abind(self, binder: AsyncBinder[Never, object, object]) -> AsyncErr[E_co]:
+        return AsyncErr(self._return_self())
+
+    @override
+    def acatch(self, binder: AsyncBinder[E_co, NewT, NewE]) -> AsyncResult[NewT, NewE]:
+        return AsyncResult(self._acatch(binder))
+
+    @override
+    async def aresolve(self, mapper: AsyncMapper[E_co, NewT]) -> NewT:
+        return await mapper(self._boxed_err)
+
+    async def _return_self(self) -> Self:
+        return self
+
+    async def _acatch(
+        self, binder: AsyncBinder[E_co, NewT, NewE]
+    ) -> Result[NewT, NewE]:
+        return await binder(self._boxed_err)
+
+    async def _async_map_err(self, mapper: AsyncMapper[E_co, NewE]) -> Err[NewE]:
+        return Err(await mapper(self._boxed_err))
+
+
+@final
+class AsyncErr(AsyncResult[Never, E_co]):
+    @override
+    def __init__(self, awaitable: Awaitable[Err[E_co]]) -> None:
+        super().__init__(awaitable)
+
+    @override
+    def __await__(self) -> Generator[object, None, Err[E_co]]:
+        return cast("Generator[object, None, Err[E_co]]", super().__await__())
+
+    @override
+    def map(self, mapper: Mapper[Never, object]) -> Self:
+        return self
+
+    @override
+    def amap(self, mapper: AsyncMapper[Never, object]) -> Self:
+        return self
+
+    @override
+    def bind(self, binder: Binder[Never, object, object]) -> Self:
+        return self
+
+    @override
+    def abind(self, binder: AsyncBinder[Never, object, object]) -> Self:
+        return self
+
+    @override
+    def map_err(self, mapper: Mapper[E_co, NewE]) -> AsyncErr[NewE]:
+        return AsyncErr(self._map_err(mapper))
+
+    @override
+    def amap_err(self, mapper: AsyncMapper[E_co, NewE]) -> AsyncErr[NewE]:
+        return AsyncErr(self._amap_err(mapper))
+
+    @override
+    def catch(self, binder: Binder[E_co, NewT, NewE]) -> AsyncResult[NewT, NewE]:
+        return AsyncResult(self._catch(binder))
+
+    @override
+    def acatch(self, binder: AsyncBinder[E_co, NewT, NewE]) -> AsyncResult[NewT, NewE]:
+        return AsyncResult(self._acatch(binder))
+
+    @override
+    async def _map_err(self, mapper: Mapper[E_co, NewE]) -> Err[NewE]:
+        res = await self
+        return res.map_err(mapper)
+
+    @override
+    async def _amap_err(self, mapper: AsyncMapper[E_co, NewE]) -> Err[NewE]:
+        res = await self
+        return await res.amap_err(mapper)
+
+    @override
+    async def _catch(self, binder: Binder[E_co, NewT, NewE]) -> Result[NewT, NewE]:
+        res = await self
+        return res.catch(binder)
+
+    @override
+    async def _acatch(
+        self, binder: AsyncBinder[E_co, NewT, NewE]
+    ) -> Result[NewT, NewE]:
+        res = await self
+        return await res.acatch(binder)

fates-0.1.0/src/fates/_ok.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Awaitable, Generator, cast, final
+
+if sys.version_info >= (3, 12):
+    from typing import Never, Self, override  # pragma: no cover
+else:
+    from typing_extensions import Never, Self, override  # pragma: no cover
+
+
+from fates._async import AsyncResult
+from fates._result import Result
+from fates._typevars import NewE, NewT, T_co
+from fates.exceptions import UnwrapError
+
+if TYPE_CHECKING:
+    from fates._types import AsyncBinder, AsyncMapper, Binder, Mapper
+
+
+@final
+class Ok(Result[T_co, Never]):
+    __slots__ = ("_boxed_val",)
+    __match_args__ = ("_boxed_val",)
+
+    def __init__(self, boxed_val: T_co) -> None:
+        self._boxed_val = boxed_val
+
+    def __repr__(self) -> str:
+        return f"Ok({self._boxed_val!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Ok):
+            other = cast("Ok[object]", other)  # ty: ignore[redundant-cast]
+            return self._boxed_val == other._boxed_val
+        return False
+
+    def __hash__(self) -> int:
+        return self._boxed_val.__hash__()  # pragma: no cover
+
+    @override
+    def unwrap(self) -> T_co:
+        return self._boxed_val
+
+    @override
+    def unwrap_or(self, default: object) -> T_co:
+        return self._boxed_val
+
+    @override
+    def unwrap_err(self) -> Never:
+        msg = f"unwrap_err() called on {self}"
+        raise UnwrapError(msg)
+
+    @override
+    def expect(self, note: str) -> T_co:
+        return self._boxed_val
+
+    @override
+    def map(self, mapper: Mapper[T_co, NewT]) -> Ok[NewT]:
+        return Ok(mapper(self._boxed_val))
+
+    @override
+    def map_err(self, mapper: Mapper[Never, object]) -> Self:
+        return self
+
+    @override
+    def bind(self, binder: Binder[T_co, NewT, NewE]) -> Result[NewT, NewE]:
+        return binder(self._boxed_val)
+
+    @override
+    def catch(self, binder: Binder[Never, object, object]) -> Self:
+        return self
+
+    @override
+    def resolve(self, mapper: Mapper[Never, object]) -> T_co:
+        return self._boxed_val
+
+    @override
+    def amap(self, mapper: AsyncMapper[T_co, NewT]) -> AsyncOk[NewT]:
+        return AsyncOk(self._async_map(mapper))
+
+    @override
+    def amap_err(self, mapper: AsyncMapper[Never, object]) -> AsyncOk[T_co]:
+        return AsyncOk(self._return_self())
+
+    @override
+    def abind(self, binder: AsyncBinder[T_co, NewT, NewE]) -> AsyncResult[NewT, NewE]:
+        return AsyncResult(self._async_bind(binder))
+
+    @override
+    def acatch(self, binder: AsyncBinder[Never, object, object]) -> AsyncOk[T_co]:
+        return AsyncOk(self._return_self())
+
+    @override
+    async def aresolve(self, mapper: AsyncMapper[Never, object]) -> T_co:
+        return self._boxed_val
+
+    async def _async_map(self, mapper: AsyncMapper[T_co, NewT]) -> Ok[NewT]:
+        return Ok(await mapper(self._boxed_val))
+
+    async def _async_bind(
+        self, binder: AsyncBinder[T_co, NewT, NewE]
+    ) -> Result[NewT, NewE]:
+        return await binder(self._boxed_val)
+
+    async def _return_self(self) -> Self:
+        return self
+
+
+@final
+class AsyncOk(AsyncResult[T_co, Never]):
+    @override
+    def __init__(self, awaitable: Awaitable[Ok[T_co]]) -> None:
+        super().__init__(awaitable)
+
+    @override
+    def __await__(self) -> Generator[object, None, Ok[T_co]]:
+        return cast("Generator[object, None, Ok[T_co]]", super().__await__())
+
+    @override
+    async def unwrap_or(self, default: object) -> T_co:
+        res = await self
+        return res.unwrap()
+
+    @override
+    async def expect(self, note: str) -> T_co:
+        res = await self
+        return res.unwrap()
+
+    @override
+    async def resolve(self, mapper: Mapper[Never, object]) -> T_co:
+        res = await self
+        return res.unwrap()
+
+    @override
+    async def aresolve(self, mapper: AsyncMapper[Never, object]) -> T_co:
+        res = await self
+        return res.unwrap()
+
+    @override
+    def map(self, mapper: Mapper[T_co, NewT]) -> AsyncOk[NewT]:
+        return AsyncOk(self._map(mapper))
+
+    @override
+    def amap(self, mapper: AsyncMapper[T_co, NewT]) -> AsyncOk[NewT]:
+        return AsyncOk(self._amap(mapper))
+
+    @override
+    def map_err(self, mapper: Mapper[Never, object]) -> Self:
+        return self
+
+    @override
+    def catch(self, binder: Binder[Never, object, object]) -> Self:
+        return self
+
+    @override
+    def acatch(self, binder: AsyncBinder[Never, object, object]) -> Self:
+        return self
+
+    @override
+    def amap_err(self, mapper: AsyncMapper[Never, object]) -> Self:
+        return self
+
+    @override
+    async def _map(self, mapper: Mapper[T_co, NewT]) -> Ok[NewT]:
+        res = await self
+        return res.map(mapper)
+
+    @override
+    async def _amap(self, mapper: AsyncMapper[T_co, NewT]) -> Ok[NewT]:
+        res = await self
+        return await res.amap(mapper)

fates-0.1.0/src/fates/_result.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Generic, Protocol
+
+from fates._typevars import DefaultT, E_co, NewE, NewT, T_co
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+if TYPE_CHECKING:
+    from fates._async import AsyncResult
+    from fates._types import AsyncBinder, AsyncMapper, Binder, Mapper
+
+
+class Result(Protocol, Generic[T_co, E_co]):
+    def unwrap(self) -> T_co:
+        """Extracts the success value or raises an exception if it is a failure.
+
+        Returns:
+            T_co: The contained success value.
+
+        Raises:
+            UnwrapError: If the result is an Err.
+
+        Examples:
+            >>> Ok(42).unwrap()
+            42
+            >>> Err("error").unwrap()
+            Traceback (most recent call last):
+            fates.exceptions.UnwrapError: 'error'
+        """
+        ...
+
+    def unwrap_or(self, default: DefaultT) -> T_co | DefaultT:
+        """Returns the success value or a default value if it is a failure.
+
+        Args:
+            default (DefaultT): The fallback value to return.
+
+        Returns:
+            T_co | DefaultT: The contained value or the default value.
+
+        Examples:
+            >>> Ok(42).unwrap_or(0)
+            42
+            >>> Err("error").unwrap_or(0)
+            0
+        """
+        ...
+
+    def unwrap_err(self) -> E_co:
+        """Extracts the error value or raises an exception if it is a success.
+
+        Returns:
+            E_co: The contained error value.
+
+        Raises:
+            UnwrapError: If the result is an Ok.
+
+        Examples:
+            >>> Err("danger").unwrap_err()
+            'danger'
+            >>> Ok(42).unwrap_err()
+            Traceback (most recent call last):
+            fates.exceptions.UnwrapError: unwrap_err() called on Ok(42)
+        """
+        ...
+
+    def expect(self, note: str) -> T_co:
+        """Extracts the value or raises an exception with a custom message.
+
+        Args:
+            note (str): The custom error message to include in the exception.
+
+        Returns:
+            T_co: The contained success value.
+
+        Raises:
+            UnwrapError: If the result is an Err, containing the note.
+
+        Examples:
+            >>> Ok(42).expect("Should be a number")
+            42
+            >>> Err("db_error").expect("Database connection failed")
+            Traceback (most recent call last):
+            fates.exceptions.UnwrapError: Database connection failed
+            Error details: 'db_error'
+        """
+        ...
+
+    def map(
+        self,
+        mapper: Mapper[T_co, NewT],
+    ) -> Result[NewT, E_co]:
+        """Applies a function to the success value, leaving an error untouched.
+
+        Args:
+            mapper (Mapper[T_co, NewT]): A function to transform the success value.
+
+        Returns:
+            Result[NewT, E_co]: A new Result with
+                the transformed value or original error.
+
+        Examples:
+            >>> Ok(2).map(lambda x: x * 2)
+            Ok(4)
+            >>> Err("error").map(lambda x: x * 2)
+            Err('error')
+        """
+        ...
+
+    def map_err(
+        self,
+        mapper: Mapper[E_co, NewE],
+    ) -> Result[T_co, NewE]:
+        """Applies a function to the error value, leaving a success untouched.
+
+        Args:
+            mapper (Mapper[E_co, NewE]): A function to transform the error value.
+
+        Returns:
+            Result[T_co, NewE]: A new Result with the
+                transformed error or original value.
+
+        Examples:
+            >>> Err("failed").map_err(lambda e: f"Log: {e}")
+            Err('Log: failed')
+            >>> Ok(42).map_err(lambda e: f"Log: {e}")
+            Ok(42)
+        """
+        ...
+
+    def bind(
+        self,
+        binder: Binder[T_co, NewT, NewE],
+    ) -> Result[NewT, E_co | NewE]:
+        """Monadic bind. Transforms the success value into a new Result.
+
+        Args:
+            binder (Binder[T_co, NewT, NewE]): A function that takes the success
+                value and returns a new Result.
+
+        Returns:
+            Result[NewT, E_co | NewE]: The new Result, or the original Err.
+
+        Examples:
+            >>> def check_positive(x: int) -> Result[int, str]:
+            ...     return Ok(x) if x > 0 else Err("negative")
+            >>> Ok(5).bind(check_positive)
+            Ok(5)
+            >>> Ok(-1).bind(check_positive)
+            Err('negative')
+            >>> Err("not_a_number").bind(check_positive)
+            Err('not_a_number')
+        """
+        ...
+
+    def catch(
+        self,
+        binder: Binder[E_co, NewT, NewE],
+    ) -> Self | Result[NewT, NewE]:
+        """Handles an error by transforming it into a new Result.
+
+        Args:
+            binder (Binder[E_co, NewT, NewE]): A function that takes the error
+                value and returns a alternative Result.
+
+        Returns:
+            Self | Result[NewT, NewE]: The original Ok,
+                or the new Result from the binder.
+
+        Examples:
+            >>> def recover(e: str) -> Result[int, str]:
+            ...     return Ok(0) if e == "recoverable" else Err("fatal")
+            >>> Ok(42).catch(recover)
+            Ok(42)
+            >>> Err("recoverable").catch(recover)
+            Ok(0)
+            >>> Err("boom").catch(recover)
+            Err('fatal')
+        """
+        ...
+
+    def resolve(self, mapper: Mapper[E_co, NewT]) -> T_co | NewT:
+        """Returns the success value or transforms the error into a success type.
+
+        Args:
+            mapper (Mapper[E_co, NewT]): A function to transform the error value.
+
+        Returns:
+            T_co | NewT: The original success value or the transformed error value.
+
+        Examples:
+            >>> Ok(100).resolve(lambda e: 0)
+            100
+            >>> Err("missing").resolve(lambda e: 0)
+            0
+        """
+        ...
+
+    def amap(
+        self,
+        mapper: AsyncMapper[T_co, NewT],
+    ) -> AsyncResult[NewT, E_co]:
+        """Asynchronously maps the success value using an async function.
+
+        Args:
+            mapper (AsyncMapper[T_co, NewT]): An async function to transform the value.
+
+        Returns:
+            AsyncResult[NewT, E_co]: An async result wrapper.
+
+        Examples:
+            >>> async def async_double(x: int) -> int:
+            ...     return x * 2
+            >>> await Ok(2).amap(async_double)
+            Ok(4)
+            >>> await Err("error").amap(async_double)
+            Err('error')
+        """
+        ...
+
+    def amap_err(
+        self,
+        mapper: AsyncMapper[E_co, NewE],
+    ) -> AsyncResult[T_co, NewE]:
+        """Asynchronously maps the error value using an async function.
+
+        Args:
+            mapper (AsyncMapper[E_co, NewE]): An async function to transform the error.
+
+        Returns:
+            AsyncResult[T_co, NewE]: An async result wrapper.
+
+        Examples:
+            >>> async def async_log(e: str) -> str:
+            ...     return f"logged_{e}"
+            >>> await Err("fail").amap_err(async_log)
+            Err('logged_fail')
+            >>> await Ok(42).amap_err(async_log)
+            Ok(42)
+        """
+        ...
+
+    def abind(
+        self, binder: AsyncBinder[T_co, NewT, NewE]
+    ) -> AsyncResult[NewT, E_co | NewE]:
+        """
+        Asynchronously binds the success value to an async
+            function returning a Result.
+
+        Args:
+            binder (AsyncBinder[T_co, NewT, NewE]): An async
+                function returning a Result.
+
+        Returns:
+            AsyncResult[NewT, E_co | NewE]: An async result wrapper.
+
+        Examples:
+            >>> async def async_check(x: int) -> Result[int, str]:
+            ...     return Ok(x) if x > 0 else Err("negative")
+            >>> await Ok(5).abind(async_check)
+            Ok(5)
+            >>> await Err("error").abind(async_check)
+            Err('error')
+        """
+        ...
+
+    def acatch(
+        self,
+        binder: AsyncBinder[E_co, NewT, NewE],
+    ) -> AsyncResult[T_co, E_co] | AsyncResult[NewT, NewE]: ...
+
+    async def aresolve(self, mapper: AsyncMapper[E_co, NewT]) -> T_co | NewT: ...

fates-0.1.0/src/fates/_types.py

@@ -0,0 +1,20 @@
+# pragma: exclude file
+
+import sys
+from collections.abc import Awaitable, Callable
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+from fates._result import Result
+from fates._typevars import New, NewE, NewT, Old, T_co
+
+Mapper: TypeAlias = Callable[[Old], New]
+
+AsyncMapper: TypeAlias = Callable[[Old], Awaitable[New]]
+
+Binder: TypeAlias = Callable[[T_co], Result[NewT, NewE]]
+
+AsyncBinder: TypeAlias = Callable[[T_co], Awaitable[Result[NewT, NewE]]]

fates-0.1.0/src/fates/_typevars.py

@@ -0,0 +1,9 @@
+from typing import TypeVar
+
+T_co = TypeVar("T_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+NewT = TypeVar("NewT")
+NewE = TypeVar("NewE")
+DefaultT = TypeVar("DefaultT")
+Old = TypeVar("Old")
+New = TypeVar("New")

fates-0.1.0/src/fates/exceptions.py

@@ -0,0 +1,2 @@
+class UnwrapError(Exception):
+    """Raises when unwrap() called on Err or unwrap_err() called on Ok."""