Options — returns 0.20.0 documentation

Straight-forward method

Take into account this code that yow will discover in any python undertaking.

import requests

def fetch_user_profile(user_id: int) -> 'UserProfile':
    """Fetches UserProfile dict from international API."""
    response = requests.get('/api/customers/{0}'.format(user_id))
    response.raise_for_status()
    return response.json()

Appears legit, does it not?
It additionally looks like a fairly simple code to check.
All you want is to mock requests.get to return the construction you want.

However, there are hidden issues on this tiny code pattern
which can be virtually unimaginable to identify on the first look.

Hidden issues

Let’s take a look at the very same code,
however with the all hidden issues defined.

import requests

def fetch_user_profile(user_id: int) -> 'UserProfile':
    """Fetches UserProfile dict from international API."""
    response = requests.get('/api/customers/{0}'.format(user_id))

    # What if we attempt to discover person that doesn't exist?
    # Or community will go down? Or the server will return 500?
    # On this case the following line will fail with an exception.
    # We have to deal with all potential errors on this operate
    # and don't return corrupt information to customers.
    response.raise_for_status()

    # What if we've obtained invalid JSON?
    # Subsequent line will elevate an exception!
    return response.json()

Now, all (in all probability all?) issues are clear.
How can we ensure that this operate will probably be protected
to make use of inside our advanced enterprise logic?

We actually can’t be certain!
We should create tons of strive and besides instances
simply to catch the anticipated exceptions. Our code will change into advanced and unreadable with all this mess!

Or we will go along with the highest degree besides Exception: case
to catch actually the whole lot.
And this fashion we’d find yourself with catching undesirable ones.
This method can cover critical issues from us for a very long time.

Pipe instance

import requests
from returns.end result import Consequence, protected
from returns.pipeline import move
from returns.pointfree import bind

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

@protected
def _make_request(user_id: int) -> requests.Response:
    # TODO: we're not but completed with this instance, learn extra about `IO`:
    response = requests.get('/api/customers/{0}'.format(user_id))
    response.raise_for_status()
    return response

@protected
def _parse_json(response: requests.Response) -> 'UserProfile':
    return response.json()

Now we’ve a clear and a protected and declarative method
to precise our enterprise wants:

• We begin from making a request, that may fail at any second,

• Then parsing the response if the request was profitable,

• After which return the end result.

Now, as an alternative of returning common values
we return values wrapped inside a particular container
because of the
@safe
decorator. It can return Success[YourType] or Failure[Exception].
And can by no means throw exception at us!

We additionally use flow
and bind
capabilities for useful and declarative composition.

This manner we will ensure that our code received’t break in
random locations resulting from some implicit exception.
Now we management all elements and are ready for the express errors.

We aren’t but completed with this instance,
let’s proceed to enhance it within the subsequent chapter.

Troublesome IO

Because it was already mentioned, we use IO after we deal with capabilities that don’t fail.

What if our operate can fail and is impure?
Like requests.get() we had earlier in our instance.

Then we’ve to make use of a particular IOResult kind as an alternative of a daily Consequence.
Let’s discover the distinction:

• Our _parse_json operate at all times returns
  the identical end result (hopefully) for a similar enter:
  you’ll be able to both parse legitimate json or fail on invalid one.
  That’s why we return pure Consequence, there’s no IO inside

• Our _make_request operate is impure and might fail.
  Attempt to ship two related requests with and with out web connection.
  The end result will probably be totally different for a similar enter.
  That’s why we should use IOResult right here: it will probably fail and has IO

  See Also

  

  Breaking SecuROM 7 – A Dissection

So, in an effort to fulfill our requirement and separate pure code from impure one,
we’ve to refactor our instance.

Express IO

Let’s make our IO
express!

import requests
from returns.io import IOResult, impure_safe
from returns.end result import protected
from returns.pipeline import move
from returns.pointfree import bind_result

def fetch_user_profile(user_id: int) -> IOResult['UserProfile', Exception]:
    """Fetches `UserProfile` TypedDict from international API."""
    return move(
        user_id,
        _make_request,
        # earlier than: def (Response) -> UserProfile
        # after protected: def (Response) -> ResultE[UserProfile]
        # after bind_result: def (IOResultE[Response]) -> IOResultE[UserProfile]
        bind_result(_parse_json),
    )

@impure_safe
def _make_request(user_id: int) -> requests.Response:
    response = requests.get('/api/customers/{0}'.format(user_id))
    response.raise_for_status()
    return response

@protected
def _parse_json(response: requests.Response) -> 'UserProfile':
    return response.json()

And later we will use unsafe_perform_io
someplace on the high degree of our program to get the pure (or “actual”) worth.

On account of this refactoring session, we all know the whole lot about our code:

Mixing sync and async code

The primary characteristic of Future
is that it permits to run async code
whereas sustaining sync context. Let’s see an instance.

Let’s say we’ve two capabilities,
the first one returns a quantity and the second one increments it:

async def first() -> int:
    return 1

def second():  # How can we name `first()` from right here?
    return first() + 1  # Growth! Do not do that. We illustrate an issue right here.

If we attempt to simply run first(), we’ll simply create an unawaited coroutine.
It received’t return the worth we would like.

However, if we’d attempt to run await first(),
then we would wish to vary second to be async.
And generally it isn’t potential for varied causes.

Nevertheless, with Future we will “faux” to name async code from sync code:

from returns.future import Future

def second() -> Future[int]:
    return Future(first()).map(lambda num: num + 1)

With out touching our first async operate
or making second async we’ve achieved our purpose.
Now, our async worth is incremented inside a sync operate.

Nevertheless, Future nonetheless requires to be executed inside a correct eventloop:

import anyio  # or asyncio, or some other lib

# We will then cross our `Future` to any library: asyncio, trio, curio.
# And use any occasion loop: common, uvloop, even a customized one, and many others
assert anyio.run(second().awaitable) == 2

As you’ll be able to see Future permits you
to work with async capabilities from a sync context.
And to combine these two realms collectively.
Use uncooked Future for operations that can’t fail or elevate exceptions.
Just about the identical logic we had with our IO container.

Async code with out exceptions

We’ve got already lined how “Consequence` <#result-container>`_ works
for each pure and impure code.
The primary concept is: we don’t elevate exceptions, we return them.
It’s particularly vital in async code,
as a result of a single exception can destroy
all our coroutines operating in a single eventloop.

We’ve got a useful mixture of Future and Consequence containers: FutureResult.
Once more, that is precisely like IOResult, however for impure async code.
Use it when your Future might need issues:
like HTTP requests or filesystem operations.

You may simply flip any wild throwing coroutine into a relaxed FutureResult:

import anyio
from returns.future import future_safe
from returns.io import IOFailure

@future_safe
async def elevating():
    elevate ValueError('Not so quick!')

ioresult = anyio.run(elevating.awaitable)  # all `Future`s return IO containers
assert ioresult == IOFailure(ValueError('Not so quick!'))  # True

Utilizing FutureResult will hold your code protected from exceptions.
You may at all times await or execute inside an eventloop any FutureResult
to get sync IOResult occasion to work with it in a sync method.

Higher async composition

Beforehand, you needed to do numerous awaiting whereas writing async code:

async def fetch_user(user_id: int) -> 'Person':
    ...

async def get_user_permissions(person: 'Person') -> 'Permissions':
    ...

async def ensure_allowed(permissions: 'Permissions') -> bool:
    ...

async def predominant(user_id: int) -> bool:
    # Additionally, do not forget to deal with all potential errors with `strive / besides`!
    person = await fetch_user(user_id)  # We are going to await every time we use a coro!
    permissions = await get_user_permissions(person)
    return await ensure_allowed(permissions)

Some individuals are comfortable with it, however some individuals don’t like this crucial fashion.
The issue is that there was no alternative.

However now, you are able to do the identical factor in practical fashion!
With the assistance of Future and FutureResult containers:

import anyio
from returns.future import FutureResultE, future_safe
from returns.io import IOSuccess, IOFailure

@future_safe
async def fetch_user(user_id: int) -> 'Person':
    ...

@future_safe
async def get_user_permissions(person: 'Person') -> 'Permissions':
    ...

@future_safe
async def ensure_allowed(permissions: 'Permissions') -> bool:
    ...

def predominant(user_id: int) -> FutureResultE[bool]:
    # We will now flip `predominant` right into a sync operate, it doesn't `await` in any respect.
    # We additionally do not care about exceptions anymore, they're already dealt with.
    return fetch_user(user_id).bind(get_user_permissions).bind(ensure_allowed)

correct_user_id: int  # has required permissions
banned_user_id: int  # doesn't have required permissions
wrong_user_id: int  # doesn't exist

# We will have right enterprise outcomes:
assert anyio.run(predominant(correct_user_id).awaitable) == IOSuccess(True)
assert anyio.run(predominant(banned_user_id).awaitable) == IOSuccess(False)

# Or we will have errors alongside the way in which:
assert anyio.run(predominant(wrong_user_id).awaitable) == IOFailure(
    UserDoesNotExistError(...),
)

And even one thing actually fancy:

from returns.pointfree import bind
from returns.pipeline import move

def predominant(user_id: int) -> FutureResultE[bool]:
    return move(
        fetch_user(user_id),
        bind(get_user_permissions),
        bind(ensure_allowed),
    )

Later we will additionally refactor our logical capabilities to be sync
and to return FutureResult.

Beautiful, isn’t it?