Returns

---

---

Make your functions return something meaningful, typed, and safe!

Features

• Brings functional programming to Python land
• Provides a bunch of primitives to write declarative business logic
• Enforces better architecture
• Fully typed with annotations and checked with mypy, PEP561 compatible
• Adds emulated Higher Kinded Types support
• Provides type-safe interfaces to create your own data-types with enforced laws
• Has a bunch of helpers for better composition
• Pythonic and pleasant to write and to read 🐍
• Supports functions and coroutines, framework agnostic
• Easy to start: has lots of docs, tests, and tutorials

Quickstart right now!

Installation

pip install returns

You can also install returns with the latest supported mypy version:

pip install returns[compatible-mypy]

You would also need to configure our mypy plugin:

# In setup.cfg or mypy.ini:
[mypy]
plugins =
  returns.contrib.mypy.returns_plugin

or:

[tool.mypy]
plugins = ["returns.contrib.mypy.returns_plugin"]

We also recommend to use the same mypy settings we use, which you'll find in the [tool.mypy] sections in our pyproject.toml file.

Make sure you know how to get started, check out our docs! Try our demo.

Contents

• Maybe container that allows you to write None-free code
• RequiresContext container that allows you to use typed functional dependency injection
• Result container that lets you to get rid of exceptions
• IO container and IOResult that marks all impure operations and structures them
• Future container and FutureResult to work with async code
• Write your own container! You would still have all the features for your own types (including full existing code reuse and type-safety)
• Use do-notation to make your code easier!

Maybe container

None is called the worst mistake in the history of Computer Science.

So, what can we do to check for None in our programs? You can use builtin Optional type and write a lot of if some is not None: conditions. But, having null checks here and there makes your code unreadable.

user: Optional[User]
discount_program: Optional['DiscountProgram'] = None

if user is not None:
     balance = user.get_balance()
     if balance is not None:
         credit = balance.credit_amount()
         if credit is not None and credit > 0:
             discount_program = choose_discount(credit)

Or you can use Maybe container! It consists of Some and Nothing types, representing existing state and empty (instead of None) state respectively.

from typing import Optional
from returns.maybe import Maybe, maybe

@maybe  # decorator to convert existing Optional[int] to Maybe[int]
def bad_function() -> Optional[int]:
    ...

maybe_number: Maybe[float] = bad_function().bind_optional(
    lambda number: number / 2,
)
# => Maybe will return Some[float] only if there's a non-None value
#    Otherwise, will return Nothing

You can be sure that .bind_optional() method won't be called for Nothing. Forget about None-related errors forever!

We can also bind a Optional-returning function over a container. To achieve this, we are going to use .bind_optional method.

And here's how your initial refactored code will look:

user: Optional[User]

# Type hint here is optional, it only helps the reader here:
discount_program: Maybe['DiscountProgram'] = Maybe.from_optional(
    user,
).bind_optional(  # This won't be called if `user is None`
    lambda real_user: real_user.get_balance(),
).bind_optional(  # This won't be called if `real_user.get_balance()` is None
    lambda balance: balance.credit_amount(),
).bind_optional(  # And so on!
    lambda credit: choose_discount(credit) if credit > 0 else None,
)

Much better, isn't it?

RequiresContext container

Many developers do use some kind of dependency injection in Python. And usually it is based on the idea that there's some kind of a container and assembly process.

Functional approach is much simpler!

Imagine that you have a django based game, where you award users with points for each guessed letter in a word (unguessed letters are marked as '.'):

from django.http import HttpRequest, HttpResponse
from words_app.logic import calculate_points

def view(request: HttpRequest) -> HttpResponse:
    user_word: str = request.POST['word']  # just an example
    points = calculate_points(user_word)
    ...  # later you show the result to user somehow

# Somewhere in your `words_app/logic.py`:

def calculate_points(word: str) -> int:
    guessed_letters_count = len([letter for letter in word if letter != '.'])
    return _award_points_for_letters(guessed_letters_count)

def _award_points_for_letters(guessed: int) -> int:
    return 0 if guessed < 5 else guessed  # minimum 6 points possible!

Awesome! It works, users are happy, your logic is pure and awesome. But, later you decide to make the game more fun: let's make the minimal accountable letters threshold configurable for an extra challenge.

You can just do it directly:

def _award_points_for_letters(guessed: int, threshold: int) -> int:
    return 0 if guessed < threshold else guessed

The problem is that _award_points_for_letters is deeply nested. And then you have to pass threshold through the whole callstack, including calculate_points and all other functions that might be on the way. All of them will have to accept threshold as a parameter! This is not useful at all! Large code bases will struggle a lot from this change.

Ok, you can directly use django.settings (or similar) in your _award_points_for_letters function. And ruin your pure logic with framework specific details. That's ugly!

Or you can use RequiresContext container. Let's see how our code changes:

from django.conf import settings
from django.http import HttpRequest, HttpResponse
from words_app.logic import calculate_points

def view(request: HttpRequest) -> HttpResponse:
    user_word: str = request.POST['word']  # just an example
    points = calculate_points(user_word)(settings)  # passing the dependencies
    ...  # later you show the result to user somehow

# Somewhere in your `words_app/logic.py`:

from typing import Protocol
from returns.context import RequiresContext

class _Deps(Protocol):  # we rely on abstractions, not direct values or types
    WORD_THRESHOLD: int

def calculate_points(word: str) -> RequiresContext[int, _Deps]:
    guessed_letters_count = len([letter for letter in word if letter != '.'])
    return _award_points_for_letters(guessed_letters_count)

def _award_points_for_letters(guessed: int) -> RequiresContext[int, _Deps]:
    return RequiresContext(
        lambda deps: 0 if guessed < deps.WORD_THRESHOLD else guessed,
    )

And now you can pass your dependencies in a really direct and explicit way. And have the type-safety to check what you pass to cover your back. Check out RequiresContext docs for more. There you will learn how to make '.' also configurable.

We also have RequiresContextResult for context-related operations that might fail. And also RequiresContextIOResult and RequiresContextFutureResult.

Result container

Please, make sure that you are also aware of Railway Oriented Programming.

Straight-forward approach

Consider this code that you can find in any python project.

import requests

def fetch_user_profile(user_id: int) -> 'UserProfile':
    """Fetch