instructor/docs/maybe.md

Error Handling Using Maybe Pattern

Introduction

The Maybe pattern is a functional programming concept used for error handling. Instead of raising exceptions or returning None, you can use a Maybe type to encapsulate both the result and possible errors.

Define Models with Pydantic

Using Pydantic, define the UserDetail and MaybeUser classes.

from pydantic import BaseModel, Field, Optional

class UserDetail(BaseModel):
    age: int
    name: str
    role: Optional[str] = Field(default=None)

class MaybeUser(BaseModel):
    result: Optional[UserDetail] = Field(default=None)
    error: bool = Field(default=False)
    message: Optional[str] = Field(default=None)

    def __bool__(self):
        return self.result is not None

Implementing Maybe Pattern with instructor

You can use instructor to generalize the Maybe pattern.

import instructor

MaybeUser = instructor.Maybe(UserDetail)

Function Example: get_user_detail

Here's a function example that returns a MaybeUser instance. The function simulates an API call to get user details.

from typing import Optional
import random

def get_user_detail(string: str) -> MaybeUser:
    ...
    return

# Example usage
user1 = get_user_detail("Jason is a 25 years old scientist")
{
  "result": {
    "age": 25,
    "name": "Jason",
    "role": "scientist"
  },
  "error": false,
  "message": null
}


user2 = get_user_detail("Unknown user")
{
  "result": null,
  "error": true,
  "message": "User not found"
}

Conclusion

The Maybe pattern enables a more structured approach to error handling. This example illustrated its implementation using Python and Pydantic.