thresult 0.9.19

Tangled Result

thresult

Overview

Python Result library for handling returned values (Result, Ok, Err) from functions/methods and handling errors. It is error handling library which is alternative to try/except style of programming.

It is inspired by great Rust Result, Ok, Err types.

Installation

pip install thresult

Simple Usage

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

Using Result as Context Manager

from thresult import Result, Ok, Err


@Result[float]
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

Unwrapping Result in unwrap Context Manager

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


try:
    with unwrap():
        r: float = f(1, 0)
        # unreachable 
except Exception as e:
    # exception happened
    raise e

Advanced Usage

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

Run / Develop Cycle

docker run --rm -it -v $PWD/thresult:/code -w /code python:3.11-alpine python -B result.py

Testing

docker-compose build thresult-test ; docker-compose run --rm -v $PWD:/test thresult-test

Coverage

docker-compose build thresult-coverage ; docker-compose run --rm -v $PWD:/test thresult-coverage

Building

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

Licensing

thresult is licensed under the BSD 3 license.

Check the LICENSE for details