How to handle exceptions with Returns instead of try/except?

Use the Result container with @safe decorators to convert exceptions into returned Failure values, enabling Railway Oriented Programming. For example, wrap HTTP requests in safe functions to avoid raising exceptions.

Returns vs. PyMonad for functional programming in Python?

Returns offers more comprehensive type safety with mypy integration and containers like IO and Future for side effects, while PyMonad is lighter but lacks built-in async support. Returns is better for teams prioritizing robust, typed error handling.

Is Returns good for Django projects?

Yes, especially for dependency injection with RequiresContext to manage configurable logic without coupling to django.settings. However, it requires refactoring views to use containers, which may be a significant change.

How to use Returns with async/await code?

Use the Future and FutureResult containers to handle async operations in a sync-like manner, preventing exceptions from breaking event loops. Decorate coroutines with @future_safe and compose them using bind for safe error handling.

Does Returns slow down my Python code?

There's some performance overhead due to abstraction layers in monadic containers, but it's minimal for most applications. The trade-off is improved safety and maintainability, though performance-critical code might need profiling.

Can I use Returns without mypy?

Technically yes, but you lose the type safety guarantees that are core to the library. The mypy plugin is recommended to catch errors early, and without it, many benefits like emulated Higher Kinded Types are diminished.

returns — Python Functional Returns Library

What is returns?

Returns is a Python library that introduces functional programming patterns through monadic containers to make function returns typed, safe, and meaningful. It solves problems like null references, exception handling, and impure code by providing containers like Maybe, Result, IO, and Future, enabling developers to write declarative and error-resistant business logic.

Target Audience

Python developers building maintainable applications who want to adopt functional programming principles, improve type safety, eliminate exceptions, and separate pure from impure code. It's especially useful for teams focusing on robust architecture and predictable error handling.

Value Proposition

Developers choose Returns because it offers a comprehensive, type-safe way to handle side effects, errors, and null values without exceptions, leading to more readable and composable code. Its integration with `mypy` and support for Higher Kinded Types provide strong guarantees that are rare in Python ecosystems.

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

Use Cases

Best For

Eliminating None values and null-related errors in Python codebases
Replacing exception-based error handling with Railway Oriented Programming
Implementing typed functional dependency injection in Django or other frameworks
Writing async code with safe error handling and better composition
Separating pure business logic from impure I/O operations
Building declarative and type-safe pipelines for complex business workflows

Not Ideal For

Projects with tight deadlines or rapid prototyping where the overhead of learning functional patterns and refactoring code is prohibitive
Codebases deeply integrated with libraries that rely on traditional exception handling (e.g., many web frameworks' error middleware)
Small scripts or one-off tasks where the added complexity of monadic containers and type safety provides little benefit
Teams not using type hints or static type checking (mypy), as Returns' safety guarantees depend heavily on these

Pros & Cons

Pros

Eliminates Null Errors

The Maybe container replaces None with Some and Nothing types, preventing null-related errors entirely, as shown in the README's refactored example that avoids nested if checks for None values.

Full Type Safety

Integrates seamlessly with mypy and PEP561 for rigorous type checking, including emulated Higher Kinded Types, ensuring compile-time safety for complex functional patterns.

Functional Dependency Injection

The RequiresContext container enables typed, explicit dependency injection without cluttering function signatures, demonstrated in the Django example for configurable game logic.

Separates Pure and Impure Code

IO and IOResult containers clearly mark impure operations (like I/O), enforcing better architecture and testability, as illustrated in the refactored HTTP request example.

Cons

Complex Setup Requirements

Requires configuring a custom mypy plugin and specific type-checker settings, which adds initial overhead and may conflict with existing tooling in some projects.

Verbose Code Style

Adopting monadic containers often leads to more verbose code compared to Python's idiomatic exception handling or optional types, potentially reducing readability for teams unfamiliar with FP.

Ecosystem Friction

Integrating with third-party libraries that expect exceptions or None values requires additional wrapping layers, increasing boilerplate and maintenance effort.

What is returns?

Target Audience

Value Proposition

Use Cases

Best For

Eliminating None values and null-related errors in Python codebases
Replacing exception-based error handling with Railway Oriented Programming
Implementing typed functional dependency injection in Django or other frameworks
Writing async code with safe error handling and better composition
Separating pure business logic from impure I/O operations
Building declarative and type-safe pipelines for complex business workflows

Not Ideal For

Projects with tight deadlines or rapid prototyping where the overhead of learning functional patterns and refactoring code is prohibitive
Codebases deeply integrated with libraries that rely on traditional exception handling (e.g., many web frameworks' error middleware)
Small scripts or one-off tasks where the added complexity of monadic containers and type safety provides little benefit
Teams not using type hints or static type checking (mypy), as Returns' safety guarantees depend heavily on these

Pros & Cons

Pros

Eliminates Null Errors

The Maybe container replaces None with Some and Nothing types, preventing null-related errors entirely, as shown in the README's refactored example that avoids nested if checks for None values.

Full Type Safety

Integrates seamlessly with mypy and PEP561 for rigorous type checking, including emulated Higher Kinded Types, ensuring compile-time safety for complex functional patterns.

Functional Dependency Injection

The RequiresContext container enables typed, explicit dependency injection without cluttering function signatures, demonstrated in the Django example for configurable game logic.

Separates Pure and Impure Code

IO and IOResult containers clearly mark impure operations (like I/O), enforcing better architecture and testability, as illustrated in the refactored HTTP request example.

Cons

Complex Setup Requirements

Requires configuring a custom mypy plugin and specific type-checker settings, which adds initial overhead and may conflict with existing tooling in some projects.

Verbose Code Style

Adopting monadic containers often leads to more verbose code compared to Python's idiomatic exception handling or optional types, potentially reducing readability for teams unfamiliar with FP.

Ecosystem Friction

Integrating with third-party libraries that expect exceptions or None values requires additional wrapping layers, increasing boilerplate and maintenance effort.

returns

What is returns?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Found a gem we're missing?

returns

What is returns?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Found a gem we're missing?