returns is a Python library that brings functional programming patterns and type-safe return types to Python development.
The library addresses the problem of functions returning ambiguous or unsafe values by implementing railway-oriented programming and functional composition patterns. It provides container types like Result, Maybe, and IO that encode success and failure states directly in return values, eliminating the need for exceptions or None checks. This approach makes error handling explicit and composable, allowing developers to chain operations safely and let failures propagate through the pipeline without intermediate error handling at each step.
Developers considering adoption should know that returns is designed for teams prioritizing type safety and functional programming practices in Python. It works well in codebases where explicit error handling and predictable function behavior matter more than brevity. The library integrates with mypy through custom plugins and stubs, enabling static type checking of container operations. It suits projects building APIs, data processing pipelines, or business logic where distinguishing between success and failure states is central to correctness. The library is particularly valuable when working with teams that value railway-oriented programming as a design pattern.
The project maintains active engagement with its codebase through regular updates and refinements to its type system integration. Development includes ongoing work to improve mypy plugin compatibility and expand the functional programming abstractions available to users. The maintainers actively address issues and incorporate feedback from the functional programming community. Documentation receives consistent attention, with the project maintaining comprehensive guides and examples for users learning the patterns. The project demonstrates sustained commitment to both the core library functionality and the ecosystem of tools that support type-safe functional Python development.
