toradh 0.3.0
Minimalistic library intended to bring better flow control to Python.
License: MIT
Requires Python: <4.0,>=3.9
Keywords: toradh, rust, result, optional, control-flow

# TORADH
[![codecov](https://codecov.io/github/levensworth/toradh/graph/badge.svg?token=hsojulL0hJ)](https://codecov.io/github/levensworth/toradh)
[![pypi](https://img.shields.io/pypi/v/toradh.svg)](https://pypi.python.org/pypi/toradh/)
[![version](https://img.shields.io/pypi/pyversions/toradh.svg)](https://pypi.python.org/pypi/toradh/)
[![license](https://img.shields.io/pypi/l/toradh.svg)](https://en.wikipedia.org/wiki/GNU_General_Public_License)
[![PyPI Downloads](https://static.pepy.tech/badge/toradh)](https://pepy.tech/projects/toradh)


Minimalistic library intended to bring better flow control to Python.

## Motivation:
Have you ever install a new sdk or lib that you really wanted to use for a particular project only to find out, mid development
that if you try to `.get()` something that is not present in the instance it will `raise` an `ValueError` which was not mentioned
in any docstring. Does it sounds familiar? well, this kind of frustration is what `toradh` (pronounced "taru") comes to ease.
By bringing some of the key fundamental structures of languages such as `Rust` to Python, we aim to make exception handling a little
less chaotic and more predictable when needed. 

## Install:
```
pip install toradh
```


## Usage:
We support structural pattern matching with the `match` operator as well as build in methods for control flow management.

```python
from typing import Literal
from toradh import Result, Ok, Err

DB = {
    1: 'john', 
    2: 'jane',
}

def create_user(name: str) -> Result[int, ValueError | KeyError]:
    if name in DB:
        return Err(KeyError(f'A user by {name} already exists'))
    if len(name) > 10:
        return Err(ValueError('names can not be too long'))
    user_id = len(DB)+1
    DB[user_id] = name
    return Ok(user_id)

def basic_handling():
    # In this example, we don't want to interrupt the execution
    # but we don't really want to handle specific errors
    res = create_user('janet')
    match res:
        case Ok(user_id):
            print(f'successfully persisted under {user_id}')
        case Err(err):
            print(f'There was an error => {err}')

def concrete_error_handling():
    # In this case, we are handling each possible scenario and 
    # taking some sort of action based on the type of error
    res = create_user('janet')
    
    # If all cases aren't handle mypy will alert about this.
    match res.kind():
        case int():
            print(f'successfully persisted under {res.unwrap()}')
        case ValueError():
            print(f'There was a problem with the name\'s length')
        case KeyError():
            print(f'Name already exists')
            #include possible measure to recover from this error
            # ...

def no_handling():
    # in this case, we do not want to handle the possible errors
    # if any are give, the .unwrap() call simply raise them as normal python code
    res = create_user('janet')
    print(f'successfully persisted under {res.unwrap()}')

if __name__ == '__main__':
    basic_handling()

    concrete_error_handling()
    
    no_handling()

```


## why use Toradh?
First let's go over some simple examples:

Let's go over an example not using the framework
```python

DB = {
    1: 'john', 
    2: 'jane',
}

# instead of this
def get_user_by_id_old(user_id: int) -> str | None:
    return DB.get(user_id)    

def main():
    user = get_user_by_id_old(1)
    
    if user is not None:
        print(f'Hello {user}')
    else:
        print('id not found')
```

and how it would look like if using it
```python
from toradh import Optional, Option, Nothing, Some

DB = {
    1: 'john', 
    2: 'jane',
}

def get_user_by_id_new(user_id: int) -> Optional[str]:
    if user_id not in DB:
        return Nothing()
    
    return Some(DB.get(user_id))
    
def main():
    user = get_user_by_id_new(1)
    
    if user.is_some():
        print(f'Hello {user.unwrap()}')
    else:
        print('id not found')
        
```


Now, at this point it really doesn't add too much. But if you allow the following state to 
exist in your `DB`.

```python
D  = {
    1: 'john',
    2: 'jane',
    3: None
}
```
Then things, get tricky for the first implementation. 
***How do you distinguish between the DB value `None` and the state of element not found?***

A possible solution would be:

```python

DB = {
    1: 'john', 
    2: 'jane',
}

def get_user_by_id_old(user_id: int) -> str | None:
    return DB[user_id] # this will raise a KeyError if user_id is not part of DB

def main():
    try:
        user = get_user_by_id_old(1)
    except KeyError:
        print('user not found') 
        return # cut control flow here
    
    if user is not None:
        print(f'Hello {user}')
    else:
        print(f'User gone')
```

Which is not ideal as the KeyError exception is not visible throw the type hint system, which puts the 
pleasure of correctly handling this behavior on the invoker.

As opposed to this implementation:

```python
from toradh import Optional, Option, Nothing, Some

DB = {
    1: 'john', 
    2: 'jane',
    3: None
}

def get_user_by_id_new(user_id: int) -> Optional[str | None]:
    if user_id not in DB:
        return Nothing()
    
    return Some(DB.get(user_id))
    
def main():
    user = get_user_by_id_new(1)
    
    match user:
        case Nothing():
            print('id not found')    
        case Some(None):
            print('User is gone')
        case Some(name):
            print(f'Hello {name}')
        
```

In this example (although not really a good use of `None`) we can see that there is a clear distinction between the absence of what 
we want and an actual product of calling the function.

## Pydantic v2 compatibility

You can use `Option`, `Some`, `Nothing`, `Ok`, and `Err` as field types in Pydantic v2 models. Serialization works as follows:

- `Nothing()` serializes to `None`
- `Some(value)` serializes to the inner value
- `Ok(value)` serializes to the inner value
- `Err(error)` serializes to `None` (no payload)

Example:

```python
from pydantic import BaseModel
from toradh import Option, Some, Nothing, Ok, Err, Result

class Inner(BaseModel):
    x: int

class MyModel(BaseModel):
    opt: Option[int]
    ok: Ok[Inner]
    res: Result[int, Exception]

m = MyModel(opt=Some(1), ok=Ok(Inner(x=5)), res=Ok(10))
assert m.model_dump() == {"opt": 1, "ok": {"x": 5}, "res": 10}

# Accepts bare values and wraps them appropriately
m2 = MyModel(opt=None, ok={"x": 7}, res=5)
assert isinstance(m2.opt, Nothing)
assert m2.model_dump() == {"opt": None, "ok": {"x": 7}, "res": 5}

# Err serializes to None
m3 = MyModel(opt=Nothing(), ok=Ok(Inner(x=1)), res=Err(RuntimeError("boom")))
assert m3.model_dump() == {"opt": None, "ok": {"x": 1}, "res": None}
```

See `examples/pydantic_compat.py` for a runnable demonstration.