returns

What it is and what it does

Returns is a functional programming library that replaces common error-handling patterns (None checks, exceptions) with composable container types. It provides Maybe (for optional values), Result (for operations that may fail), RequiresContext (for dependency injection), and IO/Future variants for side effects and async code. All containers are fully typed and checked with mypy, supporting higher-kinded types and enforcing laws through its type system.

The library is designed to make business logic more declarative and testable by encoding control flow into the type system itself. Instead of scattering None checks or try-catch blocks throughout your code, you chain operations using methods like bind, map, and bind_optional, which short-circuit automatically on failure or absence. It works with both sync and async functions and is framework-agnostic.

Use it for:

• Replace nested None checks with Maybe.from_optional and chained bind_optional calls for cleaner, more readable pipelines.
• Handle operations that may fail (database queries, API calls) using Result to avoid exception-based control flow.
• Implement typed functional dependency injection with RequiresContext to pass configuration through call stacks without polluting function signatures.
• Structure async code with Future and FutureResult to compose coroutines and handle errors uniformly.
• Write declarative business logic that is easier to test, reason about, and refactor because control flow is explicit in the type system.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides functional programming primitives—containers like Maybe, Result, and RequiresContext—that let you write type-safe, composable functions that return meaningful values instead of raising exceptions or returning None.

Yes. Returns is actively maintained, has no known vulnerabilities, minimal dependencies, and solves a real problem—making error handling and composition more explicit and type-safe. It is worth installing if you value functional programming patterns, mypy integration, and reducing None/exception-related bugs. The learning curve is moderate; start with Maybe and Result before exploring advanced features.

Install

returns on PyPI

pip install returns

uv add returns

poetry add returns

Installing returns

Before you install

Low friction: pure Python wheel with only typing-extensions as a runtime dependency. Actively maintained with a release 12 days ago. Supports Python 3.11–3.14.

License in practice

BSD-3-Clause is permissive; you can use this in commercial and proprietary projects with minimal restrictions, provided you include the license text.

Quickstart

pip install returns

from returns.maybe import Maybe

maybe_value: Maybe[int] = Maybe.from_optional(some_optional)
result = maybe_value.bind_optional(lambda x: x / 2)

Requires Python 3.11 or later; mypy plugin configuration recommended for full type-safety but not strictly required to run.

Verify before relying

• Whether the mypy plugin integration is required for full type-checking benefits or optional
• Performance overhead of container wrapping compared to direct exception handling in hot paths
• Compatibility with popular async frameworks beyond the documented Future and FutureResult containers

Package facts

Evidence: returns-0.29.0-py3-none-any.whl

Keywords: functional programming, fp, monads, monad, monad transformers, composition, type-safety, mypy, railway-oriented-programming

Tags

More Python Modules packages