thresult 0.9.14

TangledHub Result

thresult

Overview

TangledHub library for handling returned values from functions/methods and handling errors.

Installation

pip install thresult

Examples

Traditional Python try-except example

def div(x: float, y: float) -> float:
    z: float = x / y
    return z


z0: float = div(1.0, 2.0) # 0.5
z1: float = div(1.0, 0.0) # raises "ZeroDivisionError: division by zero" exception

Manually create Result value, and Structural Pattern Matching

from thresult import Result, Ok, Err


def div(x: float, y: float) -> Result[float, Exception]:
    res: Result[float, Exception]

    try:
        # can raise "ZeroDivisionError: division by zero" exception
        z: float = x / y
        res = Ok[float](z)
    except Exception as e:
        res = Err[Exception](e)

    return res


r0: Result = div(1.0, 2.0) # Ok
r1: Result = div(1.0, 0.0) # Err

match r0:
    case Ok(v):
        print('Ok, value:', v)
    case Err(e):
        print('Err, error:', e) # "ZeroDivisionError: division by zero"

match r1:
    case Ok(v):
        print('Ok, value:', v)
    case Err(e):
        print('Err, error:', e) # "ZeroDivisionError: division by zero"

z0: float = r0.unwrap() # 0.5
z1: float = r1.unwrap_or(float('inf')) # inf
z1: float = r1.unwrap() # raises "ZeroDivisionError: division by zero" exception

Decorate function with Result, and Structural Pattern Matching

from thresult import Result, Ok, Err


@Result[float, Exception]
def div(x: float, y: float) -> float:
    # can raise "ZeroDivisionError: division by zero" exception
    z: float = x / y
    return z


r0: Result = div(1.0, 2.0) # Ok
r1: Result = div(1.0, 0.0) # Err

match r0:
    case Ok(v):
        print('Ok, value:', v)
    case Err(e):
        print('Err, error:', e) # "ZeroDivisionError: division by zero"

match r1:
    case Ok(v):
        print('Ok, value:', v)
    case Err(e):
        print('Err, error:', e) # "ZeroDivisionError: division by zero"

z0: float = r0.unwrap() # 0.5
z1: float = r1.unwrap_or(float('inf')) # inf
z1: float = r1.unwrap() # raises "ZeroDivisionError: division by zero" exception

Using Result as context manager (with statement)

from thresult import Result, Ok, Err


@Result[float, Exception]
def div(x: float, y: float) -> float:
    z: float = x / y
    return z


try:
    with div(1.0, 0.0) as z:
        # unreachable 
        pass
except ZeroDivisionError as e:
    # exception happened
    pass

Decorate function with auto_unwrap and Result

from thresult import Result, Ok, Err, auto_unwrap


@auto_unwrap
@Result[float, Exception]
def div(x: float, y: float) -> float:
    z: float = x / y
    return z


z0: float = div(1.0, 2.0) # 0.5
z1: float = div(1.0, 0.0) # raises "ZeroDivisionError: division by zero" exception

Testing

docker-compose build thresult-test ; docker-compose run --rm thresult-test

Building

docker-compose build thresult-build ; docker-compose run --rm thresult-build

Licensing

thresult is licensed under the BSD license.

Check the LICENSE for details