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.
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():
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():
res = create_user('janet')
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')
def no_handling():
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
DB = {
1: 'john',
2: 'jane',
}
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
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
.
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:
DB = {
1: 'john',
2: 'jane',
}
def get_user_by_id_old(user_id: int) -> str | None:
return DB[user_id]
def main():
try:
user = get_user_by_id_old(1)
except KeyError:
print('user not found')
return
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:
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.