flow-res 0.1.0__tar.gz

flow_res-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shimae
+
+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.

flow_res-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: flow-res
+Version: 0.1.0
+Summary: 
+Author: Shimae
+Author-email: Shimae <50893541+aiagate@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/aiagate/flow-res
+Project-URL: Issues, https://github.com/aiagate/flow-res/issues
+Description-Content-Type: text/markdown
+
+# flow-res
+
+Rust 言語の `Result` 型に範を仰いだ、Python 向けの高機能かつ型安全なエラーハンドリングライブラリです。
+
+従来の例外駆動型（Exception-driven）から、Result 駆動型（Result-driven）へのパラダイムシフトを強力に支援します。明示的なエラーハンドリングを導入することで、コードの堅牢性と可読性を飛躍的に向上させることが可能です。
+
+## 主要な特徴
+
+* **厳密な型安全性**: ジェネリクスを活用し、成功値とエラー値の双方に対して静的解析（mypy, pyright 等）を適用可能です。
+* **鉄道指向プログラミング（ROP）**: `map` や `and_then` によるメソッドチェーンにより、宣言的なエラーハンドリングを実現します。
+* **非同期処理のネイティブサポート**: `@async_result` デコレータを通じて、非同期処理を `AwaitableResult` として透過的にチェーン可能です。
+* **メタプログラミングによる統合**: `@safe` デコレータを用いることで、既存の例外送出型関数を容易に Result 型へ変換できます。
+* **高度な結果集約**: `combine`（早期失敗）および `combine_all`（全エラー集約）により、複数の処理結果を合理的に統合します。
+* **軽量設計（ゼロ依存）**: 外部ライブラリへの依存はなく、プロジェクトへの導入障壁が極めて低く抑えられています。
+
+## インストール
+
+```bash
+pip install flow_res
+```
+
+※ Python 3.13 以上が必要です。
+
+## 実装ガイド
+
+### 1. 基本的な定義とハンドリング
+
+関数の戻り値に `Result` を指定することで、呼び出し側に対してエラー処理の検討を強制（明示）させます。Python 3.10 以降の構造的パターンマッチングを利用することで、エレガントに結果を処理できます。
+
+```python
+from flow_res import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[float, ValueError]:
+    """2つの数値の除算を行い、結果を Result 型で返却する"""
+    if b == 0:
+        return Err(ValueError("Division by zero"))
+    return Ok(a / b)
+
+result = divide(10, 2)
+match result:
+    case Ok(value):
+        print(f"Success: {value}")
+    case Err(error):
+        print(f"Failure: {error}")
+```
+
+### 2. 関数型インターフェースによる連鎖処理 (Railroad-Oriented Programming)
+
+`map` や `and_then` を用いることで、命令的な条件分岐を排除し、処理のパイプラインを構築できます。
+
+```python
+from flow_res import Result
+
+def validate_positive(x: int) -> Result[int, ValueError]:
+    if x < 0:
+        return Err(ValueError("Must be positive"))
+    return Ok(x)
+
+# 依存関係のある処理の連結
+result = (
+    Ok(5)
+    .and_then(validate_positive)
+    .map(lambda x: x * 2)
+    .map(lambda x: x + 3)
+)
+print(result.unwrap())  # 13
+```
+
+### 3. @safe デコレータによる例外のラップ
+
+既存の例外を発生させる可能性のある関数を、低コストで Result 駆動型へ移行させます。
+
+```python
+from flow_res import safe
+
+@safe
+def parse_int(s: str) -> int:
+    return int(s)
+
+# 例外は送出されず、Err として返却される
+result = parse_int("not_a_number")
+print(result)  # Err(error=ValueError("invalid literal for int() with base 10: 'not_a_number'"))
+```
+
+### 4. 非同期処理の統合 (@async_result)
+
+`@async_result` デコレータを使用することで、非同期関数の実行結果に対しても await 前にメソッドチェーンを適用できます。
+
+```python
+import asyncio
+from flow_res import Result, async_result
+
+@async_result
+async def fetch_user(user_id: int) -> Result[dict, ValueError]:
+    await asyncio.sleep(0.1)
+    if user_id < 0:
+        return Err(ValueError("Invalid user ID"))
+    return Ok({"id": user_id, "name": f"User{user_id}"})
+
+async def main():
+    # 処理を連結した後に一括で await
+    result = await (
+        fetch_user(1)
+        .map(lambda u: u["name"])
+        .map(str.upper)
+    )
+    print(result.unwrap())  # USER1
+
+asyncio.run(main())
+```
+
+### 5. 複数結果の集約ロジック (combine / combine_all)
+
+バリデーションなど、複数の検証結果を一括で扱うためのインターフェースを提供します。
+
+* `combine`: 最初に遭遇した `Err` を返却する（短絡評価・早期失敗）
+* `combine_all`: すべての `Err` を集約して複数の例外を保持する `Err` を返却する（全件チェック）
+
+```python
+from flow_res import Result, combine, combine_all, Ok, Err
+
+results = (
+    Ok(1),
+    Err(ValueError("error1")),
+    Err(RuntimeError("error2")),
+)
+
+# 最初のエラー (error1) のみを返す
+print(combine(results)) 
+
+# すべてのエラーを集約して返す
+match combine_all(results):
+    case Err(error):
+        for e in error.exceptions:
+            print(f"Error: {e}")
+```
+
+## 動作環境
+
+* **Python バージョン**: 3.13 以上
+* **型ヒント**: 完全対応（Static Type Checking を推奨）
+
+## ライセンス
+
+本プロジェクトは MIT License の下に公開されています。
+
+## 協力・貢献
+
+不具合報告や機能拡張の提案は、[GitHub Issues](https://github.com/aiagate/flow-res/issues) にて承っております。

flow_res-0.1.0/README.md

@@ -0,0 +1,149 @@
+# flow-res
+
+Rust 言語の `Result` 型に範を仰いだ、Python 向けの高機能かつ型安全なエラーハンドリングライブラリです。
+
+従来の例外駆動型（Exception-driven）から、Result 駆動型（Result-driven）へのパラダイムシフトを強力に支援します。明示的なエラーハンドリングを導入することで、コードの堅牢性と可読性を飛躍的に向上させることが可能です。
+
+## 主要な特徴
+
+* **厳密な型安全性**: ジェネリクスを活用し、成功値とエラー値の双方に対して静的解析（mypy, pyright 等）を適用可能です。
+* **鉄道指向プログラミング（ROP）**: `map` や `and_then` によるメソッドチェーンにより、宣言的なエラーハンドリングを実現します。
+* **非同期処理のネイティブサポート**: `@async_result` デコレータを通じて、非同期処理を `AwaitableResult` として透過的にチェーン可能です。
+* **メタプログラミングによる統合**: `@safe` デコレータを用いることで、既存の例外送出型関数を容易に Result 型へ変換できます。
+* **高度な結果集約**: `combine`（早期失敗）および `combine_all`（全エラー集約）により、複数の処理結果を合理的に統合します。
+* **軽量設計（ゼロ依存）**: 外部ライブラリへの依存はなく、プロジェクトへの導入障壁が極めて低く抑えられています。
+
+## インストール
+
+```bash
+pip install flow_res
+```
+
+※ Python 3.13 以上が必要です。
+
+## 実装ガイド
+
+### 1. 基本的な定義とハンドリング
+
+関数の戻り値に `Result` を指定することで、呼び出し側に対してエラー処理の検討を強制（明示）させます。Python 3.10 以降の構造的パターンマッチングを利用することで、エレガントに結果を処理できます。
+
+```python
+from flow_res import Result, Ok, Err
+
+def divide(a: int, b: int) -> Result[float, ValueError]:
+    """2つの数値の除算を行い、結果を Result 型で返却する"""
+    if b == 0:
+        return Err(ValueError("Division by zero"))
+    return Ok(a / b)
+
+result = divide(10, 2)
+match result:
+    case Ok(value):
+        print(f"Success: {value}")
+    case Err(error):
+        print(f"Failure: {error}")
+```
+
+### 2. 関数型インターフェースによる連鎖処理 (Railroad-Oriented Programming)
+
+`map` や `and_then` を用いることで、命令的な条件分岐を排除し、処理のパイプラインを構築できます。
+
+```python
+from flow_res import Result
+
+def validate_positive(x: int) -> Result[int, ValueError]:
+    if x < 0:
+        return Err(ValueError("Must be positive"))
+    return Ok(x)
+
+# 依存関係のある処理の連結
+result = (
+    Ok(5)
+    .and_then(validate_positive)
+    .map(lambda x: x * 2)
+    .map(lambda x: x + 3)
+)
+print(result.unwrap())  # 13
+```
+
+### 3. @safe デコレータによる例外のラップ
+
+既存の例外を発生させる可能性のある関数を、低コストで Result 駆動型へ移行させます。
+
+```python
+from flow_res import safe
+
+@safe
+def parse_int(s: str) -> int:
+    return int(s)
+
+# 例外は送出されず、Err として返却される
+result = parse_int("not_a_number")
+print(result)  # Err(error=ValueError("invalid literal for int() with base 10: 'not_a_number'"))
+```
+
+### 4. 非同期処理の統合 (@async_result)
+
+`@async_result` デコレータを使用することで、非同期関数の実行結果に対しても await 前にメソッドチェーンを適用できます。
+
+```python
+import asyncio
+from flow_res import Result, async_result
+
+@async_result
+async def fetch_user(user_id: int) -> Result[dict, ValueError]:
+    await asyncio.sleep(0.1)
+    if user_id < 0:
+        return Err(ValueError("Invalid user ID"))
+    return Ok({"id": user_id, "name": f"User{user_id}"})
+
+async def main():
+    # 処理を連結した後に一括で await
+    result = await (
+        fetch_user(1)
+        .map(lambda u: u["name"])
+        .map(str.upper)
+    )
+    print(result.unwrap())  # USER1
+
+asyncio.run(main())
+```
+
+### 5. 複数結果の集約ロジック (combine / combine_all)
+
+バリデーションなど、複数の検証結果を一括で扱うためのインターフェースを提供します。
+
+* `combine`: 最初に遭遇した `Err` を返却する（短絡評価・早期失敗）
+* `combine_all`: すべての `Err` を集約して複数の例外を保持する `Err` を返却する（全件チェック）
+
+```python
+from flow_res import Result, combine, combine_all, Ok, Err
+
+results = (
+    Ok(1),
+    Err(ValueError("error1")),
+    Err(RuntimeError("error2")),
+)
+
+# 最初のエラー (error1) のみを返す
+print(combine(results)) 
+
+# すべてのエラーを集約して返す
+match combine_all(results):
+    case Err(error):
+        for e in error.exceptions:
+            print(f"Error: {e}")
+```
+
+## 動作環境
+
+* **Python バージョン**: 3.13 以上
+* **型ヒント**: 完全対応（Static Type Checking を推奨）
+
+## ライセンス
+
+本プロジェクトは MIT License の下に公開されています。
+
+## 協力・貢献
+
+不具合報告や機能拡張の提案は、[GitHub Issues](https://github.com/aiagate/flow-res/issues) にて承っております。

flow_res-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "flow-res"
+version = "0.1.0"
+authors = [
+  { name="Shimae", email="50893541+aiagate@users.noreply.github.com" },
+]
+description = ""
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICENSE*"]
+
+[build-system]
+requires = ["uv_build >= 0.10.10, <0.11.0"]
+build-backend = "uv_build"
+
+[project.urls]
+Homepage = "https://github.com/aiagate/flow-res"
+Issues = "https://github.com/aiagate/flow-res/issues"
+
+[dependency-groups]
+dev = [
+    "anyio>=4.11.0",
+    "pre-commit>=4.5.0",
+    "pyright>=1.1.407",
+    "pytest>=8.3.5",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.14.6",
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_empty = true
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--cov=src",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+asyncio_default_fixture_loop_scope = "function"

flow_res-0.1.0/src/flow_res/__init__.py

@@ -0,0 +1,18 @@
+from .async_result import AwaitableResult, async_result
+from .combinators import combine, combine_all
+from .guards import is_err, is_ok
+from .result import Err, Ok, Result
+from .safe import safe
+
+__all__ = [
+    "Result",
+    "AwaitableResult",
+    "Ok",
+    "Err",
+    "is_err",
+    "is_ok",
+    "safe",
+    "combine",
+    "combine_all",
+    "async_result",
+]

flow_res-0.1.0/src/flow_res/async_result.py

@@ -0,0 +1,184 @@
+import inspect
+from collections.abc import Awaitable, Callable, Coroutine, Generator
+from functools import wraps
+from typing import Any
+
+from .result import Err, Ok, Result
+
+
+class AwaitableResult[T, E: Exception]:
+    """
+    Awaitable wrapper for Result that enables method chaining before await.
+
+    This allows elegant syntax like:
+        message = await Mediator.send_async(query).map(...).unwrap()
+    """
+
+    def __init__(self, coro: Coroutine[Any, Any, Result[T, E]]) -> None:
+        """
+        Initialize with a coroutine that returns a Result.
+
+        Args:
+            coro: Coroutine that will return Result[T, E]
+        """
+        self._coro = coro
+
+    def __repr__(self) -> str:
+        """Return a helpful representation for debugging.
+
+        Shows the wrapped coroutine's repr to aid debugging without awaiting.
+        """
+        try:
+            coro_repr = repr(self._coro)
+        except Exception:
+            coro_repr = "<unreprable coroutine>"
+        return f"ResultAwaitable(coro={coro_repr})"
+
+    def __await__(self) -> Generator[Any, None, Result[T, E]]:
+        """Make this object awaitable, returning the underlying Result."""
+        return self._coro.__await__()
+
+    def map[U](self, f: Callable[[T], U]) -> "AwaitableResult[U, E]":
+        """
+        Transform the Ok value using the provided function.
+
+        This method chains onto the coroutine, creating a new coroutine that:
+        1. Awaits the current Result
+        2. Applies .map() to transform the value
+        3. Returns the transformed Result
+
+        Args:
+            f: Function to apply to the Ok value (T -> U)
+
+        Returns:
+            ResultAwaitable[U, E] wrapping the transformed result
+
+        Example:
+            user_id = await Mediator.send_async(cmd).map(lambda v: v.user_id)
+        """
+
+        async def mapped() -> Result[U, E]:
+            _result: Result[T, E] = await self
+            return _result.map(f)
+
+        return AwaitableResult(mapped())
+
+    def and_then[U](
+        self, f: Callable[[T], Awaitable[Result[U, E]] | Result[U, E]]
+    ) -> "AwaitableResult[U, E]":
+        """
+        Apply a function (sync or async) that returns a Result, flattening the nested Result.
+
+        This enables chaining operations that may fail.
+
+        Args:
+            f: Function that takes the Ok value and returns a new Result
+               (T -> Awaitable[Result[U, E]] | Result[U, E])
+
+        Returns:
+            ResultAwaitable[U, E] wrapping the result of applying the function
+
+        Example:
+            await (
+                Mediator.send_async(create_cmd)
+                .and_then(lambda result: Mediator.send_async(GetQuery(result.id)))
+                .map(lambda value: format_message(value))
+                .unwrap()
+            )
+        """
+
+        async def chained() -> Result[U, E]:
+            _result: Result[T, E] = await self
+            match _result:
+                case Ok(value):
+                    res = f(value)
+                    if inspect.isawaitable(res):
+                        return await res
+                    return res
+                case Err():
+                    return _result
+
+        return AwaitableResult(chained())
+
+    def unwrap(self) -> Awaitable[T]:
+        """
+        Return the Ok value or raise the Err as an exception.
+
+        This is a terminal operation that unwraps the Result.
+
+        Returns:
+            Awaitable[T] that will return the value or raise the error
+
+        Example:
+            message = await Mediator.send_async(query).map(...).unwrap()
+        """
+
+        async def unwrapped() -> T:
+            _result: Result[T, E] = await self
+            return _result.unwrap()
+
+        return unwrapped()
+
+    def map_err[F: Exception](self, f: Callable[[E], F]) -> "AwaitableResult[T, F]":
+        """
+        Transform the error value using the provided function asynchronously.
+
+        Args:
+            f: Function to apply to the error value (E -> F)
+
+        Returns:
+            ResultAwaitable[T, F] wrapping the result with transformed error type
+
+        Example:
+            await (
+                Mediator.send_async(cmd)
+                .map_err(lambda e: DatabaseError(f"DB error: {e}"))
+                .unwrap()
+            )
+        """
+
+        async def mapped() -> Result[T, F]:
+            _result = await self
+            return _result.map_err(f)
+
+        return AwaitableResult(mapped())
+
+
+def async_result[T, E: Exception](
+    func: Callable[..., Coroutine[Any, Any, Result[T, E]]],
+) -> Callable[..., AwaitableResult[T, E]]:
+    """
+    Decorator that wraps an async function returning Result in AwaitableResult.
+
+    This allows async functions to return Result types while automatically
+    wrapping them in AwaitableResult for method chaining (.map, .and_then, etc.)
+
+    The decorated function must be async and return a Result. The decorator
+    will wrap the coroutine in AwaitableResult, allowing method chaining without
+    an explicit await.
+
+    Args:
+        func: An async function that returns Result[T, E]
+
+    Returns:
+        A wrapped function that returns AwaitableResult[T, E]
+
+    Example:
+        @async_result
+        async def fetch_user(user_id: int) -> Result[dict, Exception]:
+            if user_id < 0:
+                return Err(ValueError("Invalid user ID"))
+            return Ok({"id": user_id})
+
+        # Can now use method chaining without await:
+        result = fetch_user(1).map(lambda u: u["id"]).map(str.upper)
+        print(await result)  # Ok({"id": 1})
+    """
+
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> AwaitableResult[T, E]:
+        return AwaitableResult(
+            coro=func(*args, **kwargs),
+        )
+
+    return wrapper

flow_res-0.1.0/src/flow_res/combinators.py

@@ -0,0 +1,310 @@
+from collections.abc import Sequence
+from typing import Any, overload
+
+from .result import Result, Ok, Err
+
+
+@overload
+def combine[E: Exception](results: tuple[()]) -> Result[tuple[()], E]: ...
+
+
+@overload
+def combine[T1, E: Exception](
+    results: tuple[Result[T1, E]],
+) -> Result[tuple[T1], E]: ...
+
+
+@overload
+def combine[T1, T2, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E]],
+) -> Result[tuple[T1, T2], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E], Result[T3, E]],
+) -> Result[tuple[T1, T2, T3], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E], Result[T3, E], Result[T4, E]],
+) -> Result[tuple[T1, T2, T3, T4], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, T6, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, T6, T7, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, T6, T7, T8, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, T6, T7, T8, T9, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+        Result[T9, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9], E]: ...
+
+
+@overload
+def combine[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+        Result[T9, E],
+        Result[T10, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10], E]: ...
+
+
+def combine[E: Exception](
+    results: Sequence[Result[Any, E]],
+) -> Result[tuple[Any, ...], E]:
+    """
+    Aggregates a sequence of Result objects.
+
+    If all results are Ok, returns an Ok containing a tuple of all success values.
+    If any result is an Err, returns the first Err encountered.
+
+    Args:
+        results: A sequence of Result objects.
+
+    Returns:
+        A single Result object. Ok(tuple of success values) or the first Err.
+
+    Examples:
+        Heterogeneous types (use tuple):
+        >>> user_id: Result[int, Exception] = Ok(123)
+        >>> email: Result[str, Exception] = Ok("user@example.com")
+        >>> combine((user_id, email))
+        Ok((123, "user@example.com"))
+
+        Homogeneous types (use list or tuple):
+        >>> results = [Ok(1), Ok(2), Ok(3)]
+        >>> combine(results)
+        Ok((1, 2, 3))
+
+        Error handling (first error returned):
+        >>> results = [Ok(1), Err(Exception("error")), Ok(3)]
+        >>> combine(results)
+        Err(Exception("error"))
+    """
+    values: list[Any] = []
+    for r in results:
+        if isinstance(r, Err):
+            return r  # Return the first error found
+        values.append(r.unwrap())
+    return Ok(tuple(values))
+
+
+@overload
+def combine_all[T1, E: Exception](
+    results: tuple[Result[T1, E]],
+) -> Result[tuple[T1], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E]],
+) -> Result[tuple[T1, T2], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E], Result[T3, E]],
+) -> Result[tuple[T1, T2, T3], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, E: Exception](
+    results: tuple[Result[T1, E], Result[T2, E], Result[T3, E], Result[T4, E]],
+) -> Result[tuple[T1, T2, T3, T4], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, T6, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, T6, T7, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, T6, T7, T8, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, T6, T7, T8, T9, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+        Result[T9, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9], ExceptionGroup]: ...
+
+
+@overload
+def combine_all[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, E: Exception](
+    results: tuple[
+        Result[T1, E],
+        Result[T2, E],
+        Result[T3, E],
+        Result[T4, E],
+        Result[T5, E],
+        Result[T6, E],
+        Result[T7, E],
+        Result[T8, E],
+        Result[T9, E],
+        Result[T10, E],
+    ],
+) -> Result[tuple[T1, T2, T3, T4, T5, T6, T7, T8, T9, T10], ExceptionGroup]: ...
+
+
+def combine_all[E: Exception](
+    results: Sequence[Result[Any, E]],
+) -> Result[tuple[Any, ...], ExceptionGroup]:
+    """
+    Aggregates a tuple of Results, collecting all errors.
+
+    If all results are Ok, returns an Ok containing a tuple of all success values.
+    If any result is an Err, returns an Err containing an ExceptionGroup with all errors.
+
+    This is a "fail complete" strategy - useful for validation where you want to show
+    all errors to the user at once, rather than one at a time.
+
+    Args:
+        results: A tuple of Result objects.
+
+    Returns:
+        Ok(tuple of success values) if all succeed,
+        or Err(ExceptionGroup("Multiple errors occurred", list of errors)) if any fail.
+
+    Example:
+        >>> from app.core.result import combine_all, Ok, Err
+        >>> results = (Ok(1), Err(Exception("error1")), Ok(3), Err(Exception("error2")))
+        >>> combined = combine_all(results)
+        >>> # Returns Err(ExceptionGroup("Multiple errors occurred", [Exception("error1"), Exception("error2")]))
+    """
+    values: list[Any] = []
+    errors: list[E] = []
+
+    for r in results:
+        if isinstance(r, Err):
+            errors.append(r.error)
+        else:
+            values.append(r.unwrap())
+
+    if errors:
+        return Err(ExceptionGroup("Multiple errors occurred", errors))
+
+    return Ok(tuple(values))

flow_res-0.1.0/src/flow_res/guards.py

@@ -0,0 +1,23 @@
+from typing import TypeIs
+
+from .result import Err, Ok, Result
+
+
+def is_ok[T, E: Exception = Exception](result: Result[T, E]) -> TypeIs[Ok[T]]:
+    """
+    Return true if the result is ok.
+
+    Uses TypeIs for bidirectional type narrowing - when this returns False,
+    the type checker knows the result must be Err.
+    """
+    return isinstance(result, Ok)
+
+
+def is_err[T, E: Exception = Exception](result: Result[T, E]) -> TypeIs[Err[E]]:
+    """
+    Return true if the result is an error.
+
+    Uses TypeIs for bidirectional type narrowing - when this returns False,
+    the type checker knows the result must be Ok.
+    """
+    return isinstance(result, Err)

flow_res-0.1.0/src/flow_res/result.py

@@ -0,0 +1,191 @@
+"""Generic Result type, inspired by Rust's Result type."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Never
+
+
+@dataclass(frozen=True)
+class Ok[T]:
+    """Represents a successful result."""
+
+    value: T
+    __match_args__ = ("value",)
+
+    def map[V](self, f: Callable[[T], V]) -> "Ok[V]":
+        """
+        Transform the Ok value using the provided function.
+
+        Args:
+            f: Function to apply to the Ok value (T -> V)
+
+        Returns:
+            Ok[V] containing the transformed value
+
+        Example:
+            Ok(5).map(lambda x: x * 2)  # Returns Ok(10)
+        """
+        return Ok(f(self.value))
+
+    def and_then[V, F_Exc: Exception](
+        self, f: Callable[[T], "Result[V, F_Exc]"]
+    ) -> "Result[V, F_Exc]":
+        """
+        Apply a function that returns a Result, flattening the nested Result.
+
+        This is the monadic bind operation (flatMap in some languages).
+        Enables chaining operations that may fail.
+
+        Args:
+            f: Function that takes the Ok value and returns a new Result (T -> Result[V, F])
+
+        Returns:
+            Result[V, F] - The result of applying the function
+
+        Example:
+            Ok(5).and_then(lambda x: Ok(x * 2))  # Returns Ok(10)
+            Ok(5).and_then(lambda x: Err(Exception("failed")))  # Returns Err(Exception("failed"))
+        """
+        return f(self.value)
+
+    def unwrap(self) -> T:
+        """
+        Return the Ok value.
+
+        Returns:
+            The wrapped value
+        """
+        return self.value
+
+    def expect(self, msg: str) -> T:
+        """
+        Return the value.
+
+        Compatible with Err.expect signature to allow usage without type guards,
+        but requires a message explaining why success is expected.
+
+        Args:
+            msg: Message explaining why this Result is expected to be Ok (for consistency)
+
+        Returns:
+            The wrapped value
+        """
+        return self.value
+
+    def map_err[F_Exc: Exception](self, f: Callable[[Any], F_Exc]) -> "Ok[T]":
+        """
+        Pass through the Ok value unchanged.
+
+        Args:
+            f: Function to map error (ignored for Ok).
+
+        Returns:
+            Self (unchanged Ok value).
+        """
+        return self
+
+    def unwrap_or[T_Def](self, default: T_Def) -> T | T_Def:
+        """
+        Return the Ok value.
+
+        Args:
+            default: Value to return if Err. (Ignored for Ok)
+
+        Returns:
+            The wrapped value.
+        """
+        return self.value
+
+
+@dataclass(frozen=True)
+class Err[E: Exception = Exception]:
+    """Represents a failure result."""
+
+    error: E
+    __match_args__ = ("error",)
+
+    def map[V](self, f: Callable[[Any], Any]) -> "Err[E]":
+        """
+        Pass through the error unchanged (Railway-oriented programming pattern).
+
+        Args:
+            f: Function that would be applied (ignored for Err)
+
+        Returns:
+            Self (unchanged Err)
+        """
+        return self
+
+    def and_then[V, F_Exc: Exception](
+        self, f: Callable[[Any], "Result[V, F_Exc]"]
+    ) -> "Err[E]":
+        """
+        Pass through the error unchanged (Railway-oriented programming pattern).
+
+        Since this is an Err, the function is not called and the error propagates.
+
+        Args:
+            f: Function that would be applied (ignored for Err)
+
+        Returns:
+            Self (unchanged Err)
+
+        Example:
+            Err(Exception("error")).and_then(lambda x: Ok(x * 2))  # Returns Err(Exception("error"))
+        """
+        return self
+
+    def expect(self, msg: str) -> Never:
+        """
+        Raise an exception with the provided message.
+
+        Used when you want to assert that this Result should be Ok.
+        Requires a message explaining why the Result was expected to be Ok.
+
+        Args:
+            msg: Message explaining why this was expected to be Ok
+
+        Raises:
+            RuntimeError: Always raised with the provided message and underlying error
+
+        Example:
+            result.expect("User should exist in database")
+        """
+        raise RuntimeError(f"{msg}: {self.error}") from self.error
+
+    def map_err[F_Exc: Exception](self, f: Callable[[E], F_Exc]) -> "Err[F_Exc]":
+        """
+        Transform the Err value using the provided function.
+
+        Args:
+            f: Function to apply to the Err value (E -> F).
+
+        Returns:
+            Err[F] containing the transformed error.
+        """
+        new_error = f(self.error)
+        return Err(new_error)
+
+    def unwrap(self) -> Never:
+        """
+        Raise the underlying error.
+
+        This ensures that unwrap() can be called on Result (Ok | Err).
+        """
+        raise self.error
+
+    def unwrap_or[T_Def](self, default: T_Def) -> T_Def:
+        """
+        Return the default value.
+
+        Args:
+            default: Value to return.
+
+        Returns:
+            The default value.
+        """
+        return default
+
+
+# The main Result type alias
+type Result[T, E: Exception = Exception] = Ok[T] | Err[E]

flow_res-0.1.0/src/flow_res/safe.py

@@ -0,0 +1,74 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, overload
+
+from .result import Err, Ok, Result
+
+
+@overload
+def safe(
+    *exceptions: type[Exception],
+) -> Callable[[Callable[..., Any]], Callable[..., Result[Any, Exception]]]: ...
+
+
+@overload
+def safe[T](__func: Callable[..., T]) -> Callable[..., Result[T, Exception]]: ...
+
+
+def safe(*args: Any) -> Any:
+    """
+    Decorator to convert a function that raises exceptions into one that returns a Result.
+
+    Can be used without arguments to catch all Exceptions, or with specific exception types
+    to only catch those.
+
+    Args:
+        *args: Either a single function (when used as @safe), or one or more Exception types
+               (when used as @safe(ValueError, TypeError)).
+
+    Returns:
+        A wrapped function that returns Result[T, Exception] instead of raising
+
+    Example:
+        @safe
+        def risky_operation(x: int) -> int:
+            if x < 0:
+                raise ValueError("Negative number")
+            return x * 2
+
+        @safe(ValueError, TypeError)
+        def parse_data(data: dict) -> int:
+            return int(data["value"])
+    """
+    if (
+        len(args) == 1
+        and callable(args[0])
+        and not (isinstance(args[0], type) and issubclass(args[0], Exception))
+    ):
+        # Called as @safe without parentheses
+        func = args[0]
+        exceptions = (Exception,)
+
+        @wraps(func)
+        def wrapper(*w_args: Any, **w_kwargs: Any) -> Result[Any, Exception]:
+            try:
+                return Ok(func(*w_args, **w_kwargs))
+            except exceptions as e:
+                return Err(e)
+
+        return wrapper
+
+    # Called as @safe(ValueError, TypeError)
+    exceptions = args if args else (Exception,)
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Result[Any, Exception]]:
+        @wraps(func)
+        def wrapper(*w_args: Any, **w_kwargs: Any) -> Result[Any, Exception]:
+            try:
+                return Ok(func(*w_args, **w_kwargs))
+            except exceptions as e:
+                return Err(e)
+
+        return wrapper
+
+    return decorator