Getting Started¶

Prerequisites¶

django-returns is tested on Python 3.10+ and Django 4.2+

Install¶

pip install django-returns

Safe ORM¶

There are currently two options for using the safe ORM methods.

Using ReturnsManager
Using ReturnsModel

Note that the second option comes with more functionality.

`ReturnsManager`¶

Includes queryset.*_result and queryset.*_ioresult methods for unsafe methods, which are defined as follows.

    UNSAFE_METHODS = [
        "get",
        "earliest",
        "latest",
        "create",
        "get_or_create",
        "update_or_create",
        "delete",
        "bulk_create",
    ]

Example:

from datetime import date

from django.db import models
from django_returns.managers import ReturnsManager
from returns.result import Success


class Person(models.Model):
    name = models.CharField(max_length=100, unique=True)
    dob = models.DateField()

    objects = ReturnsManager()


result = Person.objects.create_result(name="test", dob=date(2020, 1, 1))
assert isinstance(result, Success)

`ReturnsModel`¶

Includes queryset.*_result and queryset.*_ioresult methods plus model.*_result methods for save, delete etc.

Example:

from datetime import date

from django.db import models
from django_returns.models import ReturnsModel
from returns.result import Success


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


creation_result = Person.objects.create_result(name="test", dob=date(2020, 1, 1))
person = creation_result.unwrap()
deletion_result = person.delete_result()
assert isinstance(deletion_result, Success)

Recap¶

Compared to standard Django ORM, django-returns classes:

Keep the existing Django ORM behavior.
Adds new methods with suffixes:
- *_result for sync operations
- *_ioresult for sync + async operations
- first_maybe() / last_maybe() for optional results