Make your functions return something meaningful, typed, and safe!
Provides a bunch of primitives to write declarative business logic
Enforces better architecture
Fully typed with annotations and checked with mypy
, PEP561 compatible
Pythonic and pleasant to write and to read (!)
Support functions and coroutines, framework agnostic
pip install returns
You might also need to configure
mypy
correctly and install our plugin:
[mypy]
plugins =
returns.contrib.mypy.decorator_plugin
Make sure you know how to get started, check out our docs!
Result container that let’s you to get rid of exceptions
IO marker that marks all impure operations and structures them
Maybe container that allows you to write None
-free code
Please, make sure that you are also aware of Railway Oriented Programming.
Consider this code that you can find in any python
project.
import requests
def fetch_user_profile(user_id: int) -> 'UserProfile':
"""Fetches UserProfile dict from foreign API."""
response = requests.get('/api/users/{0}'.format(user_id))
response.raise_for_status()
return response.json()
Seems legit, does not it?
It also seems like a pretty straight forward code to test.
All you need is to mock requests.get
to return the structure you need.
But, there are hidden problems in this tiny code sample that are almost impossible to spot at the first glance.
import requests
from returns.result import Result, pipeline, safe
class FetchUserProfile(object):
"""Single responsibility callable object that fetches user profile."""
@pipeline
def __call__(self, user_id: int) -> Result['UserProfile', Exception]:
"""Fetches UserProfile dict from foreign API."""
response = self._make_request(user_id).unwrap()
return self._parse_json(response)
@safe
def _make_request(self, user_id: int) -> requests.Response:
response = requests.get('/api/users/{0}'.format(user_id))
response.raise_for_status()
return response
@safe
def _parse_json(self, response: requests.Response) -> 'UserProfile':
return response.json()
Now we have a clean and a safe way to express our business need. We start from making a request, that might fail at any moment.
Now, instead of returning a regular value it returns a wrapped value inside a special container thanks to the @safe decorator.
It will return Success[Response] or Failure[Exception]. And will never throw this exception at us.
When we will need raw value, we can use .unwrap()
method to get it.
If the result is Failure[Exception]
we will actually raise an exception at this point.
But it is safe to use .unwrap()
inside
@pipeline
functions.
Because it will catch this exception
and wrap it inside a new Failure[Exception]
!
And we can clearly see all result patterns that might happen in this particular case:
Success[UserProfile]
Failure[HttpException]
Failure[JsonDecodeException]
And we can work with each of them precisely.
It is a good practice to create Enum
classes or Union
types
with a list of all the possible errors.
But is that all we can improve?
Let’s look at FetchUserProfile
from another angle.
All its methods look like regular ones:
it is impossible to tell whether they are pure or impure from the first sight.
It leads to a very important consequence: we start to mix pure and impure code together. We should not do that!
When these two concepts are mixed we suffer really bad when testing or reusing it. Almost everything should be pure by default. And we should explicitly mark impure parts of the program.
Let’s refactor it to make our IO explicit!
import requests
from returns.io import IO, impure
from returns.result import Result, pipeline, safe
class FetchUserProfile(object):
"""Single responsibility callable object that fetches user profile."""
@pipeline
def __call__(self, user_id: int) -> IO[Result['UserProfile', Exception]]:
"""Fetches UserProfile dict from foreign API."""
return self._make_request(user_id).map(
lambda response: self._parse_json(response.unwrap())
)
@impure
@safe
def _make_request(self, user_id: int) -> requests.Response:
response = requests.get('/api/users/{0}'.format(user_id))
response.raise_for_status()
return response
@safe
def _parse_json(self,response: requests.Response) -> 'UserProfile':
return response.json()
Now we have explicit markers where the IO
did happen
and these markers cannot be removed.
Whenever we access FetchUserProfile
we now know
that it does IO
and might fail.
So, we act accordingly!
Have you ever since code with a lot of if some is not None
conditions?
It really bloats your source code and makes it unreadable.
But, having None
in your source code is even worth.
Actually, None
is called the worth mistake in the history of Computer Science.
So, what to do? Use Maybe
container!
It consists of Some(...)
and Nothing
types,
representing existing state and None
state respectively.
from typing import Optional
from returns.maybe import Maybe
def bad_function() -> Optional[int]:
...
maybe_result: Maybe[float] = Maybe.new(
bad_function(),
).map(
lambda number: number / 2,
)
# => Maybe will return Some(float) only if there's a non-None value
# Otherwise, will return Nothing
Forget about None
-related errors forever!
Want more? Go to the docs! Or read these articles: