paraboloski-monad 1.0.0

Result monad for Python using Ok, Err and safe decorators

paraboloski-monad

An error handling decorator for Python that leverages the monadic design pattern. It represents operations that run on two parallel tracks: they can either succeed (Ok) or fail (Err), without raising exceptions.

---

Installation

PyPI

uv add paraboloski-monad
pip install paraboloski-monad

GitHub

uv add git+https://github.com/paraboloski/snippet-toolbox/python#subdirectory=snippet/monad

When to use it

Ideal for operations that can fail predictably: HTTP calls, data parsing, filesystem access, database queries. Instead of scattering try/except blocks throughout your code, failure becomes an explicit part of the return type.

Usage

from monad import Ok, Err, monad, safe, safe_async

@safe
def parse_user(data: dict) -> User:
    return User(
        id=data["id"],
        name=data["name"],
        email=data["email"],
    )

@safe_async
async def fetch_user(user_id: int) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(f"/api/users/{user_id}") as response:
            return await response.json()

Handle results with match

match parse_user(data):
    case Ok(user):
        print(f"Welcome, {user.name}")
    case Err(error):
        print(f"Invalid user data: {error}")

Operation pipelines

Failures propagate automatically without nested try/except blocks:

@safe
def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

@safe
def parse_json(content: str) -> dict:
    return json.loads(content)

@safe
def parse_user(data: dict) -> User:
    if "name" not in data:
        raise ValueError("missing 'name' field")
    return User(**data)

match read_file("user.json"):
    case Ok(content):
        match parse_json(content):
            case Ok(data):
                match parse_user(data):
                    case Ok(user):
                        print(f"Hello, {user.name}")
                    case Err(e):
                        print(f"Invalid user: {e}")
            case Err(e):
                print(f"Malformed JSON: {e}")
    case Err(e):
        print(f"File not found: {e}")

Or provide a default value with unwrap_or

When failure is acceptable and you want a fallback value:

user = parse_user(data).unwrap_or(
    User(id=0, name="anonymous", email="")
)

users = (await fetch_user(user_id)).unwrap_or([])

---

Italiano

Un decoratore per l'error handling per Python che sfrutta il design pattern monadico. Rappresenta operazioni che seguono due binari paralleli: possono avere successo (Ok) o fallire (Err), senza sollevare eccezioni.

Installazione

PyPI

uv add paraboloski-monad
pip install paraboloski-monad

GitHub

uv add git+https://github.com/paraboloski/snippet-toolbox/python#subdirectory=snippet/monad

Quando usarla

Ideale per operazioni che possono fallire in modo prevedibile: chiamate HTTP, parsing di dati, accesso al filesystem, query a database. Invece di disseminare try/except nel codice, il fallimento diventa parte esplicita del tipo di ritorno.

Utilizzo

from monad import Ok, Err, monad, safe, safe_async

@safe
def parse_user(data: dict) -> User:
    return User(
        id=data["id"],
        name=data["name"],
        email=data["email"],
    )

@safe_async
async def fetch_user(user_id: int) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(f"/api/users/{user_id}") as response:
            return await response.json()

Gestisci il risultato con match

match parse_user(data):
    case Ok(user):
        print(f"Benvenuto, {user.name}")
    case Err(error):
        print(f"Dati utente non validi: {error}")

Pipeline di operazioni

Il fallimento si propaga automaticamente senza blocchi try/except annidati:

@safe
def read_file(path: str) -> str:
    with open(path) as f:
        return f.read()

@safe
def parse_json(content: str) -> dict:
    return json.loads(content)

@safe
def parse_user(data: dict) -> User:
    if "name" not in data:
        raise ValueError("campo 'name' mancante")
    return User(**data)

match read_file("user.json"):
    case Ok(content):
        match parse_json(content):
            case Ok(data):
                match parse_user(data):
                    case Ok(user):
                        print(f"Ciao, {user.name}")
                    case Err(e):
                        print(f"Utente non valido: {e}")
            case Err(e):
                print(f"JSON malformato: {e}")
    case Err(e):
        print(f"File non trovato: {e}")

Oppure fornisci un valore di default con unwrap_or

Quando il fallimento è accettabile e hai un valore di fallback:

user = parse_user(data).unwrap_or(
    User(id=0, name="anonimo", email="")
)

users = (await fetch_user(user_id)).unwrap_or([])