returns

Instead of using try/except blocks to handle exceptions, you can use the @safe decorator. This decorator wraps the return value of a function in a Result container, which will be either a Success[YourType] or a Failure[Exception]. This prevents functions from throwing unexpected exceptions and allows for declarative error handling using flow and bind.

import requests
from returns.result import Result, safe
from returns.pipeline import flow
from returns.pointfree import bind


def fetch_user_profile(user_id: int) -> Result['UserProfile', Exception]:
    """Fetches `UserProfile` TypedDict from foreign API."""
    return flow(
        user_id,
        _make_request,
        bind(_parse_json),
    )


@safe
def _make_request(user_id: int) -> requests.Response:
    # This will return Success[Response] or Failure[Exception]
    response = requests.get('/api/users/{0}'.format(user_id))
    response.raise_for_status()
    return response


@safe
def _parse_json(response: requests.Response) -> 'UserProfile':
    # This will return Success[UserProfile] or Failure[Exception]
    return response.json()

To create a custom container in returns, follow these steps:

1. Choose Interfaces: Decide which capabilities your container needs. You can subtype specific interfaces like MappableN, BindableN, AltableN, LashableN, or Equable. You can also use pre-defined aliases like BiMappableN or SwappableN to combine multiple interfaces.
2. Implement BaseContainer: It is highly recommended to inherit from returns.primitives.container.BaseContainer to gain features like immutability, cloning, serialization, and comparison.
3. Implement Methods: You must implement all abstract methods required by the interfaces you subtype (e.g., map, bind, lash, alt, swap) to satisfy mypy type checking.
4. Define Custom Interfaces: If existing interfaces don't cover your needs, define a new interface (e.g., using typing.Protocol) and add it as a supertype.
5. Verify Laws: Use hypothesis to check that your container adheres to functional programming laws. You can define custom laws using a LawSpec and verify them with check_all_laws.
6. Write Type-Tests: Use mypy snapshots (e.g., with pytest-mypy-plugins) to ensure your container's type signatures behave correctly under both valid and invalid usage.

from typing import Callable, TypeVar, Tuple, final

from returns.interfaces import bindable, equable, lashable, swappable
from returns.primitives.container import BaseContainer
from returns.primitives.hkt import SupportsKind2

_FirstType = TypeVar('_FirstType')
_SecondType = TypeVar('_SecondType')
_NewFirstType = TypeVar('_NewFirstType')
_NewSecondType = TypeVar('_NewSecondType')

@final
class Pair(
    BaseContainer,
    SupportsKind2['Pair', _FirstType, _SecondType],
    bindable.Bindable2[_FirstType, _SecondType],
    swappable.Swappable2[_FirstType, _SecondType],
    lashable.Lashable2[_FirstType, _SecondType],
    equable.Equable,
):
    def __init__(
        self, inner_value: Tuple[_FirstType, _SecondType],
    ) -> None:
        super().__init__(inner_value)

The RequiresContext[ReturnType, EnvType] container allows you to implement dependency injection by wrapping a function that accepts an environment/dependency object. Instead of passing parameters through every level of your callstack, you wrap your logic in RequiresContext. Dependencies are injected at the very last moment when the container is called with the environment object.

Note: RequiresContext and similar types are not recursion safe. Deep nesting exceeding sys.getrecursionlimit() will cause a RecursionError.

from typing import Protocol
from returns.context import RequiresContext

class _Deps(Protocol):
    WORD_THRESHOLD: int

def calculate_points(word: str) -> RequiresContext[int, _Deps]:
    guessed_letters_count = len([letter for letter in word if letter != '.'])
    return _award_points_for_letters(guessed_letters_count)

def _award_points_for_letters(guessed: int) -> RequiresContext[int, _Deps]:
    return RequiresContext(
        lambda deps: 0 if guessed < deps.WORD_THRESHOLD else guessed,
    )

# To execute, pass the dependencies at the end:
# result = calculate_points("abc")(my_deps_instance)