feat: added a few decorators

Author: wrath-codes

tasks/tasks-0001-prd-klaw-result.md

@@ -122,19 +122,19 @@
   - [x] 2.19 Add `__repr__`, `__eq__`, `__hash__` via msgspec.Struct defaults
   - [x] 2.20 Export all types from `types/__init__.py`
 
-- [ ] 3.0 Decorators & Propagation
-
-  - [ ] 3.1 Implement `@safe` decorator using `wrapt.decorator` — catches exceptions, returns `Err(exception)`
-  - [ ] 3.2 Implement `@safe_async` decorator for async functions
-  - [ ] 3.3 Implement `@pipe` decorator — wraps return value in `Ok()`
-  - [ ] 3.4 Implement `@pipe_async` decorator for async functions
-  - [ ] 3.5 Implement `@result` decorator — catches `Propagate` exception, returns contained `Err`
-  - [ ] 3.6 Implement `@result` for async functions (same decorator, detect async)
-  - [ ] 3.7 Implement `@do` decorator — generator-based do-notation with `yield` for Result extraction
-  - [ ] 3.8 Implement `@do_async` decorator — async generator do-notation
-  - [ ] 3.9 Ensure all decorators preserve function signatures and type hints via `wrapt`
-  - [ ] 3.10 Add context manager support to Result/Option for `with result.ctx as value:` unwrapping
-  - [ ] 3.11 Export all decorators from `decorators/__init__.py`
+- [x] 3.0 Decorators & Propagation
+
+  - [x] 3.1 Implement `@safe` decorator using `wrapt.decorator` — catches exceptions, returns `Err(exception)`
+  - [x] 3.2 Implement `@safe_async` decorator for async functions
+  - [x] 3.3 Implement `@pipe` decorator — wraps return value in `Ok()`
+  - [x] 3.4 Implement `@pipe_async` decorator for async functions
+  - [x] 3.5 Implement `@result` decorator — catches `Propagate` exception, returns contained `Err`
+  - [x] 3.6 Implement `@result` for async functions (same decorator, detect async)
+  - [x] 3.7 Implement `@do` decorator — generator-based do-notation with `yield` for Result extraction
+  - [x] 3.8 Implement `@do_async` decorator — async generator do-notation
+  - [x] 3.9 Ensure all decorators preserve function signatures and type hints via `wrapt`
+  - [x] 3.10 Add context manager support to Result/Option for `with result.ctx as value:` unwrapping
+  - [x] 3.11 Export all decorators from `decorators/__init__.py`
 
 - [ ] 4.0 Composition & Operators
 

workspaces/python/klaw-result/src/klaw_result/decorators/do.py

@@ -1,15 +1,135 @@
 """@do and @do_async decorators for generator-based do-notation."""
 
-# Placeholder - implementation in Task 3.0
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Generator
+from typing import Any, ParamSpec, TypeVar
+
+import wrapt
+
+from klaw_result.types.option import NothingType, Some
+from klaw_result.types.result import Err, Ok
 
 __all__ = ["do", "do_async"]
 
+P = ParamSpec("P")
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+def do(
+    func: Callable[P, Generator[Ok[Any] | Err[E] | Some[Any] | NothingType, Any, T]],
+) -> Callable[P, Ok[T] | Err[E]]:
+    """Decorator for generator-based do-notation with Result.
+
+    Enables Haskell-style do-notation using generators. Yield Result values
+    to extract their Ok values; if an Err is yielded, it short-circuits and
+    returns that Err immediately.
+
+    The generator should yield Result values and return the final value
+    to be wrapped in Ok.
+
+    Args:
+        func: A generator function that yields Results and returns T.
+
+    Returns:
+        A function that returns Result[T, E].
+
+    Examples:
+        >>> @do
+        ... def compute() -> Generator[Result[int, str], int, int]:
+        ...     x = yield get_x()  # Returns Err early if get_x() is Err
+        ...     y = yield get_y()  # Returns Err early if get_y() is Err
+        ...     return x + y
+        >>> compute()
+        Ok(value=...)  # or Err(...) if any step failed
+    """
+
+    @wrapt.decorator
+    def wrapper(
+        wrapped: Callable[
+            P, Generator[Ok[Any] | Err[E] | Some[Any] | NothingType, Any, T]
+        ],
+        instance: Any,  # noqa: ARG001
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> Ok[T] | Err[E]:
+        gen = wrapped(*args, **kwargs)
+        try:
+            result = next(gen)
+            while True:
+                if isinstance(result, Err):
+                    return result
+                if isinstance(result, NothingType):
+                    return Err(None)  # type: ignore[arg-type]
+                if isinstance(result, Ok):
+                    value = result.value
+                elif isinstance(result, Some):
+                    value = result.value
+                else:
+                    value = result
+                result = gen.send(value)
+        except StopIteration as e:
+            return Ok(e.value)
+
+    return wrapper(func)  # type: ignore[return-value]
+
+
+def do_async(
+    func: Callable[P, AsyncGenerator[Ok[Any] | Err[E] | Some[Any] | NothingType, Any]],
+) -> Callable[P, Any]:
+    """Async decorator for generator-based do-notation with Result.
+
+    Enables Haskell-style do-notation using async generators. Yield Result
+    values to extract their Ok values; if an Err is yielded, it short-circuits
+    and returns that Err immediately.
+
+    Note: Async generators cannot have a return value in Python, so the last
+    yielded Ok value is used as the final result.
+
+    Args:
+        func: An async generator function that yields Results.
+
+    Returns:
+        An async function that returns Result[T, E].
 
-def do(fn):
-    """Placeholder for @do decorator."""
-    return fn
+    Examples:
+        >>> @do_async
+        ... async def compute():
+        ...     x = yield await fetch_x()  # Returns Err early if fetch_x() is Err
+        ...     y = yield await fetch_y()  # Returns Err early if fetch_y() is Err
+        ...     yield Ok(x + y)  # Final result
+    """
 
+    @wrapt.decorator
+    async def wrapper(
+        wrapped: Callable[
+            P, AsyncGenerator[Ok[Any] | Err[E] | Some[Any] | NothingType, Any]
+        ],
+        instance: Any,  # noqa: ARG001
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> Ok[T] | Err[E]:
+        gen = wrapped(*args, **kwargs)
+        last_ok: Ok[Any] | None = None
+        try:
+            result = await gen.asend(None)
+            while True:
+                if isinstance(result, Err):
+                    return result
+                if isinstance(result, NothingType):
+                    return Err(None)  # type: ignore[arg-type]
+                if isinstance(result, Ok):
+                    last_ok = result
+                    value = result.value
+                elif isinstance(result, Some):
+                    value = result.value
+                else:
+                    value = result
+                result = await gen.asend(value)
+        except StopAsyncIteration:
+            if last_ok is not None:
+                return last_ok
+            return Ok(None)  # type: ignore[arg-type]
 
-def do_async(fn):
-    """Placeholder for @do_async decorator."""
-    return fn
+    return wrapper(func)

workspaces/python/klaw-result/src/klaw_result/decorators/pipe.py

@@ -1,15 +1,82 @@
 """@pipe and @pipe_async decorators for wrapping return values in Ok."""
 
-# Placeholder - implementation in Task 3.0
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar
+
+import wrapt
+
+from klaw_result.types.result import Ok
 
 __all__ = ["pipe", "pipe_async"]
 
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+def pipe(func: Callable[P, T]) -> Callable[P, Ok[T]]:
+    """Decorator that wraps the return value in Ok.
+
+    Useful for functions that never fail, to make them compatible
+    with Result-based pipelines.
+
+    Args:
+        func: The function to wrap.
+
+    Returns:
+        A wrapped function that returns Ok[T] instead of T.
+
+    Examples:
+        >>> @pipe
+        ... def add(a: int, b: int) -> int:
+        ...     return a + b
+        >>> add(2, 3)
+        Ok(value=5)
+    """
+
+    @wrapt.decorator
+    def wrapper(
+        wrapped: Callable[P, T],
+        instance: Any,  # noqa: ARG001
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> Ok[T]:
+        return Ok(wrapped(*args, **kwargs))
+
+    return wrapper(func)  # type: ignore[return-value]
+
+
+def pipe_async(
+    func: Callable[P, Awaitable[T]],
+) -> Callable[P, Awaitable[Ok[T]]]:
+    """Async decorator that wraps the return value in Ok.
+
+    Useful for async functions that never fail, to make them compatible
+    with Result-based pipelines.
+
+    Args:
+        func: The async function to wrap.
+
+    Returns:
+        A wrapped async function that returns Ok[T] instead of T.
 
-def pipe(fn):
-    """Placeholder for @pipe decorator."""
-    return fn
+    Examples:
+        >>> @pipe_async
+        ... async def fetch_data() -> str:
+        ...     return "data"
+        >>> await fetch_data()
+        Ok(value='data')
+    """
 
+    @wrapt.decorator
+    async def wrapper(
+        wrapped: Callable[P, Awaitable[T]],
+        instance: Any,  # noqa: ARG001
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> Ok[T]:
+        result = await wrapped(*args, **kwargs)
+        return Ok(result)
 
-def pipe_async(fn):
-    """Placeholder for @pipe_async decorator."""
-    return fn
+    return wrapper(func)  # type: ignore[return-value]

workspaces/python/klaw-result/src/klaw_result/decorators/result.py

@@ -1,10 +1,77 @@
 """@result decorator for catching Propagate exceptions."""
 
-# Placeholder - implementation in Task 3.0
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, TypeVar
+
+import wrapt
+
+from klaw_result.types.propagate import Propagate
+from klaw_result.types.result import Err, Ok
 
 __all__ = ["result"]
 
+P = ParamSpec("P")
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+def result(
+    func: Callable[P, Ok[T] | Err[E]] | Callable[P, Awaitable[Ok[T] | Err[E]]],
+) -> Callable[P, Ok[T] | Err[E]] | Callable[P, Awaitable[Ok[T] | Err[E]]]:
+    """Decorator that catches Propagate exceptions for .bail() support.
+
+    When a function decorated with @result calls .bail() on an Err,
+    the Propagate exception is caught and the Err is returned.
+    This enables Rust-like ? operator semantics.
+
+    Automatically detects async functions and handles them appropriately.
+
+    Args:
+        func: The function to wrap. Must return a Result type.
+
+    Returns:
+        A wrapped function that catches Propagate and returns the contained Err.
+
+    Examples:
+        >>> @result
+        ... def process(x: int) -> Result[int, str]:
+        ...     value = get_value(x).bail()  # Returns Err early if get_value fails
+        ...     return Ok(value * 2)
+
+        >>> @result
+        ... async def async_process(x: int) -> Result[int, str]:
+        ...     value = (await fetch(x)).bail()
+        ...     return Ok(value * 2)
+    """
+    if asyncio.iscoroutinefunction(func):
+
+        @wrapt.decorator
+        async def async_wrapper(
+            wrapped: Callable[P, Awaitable[Ok[T] | Err[E]]],
+            instance: Any,  # noqa: ARG001
+            args: tuple[Any, ...],
+            kwargs: dict[str, Any],
+        ) -> Ok[T] | Err[E]:
+            try:
+                return await wrapped(*args, **kwargs)
+            except Propagate as p:
+                return p.value  # type: ignore[return-value]
+
+        return async_wrapper(func)  # type: ignore[return-value]
+
+    @wrapt.decorator
+    def sync_wrapper(
+        wrapped: Callable[P, Ok[T] | Err[E]],
+        instance: Any,  # noqa: ARG001
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> Ok[T] | Err[E]:
+        try:
+            return wrapped(*args, **kwargs)
+        except Propagate as p:
+            return p.value  # type: ignore[return-value]
 
-def result(fn):
-    """Placeholder for @result decorator."""
-    return fn
+    return sync_wrapper(func)  # type: ignore[return-value]