Quickstart

Starting is really fast! You can integrate returns into any project at any stage. You can use it fully or partially. With or without types.

returns is a very flexible library!

You can even just start using it without any deep theory around this project. But, you can always address our learning materials which will unravel all parts of functional programming with useful examples and simple terms.

Why

One of the most frequent questions Python developers ask: why would we need this?

Basically, the answer is that returns provides useful abstractions that solve some problems every developer has:

1. Maybe helps to work with None in a type-safe way

2. Result helps to work with exceptions in a type-safe way

3. IO helps to separate pure code from impure code to make your architecture better

4. Future helps to write await free code

5. RequiresContext helps to inject dependencies in a very readable, explicit, type-safe, and clean way

6. Pipelines can be used independently or together with the types above to create complex, declarative, and type-safe data pipelines

On top of that we provide useful interfaces that allows you to switch implementation on the fly. For example, you can write code that works the same way for sync and async execution flows. While being fully type-safe at the same time.

And you can write your own primitives that will solve any other problem you can possible have based on our existing or your custom interfaces.

In other words, returns unlocks insane powers of typed-functional programming to a regular Python developer.

Installation

returns is a pure Python library. Install it as usual:

pip install returns  # or better use poetry

Typechecking and other integrations

This step is optional. If you use mypy for type-checking, than you will need to configure it. We really recommend using mypy with this project though. Because we have put a lot of efforts into the typing part.

Check out our docs on mypy.

We also have built-in integrations with pytest and hypothesis. Also, there is developer tooling you might enjoy.

Theory

Do you want to learn new awesome concepts? Then, start reading our “Userguide”!

It has everything you need! Reading order matters.

However, this is optional. You can still use returns without a deep-dive into theory.

Building your own stuff

You can extend returns and build your own stuff! Particularly, you can add new interfaces, new containers, and new integrations. See this guide.

Join our chat to get help or advice.