django-returns

Meaningful Django utils based on Functional Programming.

Made possible by returns

Install

pip install django-returns

What

django-returns is a tiny layer on top of Django’s ORM that lets you opt into returns containers when you want explicit success/failure return types instead of exceptions.

Why

To bring the benefits of Functional Programming to the Django world.

• Improved predictability, understandability, maintainability.
• Safer code with type checking.
• Better error handling.

How

By subclassing QuerySet and applying returns decorators to its methods.

Note: the default ReturnsManager does not change Django semantics. It keeps the original methods intact and adds new ones:

• *_result variants for sync operations (return Success / Failure)
• *_ioresult variants for both sync and async operations (return IOSuccess / IOFailure)
• first_maybe() / last_maybe() for "might be None" QS methods (return Some / Nothing)

Safe ORM

Enable it by using the provided base model.

from django_returns.models import ReturnsModel


class Person(ReturnsModel):
    name = models.CharField(max_length=255, unique=True)

Or by using the custom Manager.

from django_returns.managers import ReturnsManager


class Person(models.Model):
    objects = ReturnsManager()

Basic Usage

Methods with the _result suffix return returns.result.Result.

from returns.result import Failure, Result, Success


def get_person_name(person_id):
    result: Result = Person.objects.get_result(id=person_id)

    match result:
        case Success(person):
            return Success(person.name)
        case Failure(Person.DoesNotExist()):
            return ""

IO Methods

Async/IO *_ioresult methods return an IO-wrapped result (IOSuccess / IOFailure).

from returns.io import unsafe_perform_io
from returns.result import Failure, Success


async def get_person_id_async(name):
    io_result = await Person.objects.aget_ioresult(name=name)
    result = unsafe_perform_io(io_result)

    match result:
        case Success(person):
            return person.id
        case Failure(error):
            return -1