--- id: returns version: "0.29.0" license: BSD-3-Clause license_treatment: permissive maintenance: active --- # returns — Make your functions return something meaningful, typed, and safe! License: permissive · Maintenance: active · Downloads: 1.2M/mo ## 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 above — 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 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 - License: BSD-3-Clause (permissive) - Python support: supports_current - Install friction: low - Maintenance: active - Downloads: 1.2M/month (top 5,000 on PyPI) - Known vulnerabilities: none known ## Tags functional programming python, monad containers type-safe, result maybe error handling, railway-oriented programming, typed composition helpers, dependency injection functional, exception-free return types, functional-programming, type-safety, monad-containers [View on SkillFed](https://skillfed.io/packages/returns) · [View on PyPI](https://pypi.org/project/returns/)