Result Pattern

https://github.com/zuidvolt/result-pattern
Admin
Result Pattern is a Python library implementing the 'Errors as Values' pattern with Result and...
Tokens:10,925
Snippets:81
Trust Score:5.3
License:LGPL-3.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install result-pattern Library

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Installs the 'result-pattern' library using pip. The package name for installation is 'result-pattern', but the module to import in Python code is 'result'.

```shell
# Package name is 'result-pattern', but you import 'result'
$ pip install result-pattern
```

--------------------------------

### Using match Statements for Result Handling

Source: https://github.com/zuidvolt/result-pattern/blob/main/GEMINI.md

Provides an example of using Python's `match` statement for exhaustive pattern matching on `Result` types (`Ok` and `Err`), offering a clear and readable way to handle different outcomes.

```python
from result import Ok, Err

def process_result(res):
    match res:
        case Ok(value):
            print(f"Got value: {value}")
        case Err(error):
            print(f"Encountered error: {error}")

# Example Usage:
process_result(Ok('Data processed'))
# Output: Got value: Data processed

process_result(Err('Network error'))
# Output: Encountered error: Network error

```

--------------------------------

### Python 3.10+ Pattern Matching with Result

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Illustrates how to use Python 3.10+'s native `match` statement with the `Result` type. This provides a clean syntax for handling `Ok` and `Err` cases, leveraging optimized `__match_args__`.

```python
match divide(10, 0):
    case Ok(val):
        print(f"Value: {val}")
    case Err(msg):
        print(f"Error: {msg}")
```

--------------------------------

### Exception Handling with @catch Decorator and Context Manager in Python

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Shows how to use the `@catch` decorator and context manager to lift exception-throwing functions into `Result`-returning functions. It covers basic exception catching, mapping exceptions to custom domain errors, and handling multiple exception types.

```python
from result import catch, catch_call
from enum import StrEnum
import json

class ErrorCode(StrEnum):
    INVALID = "invalid_input"
    PARSE_ERROR = "parse_error"

# Basic catch - wraps exceptions in Err
@catch(ValueError)
def parse_int(s: str) -> int:
    return int(s)

print(parse_int("10"))
print(parse_int("abc"))

# Map exceptions to domain errors with map_to
@catch(ValueError, map_to=ErrorCode.INVALID)
def strict_parse(s: str) -> int:
    return int(s)

print(strict_parse("abc"))

# Multiple exception mapping with dictionary
@catch({ValueError: ErrorCode.INVALID, json.JSONDecodeError: ErrorCode.PARSE_ERROR})
def process_json(data: str) -> dict:
    return json.loads(data)

# Inline execution with catch_call
result = catch_call(json.JSONDecodeError, json.loads, '{"key": "value"}')
print(result)

# Context manager usage
with catch(json.JSONDecodeError) as ctx:
    data = json.loads('{"name": "Alice"}')
    ctx.set(data["name"])

print(ctx.result)
```

--------------------------------

### Type Utilities: from_optional, map2, any_ok for Result Operations

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Explains and demonstrates the usage of helper functions like `from_optional` to convert Python's `Optional` types to `Result`, `map2` to apply a binary function to two `Result` objects, and `any_ok` to retrieve the first successful `Result` or collect all errors from a list of `Result` objects.

```python
from result import Ok, Err, from_optional, map2, any_ok

# from_optional: convert Optional to Result
result = from_optional(42, "No value")
print(result)  # Ok(42)

result = from_optional(None, "No value")
print(result)  # Err('No value')

# map2: apply binary function to two Results
result = map2(Ok(10), Ok(5), lambda x, y: x + y)
print(result)  # Ok(15)

result = map2(Ok(10), Err("fail"), lambda x, y: x + y)
print(result)  # Err('fail')

# any_ok: return first success or all errors
result = any_ok([Err("e1"), Ok(42), Err("e2")])
print(result)  # Ok(42)

result = any_ok([Err("e1"), Err("e2"), Err("e3")])
print(result)  # Err(['e1', 'e2', 'e3'])
```

--------------------------------

### Safe and Unsafe Operations with Result.unsafe Namespace

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Illustrates safe value retrieval from `Ok` and `Err` variants using methods like `ok()`, `err()`, `unwrap_or()`, and `unwrap_or_else()`. It also shows how to use the `.unsafe` namespace for operations that can panic, such as `unwrap()` and `unwrap_err()`, and how to handle potential `UnwrapError` exceptions.

```python
from result import Ok, Err, UnwrapError

ok_result = Ok(42)
err_result = Err("something went wrong")

# Safe access (no exceptions)
print(ok_result.ok())           # 42
print(ok_result.err())          # None
print(err_result.unwrap_or(0))  # 0
print(err_result.unwrap_or_else(lambda e: len(e)))  # 20

# Unsafe operations (can panic) - must use .unsafe namespace
print(ok_result.unsafe.unwrap())      # 42
print(err_result.unsafe.unwrap_err()) # 'something went wrong'

# Custom panic message
print(ok_result.unsafe.expect("Should have value"))  # 42

try:
    err_result.unsafe.unwrap()
except UnwrapError as e:
    print(f"Panic: {e}")  # Panic: Called unwrap on an Err value: 'something went wrong'

# Raise custom exception
try:
    err_result.unsafe.unwrap_or_raise(RuntimeError)
except RuntimeError as e:
    print(f"Custom error: {e}")  # Custom error: something went wrong
```

--------------------------------

### Context Manager for Exception Handling with catch

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Demonstrates using `catch` as a context manager to wrap a block of code. Any exceptions raised within the `with` block are caught and stored in the `safe_block.result` attribute as an `Err`.

```python
from result import catch
import json

with catch(json.JSONDecodeError) as safe_block:
    data = json.loads(payload)
    # Perform complex logic...
    safe_block.set(data["nested"]["key"])

# result is narrowed to Result[T, JSONDecodeError]
print(safe_block.result)
```

--------------------------------

### Inline Exception Catching with catch_call

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Shows how to use `catch_call` for inline exception handling of standard library functions or other callables. It takes the exception type, the callable, and its arguments, returning a `Result`.

```python
from result import catch_call
import json

res = catch_call(json.JSONDecodeError, json.loads, '{"key": "value"}')
```

--------------------------------

### Using @do_notation for Complex Logic

Source: https://github.com/zuidvolt/result-pattern/blob/main/GEMINI.md

Demonstrates how to use the `@do_notation` decorator with Python generators to simulate monad-like behavior for complex logic, handling early returns of `Err` values and wrapping final `Ok` values.

```python
from result import Ok, Err, do_notation

@do_notation
def process_data(data):
    user = yield data.get('user')
    profile = yield fetch_profile(user)
    return Ok(f"Processed {user}'s profile: {profile}")

@do_notation
def fetch_profile(user):
    if user == 'admin':
        return Err('Admin profile not available')
    return Ok({'name': user, 'email': f'{user}@example.com'})

# Example Usage:
result1 = process_data({'user': 'alice'})
# result1 will be Ok("Processed alice's profile: {'name': 'alice', 'email': 'alice@example.com'}")

result2 = process_data({'user': 'bob'})
# result2 will be Ok("Processed bob's profile: {'name': 'bob', 'email': 'bob@example.com'}")

result3 = process_data({'user': 'admin'})
# result3 will be Err('Admin profile not available')

```

--------------------------------

### Mapping Exceptions to Enums with @catch

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Illustrates how to use the `map_to` argument or a dictionary with the `@catch` decorator to map specific exceptions to predefined error codes or values, such as Enums. This allows for standardized error representation.

```python
from enum import StrEnum
from result import catch


class ErrorCode(StrEnum):
    INVALID = "invalid_input"


# Single mapping
@catch(ValueError, map_to=ErrorCode.INVALID)
def risky_op(s: str): ...


# Multiple mapping dictionary
@catch({ValueError: ErrorCode.INVALID, KeyError: "missing"})
def complex_op(x): ...
```

--------------------------------

### Functional Chaining with map and and_then in Python

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Illustrates functional chaining using `map` and `and_then` on `Result` types. `map` transforms `Ok` values, while `and_then` chains operations that return `Result`s, enabling flatMap-like behavior and short-circuiting on errors.

```python
from result import Ok, Err, Result

def parse_int(s: str) -> Result[int, str]:
    try:
        return Ok(int(s))
    except ValueError:
        return Err(f"Invalid integer: {s}")

def validate_positive(n: int) -> Result[int, str]:
    return Ok(n) if n > 0 else Err("Must be positive")

# map: transform the success value
result = Ok(10).map(lambda x: x * 2)

# map_err: transform the error value
result = Err(404).map_err(lambda code: f"Code: {code}")

# and_then: chain fallible operations
result = (
    parse_int("42")
    .and_then(validate_positive)
    .map(lambda x: x * 2)
)
print(result)

# Short-circuits on first error
result = (
    parse_int("-5")
    .and_then(validate_positive)
    .map(lambda x: x * 2)
)
print(result)
```

--------------------------------

### Implement Strict Flow Control with Do-Notation

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Demonstrates how to use the @do_notation decorator to manage result-based control flow. The .to_result() method is used to halt execution immediately upon encountering an error.

```python
@do_notation
def strict_flow():
    # .to_result() halts execution if any errors exist
    ast = yield parse_with_diagnostics(src).to_result()
    return emit(ast)
```

--------------------------------

### Accumulate Errors with and_then and Merge Outcomes

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Demonstrates how to chain operations using `and_then` to accumulate errors from sequential operations and how to merge independent `Outcome` objects, preserving both values and errors.

```python
from result import Outcome

# Example step functions (assuming they exist and return Outcome)
def step1(x):
    if x > 0:
        return Outcome(x * 6, None)
    else:
        return Outcome(x * 6, 'step1 warning')

def step2(x):
    if x > 0:
        return Outcome(x, None)
    else:
        return Outcome(x, 'step2 warning')

result = Outcome(5, None).and_then(step1).and_then(step2)
print(result)  # Outcome(value=30, error=None)

result = Outcome(-5, "initial").and_then(step1).and_then(step2)
print(result)  # Outcome(value=-30, error=['step1 warning', 'step2 warning'])

# Merge independent outcomes
out1 = Outcome("parsed", "warning1")
out2 = Outcome(42, "warning2")
merged = out1.merge(out2)
print(merged)  # Outcome(value=('parsed', 42), error=['warning1', 'warning2'])
```

--------------------------------

### Combining and Partitioning Results

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `combine` function collects multiple Results into a single Result containing a list, operating in an all-or-nothing manner. `partition` separates Results into two lists (values and errors) without short-circuiting.

```python
from result import Ok, Err, combine, partition

results = [Ok(1), Ok(2), Ok(3)]
print(combine(results))  # Ok([1, 2, 3])

results_with_error = [Ok(1), Err("fail"), Ok(3)]
print(combine(results_with_error))  # Err('fail')

# Partition collects all values and errors separately
results = [Ok(1), Err("error1"), Ok(2), Err("error2")]
values, errors = partition(results)
print(values)  # [1, 2]
print(errors)  # ['error1', 'error2']
```

--------------------------------

### Functional Chaining with Result Type

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Shows how to chain operations on a `Result` object using methods like `map`, `tap`, and `and_then`. This allows for linear pipelines and avoids deeply nested conditional logic.

```python
Ok(10).map(lambda x: x * 2).tap(print).and_then(lambda x: Ok(x + 1))
```

--------------------------------

### Basic Result Type Usage in Python

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Demonstrates the basic usage of the `Result` type, which is a Sum Type representing either a successful `Ok` value or a failed `Err` value. Includes type hinting and checking success with `is_ok`.

```python
from result import Ok, Err, Result, is_ok


def divide(a: int, b: int) -> Result[float, str]:
    if b == 0:
        return Err("Cannot divide by zero")
    return Ok(a / b)


res = divide(10, 2)
if is_ok(res):
    # res is narrowed to Ok[float]
    print(f"Success: {res.ok()}")
```

--------------------------------

### Converting Exceptions to Result with @safe

Source: https://github.com/zuidvolt/result-pattern/blob/main/GEMINI.md

Shows how to use the `@safe` decorator to automatically convert functions that might raise exceptions into functions that return a `Result` type. This allows for seamless integration of exception-throwing code into the functional Result pattern.

```python
from result import Ok, Err, safe

@safe
def divide(a, b):
    return a / b

# Example Usage:
result_success = divide(10, 2)
# result_success will be Ok(5.0)

result_failure = divide(10, 0)
# result_failure will be Err(ZeroDivisionError('division by zero'))

```

--------------------------------

### Python: Enforce Conditions with ensure and add_context

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `ensure` function integrates boolean conditions into the `Result` type, raising an `Err` if the condition is false. `add_context` enhances error messages by prepending contextual information, making debugging easier.

```python
from result import Ok, Err, ensure, add_context, do_notation, Do

@do_notation
def process_order(quantity: int, price: float) -> Do[float, str]:
    yield ensure(quantity > 0, "Quantity must be positive")
    yield ensure(price >= 0, "Price cannot be negative")
    total = quantity * price
    yield ensure(total <= 10000, "Order exceeds maximum")
    return total

print(process_order(5, 100.0))   # Ok(500.0)
print(process_order(-1, 100.0))  # Err('Quantity must be positive')

# Add context to errors
result = Err("connection refused")
enriched = add_context(result, "Database")
print(enriched)  # Err('Database: connection refused')
```

--------------------------------

### Catching Exceptions with @catch Decorator

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Demonstrates using the `@catch` decorator to automatically convert exceptions raised by a function into `Err` variants of a `Result`. This simplifies integrating exception-prone code into a Result-based workflow.

```python
from result import catch


@catch(ValueError)
def parse_int(s: str) -> int:
    return int(s)


parse_int("10")  # Ok(10)
parse_int("abc")  # Err(ValueError(...))
```

--------------------------------

### Linear Chaining with .and_then

Source: https://github.com/zuidvolt/result-pattern/blob/main/GEMINI.md

Illustrates the use of the `.and_then()` method for simple, linear data processing pipelines. This method chains operations, passing the `Ok` value of one operation to the next, or short-circuiting if an `Err` is encountered.

```python
from result import Ok, Err

def parse_int(s):
    try:
        return Ok(int(s))
    except ValueError:
        return Err('Invalid integer string')

def square(n):
    return Ok(n * n)

def add_one(n):
    return Ok(n + 1)

# Example Usage:
result_ok = Ok('5').and_then(parse_int).and_then(square).and_then(add_one)
# result_ok will be Ok(26)

result_err = Ok('abc').and_then(parse_int).and_then(square).and_then(add_one)
# result_err will be Err('Invalid integer string')

```

--------------------------------

### Exhaustive Matching with .match()

Source: https://github.com/zuidvolt/result-pattern/blob/main/GEMINI.md

Demonstrates how to use the `.match()` method on a `Result` object to explicitly handle both success (`Ok`) and failure (`Err`) states. This ensures all possible outcomes are considered.

```python
from result import Ok, Err

def handle_result(res):
    return res.match(
        lambda ok_val: f"Success: {ok_val}",
        lambda err_val: f"Failure: {err_val}"
    )

# Example Usage:
result_ok = Ok(100)
print(handle_result(result_ok))  # Output: Success: 100

result_err = Err('Something went wrong')
print(handle_result(result_err)) # Output: Failure: Something went wrong

```

--------------------------------

### Isolate Unsafe Operations

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Illustrates the safety philosophy of isolating panics within the .unsafe namespace. This prevents accidental unwrap calls at the root level.

```python
res = Err("fail")
res.unsafe.unwrap()  # Explicit panic
```

--------------------------------

### Do-Notation for Monadic Operations in Python

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Illustrates the use of the `@do_notation` decorator for writing procedural-style code that automatically handles short-circuiting logic with `Result` types. The `yield` keyword unwraps `Ok` values or propagates `Err`.

```python
from result import do_notation, Do


@do_notation
def compile_pipeline(source: str) -> Do[str, Exception]:
    tokens = yield tokenize(source)  # Returns list[Token] or short-circuits Err
    ast = yield parse(tokens)  # Returns AST or short-circuits Err
    code = yield generate(ast)
    return code  # Automatically wrapped in Ok
```

--------------------------------

### Python Safe Context Manager for Error Handling

Source: https://github.com/zuidvolt/result-pattern/blob/main/RESEARCH.md

Implements a `safe` context manager for localized exception trapping. It catches specified exceptions and returns an `Ok` variant with the result or an `Err` variant with the caught exception.

```python
with safe(ValueError) as res:
    x = int(input)
# res is now Ok(x) or Err(ValueError)
```

--------------------------------

### Async Monadic Do-Notation with @do_notation_async Decorator

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Provides monadic do-notation for asynchronous operations returning Result types. It handles awaiting async Result-returning functions and short-circuits on the first Err. Async generators must yield the final Ok value.

```python
from result import do_notation_async, Ok, Err, Result, DoAsync
import asyncio

async def fetch_data(url: str) -> Result[dict, str]:
    await asyncio.sleep(0.1)  # Simulate network delay
    if "valid" in url:
        return Ok({"data": f"content from {url}"})
    return Err(f"Failed to fetch {url}")

async def process_data(data: dict) -> Result[str, str]:
    return Ok(data["data"].upper())

@do_notation_async
async def fetch_and_process(url: str) -> DoAsync[str, str]:
    data = yield await fetch_data(url)
    processed = yield await process_data(data)
    yield Ok(f"Processed: {processed}")  # Must yield final Ok

async def main():
    result = await fetch_and_process("https://valid.example.com")
    print(result)  # Ok('Processed: CONTENT FROM HTTPS://VALID.EXAMPLE.COM')

    result = await fetch_and_process("https://bad.example.com")
    print(result)  # Err('Failed to fetch https://bad.example.com')

asyncio.run(main())
```

--------------------------------

### Python Result Type Product Operation

Source: https://github.com/zuidvolt/result-pattern/blob/main/RESEARCH.md

Demonstrates the `product` operation for merging two `Result` types into a tuple. If both `Result` instances are `Ok`, it returns an `Ok` containing a tuple of their values. Otherwise, it returns the first `Err` encountered.

```python
Ok(1).product(Ok(2)) -> Ok((1, 2))
```

--------------------------------

### Result Type: Ok and Err Variants in Python

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Demonstrates the `Result` type, a Sum Type representing success (`Ok`) or failure (`Err`). It shows how to use `is_ok` and `is_err` for type-safe narrowing and pattern matching (Python 3.10+) to handle different variants.

```python
from result import Ok, Err, Result, is_ok, is_err

def divide(a: int, b: int) -> Result[float, str]:
    if b == 0:
        return Err("Cannot divide by zero")
    return Ok(a / b)

# Type-safe narrowing with is_ok/is_err
res = divide(10, 2)
if is_ok(res):
    print(f"Success: {res.ok()}")

res2 = divide(10, 0)
if is_err(res2):
    print(f"Error: {res2.err()}")

# Pattern matching (Python 3.10+)
match divide(10, 0):
    case Ok(val):
        print(f"Value: {val}")
    case Err(msg):
        print(f"Error: {msg}")
```

--------------------------------

### Outcome Type for Partial Success and Diagnostics

Source: https://github.com/zuidvolt/result-pattern/blob/main/README.md

Introduces the `Outcome` type, a Product Type designed for scenarios requiring fault tolerance. It can hold both a partial success value and diagnostic information (like warnings or errors) simultaneously.

```python
from result import Outcome


def parse_with_diagnostics(source: str) -> Outcome[AST, list[str]]:
    # build AST and accumulate errors...
    return Outcome(ast, accumulated_errors)


# 1. Procedural Unpacking (Go/Odin style)
ast, errors = parse_with_diagnostics(src)
if errors:
    print(f"Warnings: {errors}")

# 2. Accumulation
new_outcome = Outcome(node, "e1").push_err("e2").merge(other_outcome)
```

--------------------------------

### Applicative Validation with @validate

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `validate` function accumulates all errors from multiple validation functions, unlike monadic chaining which short-circuits. It's ideal for scenarios like form validation where all issues need to be reported.

```python
from result import Ok, Err, validate, Result

def check_name(name: str) -> Result[str, str]:
    return Ok(name) if len(name) >= 2 else Err("Name too short")

def check_age(age: int) -> Result[int, str]:
    return Ok(age) if age >= 18 else Err("Must be 18+")

def check_email(email: str) -> Result[str, str]:
    return Ok(email) if "@" in email else Err("Invalid email")

# All validations pass
result = validate(
    check_name("Alice"),
    check_age(25),
    check_email("alice@example.com")
)
print(result)  # Ok(('Alice', 25, 'alice@example.com'))

# Accumulates ALL errors
result = validate(
    check_name("A"),
    check_age(16),
    check_email("invalid")
)
print(result)  # Err(['Name too short', 'Must be 18+', 'Invalid email'])
```

--------------------------------

### Python: Chain Fallible Functions with flow

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `flow` function orchestrates a sequential pipeline of fallible functions, improving readability over chained `.and_then()` calls. It takes an initial value and a series of functions, returning a `Result` object representing the final outcome or the first encountered error.

```python
from result import Ok, Err, Result, flow

def parse(s: str) -> Result[int, str]:
    try:
        return Ok(int(s))
    except ValueError:
        return Err("Parse error")

def validate(n: int) -> Result[int, str]:
    return Ok(n) if n > 0 else Err("Must be positive")

def double(n: int) -> Result[int, str]:
    return Ok(n * 2)

# Clean pipeline
result = flow("10", parse, validate, double)
print(result)  # Ok(20)

result = flow("-5", parse, validate, double)
print(result)  # Err('Must be positive')
```

--------------------------------

### Python: Chain and Merge Outcomes Accumulating Errors

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

This demonstrates chaining operations using the `Outcome` type, where errors are accumulated across steps. Each step returns an `Outcome`, and subsequent operations can process the value or propagate the accumulated errors.

```python
from result import Outcome

def step1(x: int) -> Outcome[int, str]:
    return Outcome(x + 10, "step1 warning" if x < 0 else None)

def step2(x: int) -> Outcome[int, str]:
    return Outcome(x * 2, "step2 warning" if x > 50 else None)

```

--------------------------------

### Python Async: Concurrent Operations with gather_results and traverse_async

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

These utilities enable concurrent execution of asynchronous functions returning `Result` objects. `gather_results` performs operations concurrently and returns a `Result` of a list of values, failing fast on the first error. `validate_async` accumulates all errors, and `traverse_async` applies a function to an iterable concurrently with an optional concurrency limit.

```python
from result import Ok, Err, Result, gather_results, traverse_async, validate_async
import asyncio

async def fetch_user(id: int) -> Result[dict, str]:
    await asyncio.sleep(0.1)
    if id > 0:
        return Ok({"id": id, "name": f"User{id}"})
    return Err(f"Invalid ID: {id}")

async def main():
    # gather_results: all-or-nothing concurrent execution
    result = await gather_results(
        fetch_user(1),
        fetch_user(2),
        fetch_user(3)
    )
    print(result)  # Ok([{'id': 1, 'name': 'User1'}, ...])

    # First error wins
    result = await gather_results(
        fetch_user(1),
        fetch_user(-1),
        fetch_user(2)
    )
    print(result)  # Err('Invalid ID: -1')

    # validate_async: accumulate ALL errors
    result = await validate_async(
        fetch_user(-1),
        fetch_user(-2)
    )
    print(result)  # Err(['Invalid ID: -1', 'Invalid ID: -2'])

    # traverse_async with concurrency limit
    ids = [1, 2, 3, 4, 5]
    result = await traverse_async(ids, fetch_user, limit=2)
    print(result)  # Ok([...5 user dicts...])

asyncio.run(main())
```

--------------------------------

### Monadic Do-Notation with @do_notation Decorator

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

Enables imperative-style code with automatic short-circuiting for Result types. Use 'yield' to unwrap Results, and the function returns early on the first Err. Handles exceptions by catching specified error types and wrapping them in Err.

```python
from result import do_notation, Ok, Err, Result, Do

def fetch_user(id: int) -> Result[dict, str]:
    if id > 0:
        return Ok({"id": id, "name": "Alice", "email": "alice@example.com"})
    return Err("Invalid user ID")

def validate_email(email: str) -> Result[str, str]:
    return Ok(email) if "@" in email else Err("Invalid email")

def send_notification(user: dict) -> Result[str, str]:
    return Ok(f"Notification sent to {user['name']}")

@do_notation
def process_user(user_id: int) -> Do[str, str]:
    user = yield fetch_user(user_id)
    email = yield validate_email(user["email"])
    result = yield send_notification(user)
    return f"{result} at {email}"

print(process_user(1))   # Ok('Notification sent to Alice at alice@example.com')
print(process_user(-1))  # Err('Invalid user ID')

# With exception catching
@do_notation(catch=ValueError)
def parse_and_double(s: str) -> Do[int, str | ValueError]:
    value = yield Ok(int(s))  # ValueError caught and wrapped in Err
    return value * 2

print(parse_and_double("5"))    # Ok(10)
print(parse_and_double("bad"))  # Err(ValueError(...))
```

--------------------------------

### Traverse and Try-Fold Operations

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `traverse` function maps a fallible function over an iterable, short-circuiting on the first error encountered. `try_fold` performs a fallible reduction (accumulation) over an iterable, also short-circuiting on error.

```python
from result import Ok, Err, Result, traverse, try_fold

def parse_int(s: str) -> Result[int, str]:
    try:
        return Ok(int(s))
    except ValueError:
        return Err(f"Invalid: {s}")

# traverse: map and collect, short-circuit on error
result = traverse(["1", "2", "3"], parse_int)
print(result)  # Ok([1, 2, 3])

result = traverse(["1", "bad", "3"], parse_int)
print(result)  # Err('Invalid: bad')

# try_fold: fallible accumulation
def safe_divide(acc: float, n: int) -> Result[float, str]:
    if n == 0:
        return Err("Division by zero")
    return Ok(acc / n)

result = try_fold([2, 4, 5], 100.0, safe_divide)
print(result)  # Ok(2.5) -> 100/2=50, 50/4=12.5, 12.5/5=2.5

result = try_fold([2, 0, 5], 100.0, safe_divide)
print(result)  # Err('Division by zero')
```

--------------------------------

### Python: Fault-Tolerant Outcome Type for Compilers and Parsers

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `Outcome` type, unlike `Result`, always holds a value alongside an optional error. This makes it suitable for scenarios like compilers or parsers where intermediate states with warnings or non-critical errors need to be preserved. It supports mapping, error accumulation, and conversion to a strict `Result`.

```python
from result import Outcome, catch_outcome

# Create outcomes with value and optional error
clean = Outcome(42, None)
with_warning = Outcome(42, "Non-critical warning")

print(clean.has_error())        # False
print(with_warning.has_error()) # True

# Native tuple unpacking (Go/Odin style)
value, error = with_warning
print(f"Value: {value}, Error: {error}")  # Value: 42, Error: Non-critical warning

# Convert to strict Result
print(clean.to_result())        # Ok(42)
print(with_warning.to_result()) # Err('Non-critical warning')

# Transform value while preserving error
result = with_warning.map(lambda x: x * 2)
print(result)  # Outcome(value=84, error='Non-critical warning')

# Accumulate errors
out = Outcome(10, None).push_err("e1").push_err("e2")
print(out)  # Outcome(value=10, error=['e1', 'e2'])
```

--------------------------------

### Python: Catch Exceptions into Outcomes with catch_outcome Decorator

Source: https://context7.com/zuidvolt/result-pattern/llms.txt

The `catch_outcome` decorator transforms functions that might raise exceptions into functions returning an `Outcome`. It allows specifying a default value for the `Outcome` when an exception occurs and optionally mapping caught exceptions to custom domain errors.

```python
from result import Outcome, catch_outcome
from enum import StrEnum

class ErrorCode(StrEnum):
    PARSE_ERROR = "parse_error"

# Basic usage with default value
@catch_outcome(ValueError, default=0)
def parse_or_default(s: str) -> int:
    return int(s)

print(parse_or_default("42"))   # Outcome(value=42, error=None)
print(parse_or_default("bad"))  # Outcome(value=0, error=ValueError(...))

# Map exception to domain error
@catch_outcome(ValueError, default=-1, map_to=ErrorCode.PARSE_ERROR)
def strict_parse(s: str) -> int:
    return int(s)

print(strict_parse("bad"))  # Outcome(value=-1, error=<ErrorCode.PARSE_ERROR>)
```
Tokens:
Raw