Open-source project
dry-python/returns avatar
dry-python/returns

returns and the mypy plugin behind its typed containers

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

4,386 stars160 forksPythonBSD-2-Clause

At a glance

What is it?
A look at how dry-python/returns turns Optional, exceptions and I/O into typed containers, and where the cost lands: a mypy plugin, a Python 3.11 floor, and a rewrite of your call signatures.
Who is it for?
Adopt returns on a typed service where Optional values and bare exceptions already spread through the signatures and the team runs mypy in CI, since the containers only pay off when a checker reads them. Do not adopt it to patch a single null check, on a codebase that skips type checking, or in a library whose public API you cannot change, because every call site has to change with the return type.
Can I use it commercially?
Yes. BSD-2-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • dry-python/returns4,386 ★ · +20
Star history
Repository2026-09-232026-11-15
dry-python/returns4.4k4.4k

20 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem is untyped failure, not untyped data

returns exists because Python lets a function's return type lie quietly. A function annotated to return a user can hand back None at runtime and mypy will not stop the caller from calling get_balance on it. The library's answer is to move failure into the type: a container carries either a success value or an empty state, and the only operations on it are the ones that handle both cases. That framing matters for the reader deciding whether to adopt, because it is not a lint rule and not a runtime check. Nothing about returns inspects your code and warns you; it changes the signatures your code has to write, and the payoff arrives only when a type checker reads them. The audience is engineers already running mypy on a service with layered business logic. Teams adding returns to an untyped script get containers they never inspect.

Maybe.from_optional replaces the nested None ladder

The README opens with the shape of the problem: a user, a balance, a credit amount and a discount program, each Optional, each guarded by its own if. That is three levels of nesting to express a rule that can fail. Maybe holds Some and Nothing, and bind_optional takes a function that may itself return None and will not be invoked for Nothing. The refactored form in the README reads as one leftward chain, with each comment marking the None check that used to be an explicit branch. The @maybe decorator does the conversion at the boundary, turning an existing Optional[int] annotation into Maybe[int] so that legacy code can be wrapped rather than rewritten:

python
from returns.maybe import Maybe, maybe

@maybe
def bad_function() -> Optional[int]: ...

maybe_number: Maybe[float] = bad_function().bind_optional(
    lambda number: number / 2,
)

You should see Some only when a non-None value arrived, and Nothing otherwise. Nothing forces you to convert the whole codebase on day one. It does force every call site that touches the value to change, which is where the migration cost actually sits.

RequiresContext threads dependencies without threading arguments

The second failure returns targets is parameter plumbing. The README's words game example has calculate_points calling _award_points_for_letters, and adding a configurable threshold forces threshold through calculate_points and everything between it and the view. RequiresContext is the container for that: it holds a value that produces a wrapped return, and dependencies are supplied by reading from the container rather than by adding parameters to every function on the path. The claimed audience is anyone doing dependency injection without a container and an assembly step, which is most Python web code. The trade-off is that the dependency is no longer visible in the signature. A reader scanning a function list cannot see that _award_points_for_letters reads a threshold, and IDE go-to-definition now lands on a wrapper. If your team relies on signatures to document data flow, that is a genuine loss, not a rounding error.

Result, IO and IOResult make the impure edges explicit

Result replaces raise and try with a return value, so failure is composed with map and bind rather than caught. IO is the same shape wrapped around an impure operation, and IOResult combines both, which is the container aimed at boundary code that can fail. Each is a value, so a chain of them is a plain expression and an intermediate failure short-circuits the rest without a flag telling the reader to check. Future and FutureResult do the same for coroutines, which is the part that makes the library usable under asyncio rather than only under synchronous code. The cost is layering. A function returning Result cannot be called directly by a caller expecting a bare value, and the conversion has to happen at every module that crosses the boundary. Teams that already isolate I/O behind a thin service layer get less from IO than from Result.

Installing returns means wiring a mypy plugin

Installation is one command. The part that takes real work is the type checker configuration, because the containers only pay off when mypy reads them correctly. The project ships an extras group named compatible-mypy, and a plugin entry point that must be registered by hand in setup.cfg, mypy.ini or pyproject.toml.

bash
pip install returns[compatible-mypy]

Then register the plugin:

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

The compatible-mypy extra installs returns with the latest supported mypy version, and the plugin still has to be configured separately. Note the runtime floor in pyproject.toml, python = "^3.11", with typing-extensions pinned to >=4.0,<5.0 and the package itself at version 0.30.0.

The laws are enforced by a pytest plugin and Hypothesis

return claims you can write your own container with enforced laws, and the mechanism is the check-laws extras group rather than anything in the runtime package. pyproject.toml wires two plugin entry points: a Hypothesis hook, returns.contrib.hypothesis._entrypoint:_setup_hook, and a pytest plugin registered as returns. Before you vendor it, note a mismatch in the repository itself: the project metadata reports BSD-2-Clause while pyproject.toml declares license = "BSD-3-Clause" in its tool.poetry table, and the two differ in the endorsement clause. The catch is that law checking is opt-in. Nothing runs the law checks in a plain pytest run unless the extras are installed, so a project that skips them has a custom container with documentation in the place of a guarantee. The repository carries a typesafety directory alongside tests and benchmarks, and the mypy constraints (>=1.19,<2.5) are tight enough that a major mypy bump is a real upgrade event.

Railway-oriented alternatives differ on who owns the error path

The usual comparison is with other functional libraries, but the sharper difference is architectural. approaches such as result and its successors let a function return Either and leave composition to the caller, so each error case is handled at the point it is needed. returns goes further: it ships IO and IOResult as first-class containers, ships FutureResult for async, and ties all of it to a specific mypy plugin. The benefit of that bundle is that the purity boundary becomes a type you can search for. The cost is the dependency: adopting returns means adopting its plugin, its extras and its Python floor as one unit.

Editorial conclusion

Adopt returns on a typed service where Optional values and bare exceptions already spread through the signatures and the team runs mypy in CI, since the containers only pay off when a checker reads them. Do not adopt it to patch a single null check, on a codebase that skips type checking, or in a library whose public API you cannot change, because every call site has to change with the return type. Verify first that returns.contrib.mypy.returns_plugin loads in your mypy configuration and that the python = "^3.11" constraint in pyproject.toml matches your runtime.

Frequently asked questions

What is the returns library for Python?

It provides typed containers such as Maybe, Result, IO and IOResult so that None, exceptions and impure calls appear in the type signature instead of being discovered at runtime. Composition happens through map and bind over those containers.

How do I install returns with mypy support?

Install the extras group and register the plugin by hand. pip install returns[compatible-mypy] pulls a supported mypy version, and the returns_plugin entry point must be added to the plugins setting in setup.cfg, mypy.ini or pyproject.toml. Without that line the containers import and run, but the checker support does not.

Does returns work with async code?

Yes, through the Future and FutureResult containers, which apply the same composition to coroutines. The project also states that it supports both functions and coroutines and is framework agnostic.

What Python version does returns require?

pyproject.toml declares python = "^3.11". It also pins typing-extensions to >=4.0,<5.0, so an application locked to an older interpreter is not a supported target.

Can I write my own container with returns?

The project documents creating your own container while keeping type-safety and code reuse. Law checking depends on the check-laws extras group, which installs pytest and hypothesis, and on the plugin entry points declared in pyproject.toml.

Official sources

  1. dry-python/returns on GitHub
  2. License: BSD-2-Clause
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/dry-python-returns.svg)](https://hysenlabs.com/projects/dry-python-returns)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/dry-python-returns.svg)](https://hysenlabs.com/projects/dry-python-returns)

Was this useful?