We feature several helper functions to make your developer experience better.
We also ship an utility function to compose two different functions together.
>>> from returns.functions import compose >>> bool_after_int = compose(int, bool) >>> bool_after_int('1') True >>> bool_after_int('0') False
Composition is also type-safe. The only limitation is that we only support functions with one argument and one return to be composed.
Only works with regular functions (not async).
We also ship
to help you with the composition.
Identity function is a simple concept: it just returns its argument. If you wonder why do we need this function, please read below:
tap() function to easily compose values
with functions that does not return.
For example you sometimes need to
print() values inside your pipe:
>>> from returns.functions import tap >>> result = tap(print)(1) # will print and return 1 1 >>> assert result == 1
You can also use
untap function to turn any function
return type to
None and still do its thing”
>>> from returns.functions import tap, untap >>> result = untap(tap(print))(1) # will print and return None 1 >>> assert result is None
This is also sometimes helpful for a typed function composition.
Sometimes you really want to reraise an exception from
due to some existing API (or a dirty hack).
We allow you to do that with ease!
from returns.functions import raise_exception @pipeline(Result) def create_account_and_user(username: str) -> ...: """ Creates new Account-User pair. Imagine, that you need to reraise ValidationErrors due to existing API. """ return _validate_user( username, ).alt( # What happens here is interesting, since you do not let your # unwrap to fail with UnwrapFailedError, but instead # allows you to reraise a wrapped exception. # In this case `ValidationError()` will be thrown # before `UnwrapFailedError` raise_exception, ) def _validate_user(username: str) -> Result['User', ValidationError]: ...
Use this with caution. We try to remove exceptions from our code base. Original proposal is here.
Function that returns its argument.
>>> identity(1) 1 >>> identity([1, 2, 3]) [1, 2, 3]
Why do we even need this? Identity functions help us with the composition.
Imagine, that you want to use
from returns.result import Result from returns.converters import coalesce_result numbers: Result[int, float] # Now you want to coalesce `number` into `int` type: number: int = coalesce_result(identity, int)(numbers) # Done!
Allows function composition.
second . first or
first() |> second().
You can read it as “second after first”.
>>> compose(float, int)('123.5') 123
We can only compose functions with one argument and one return. Type checked.
Allows to apply some function and return an argument, instead of a result.
Is useful for composing functions with
>>> tap(print)(1) 1 1 >>> tap(lambda _: 1)(2) 2
Allows to apply some function and always return
None as a result.
Is useful for composing functions that do some side effects and return some nosense.
Is the kind of a reverse of the
>>> def strange_log(arg: int) -> int: ... print(arg) ... return arg >>> untap(strange_log)(2) 2 >>> untap(tap(lambda _: 1))(2)
Helper function to raise exceptions as a function.
It might be required as a compatibility tool for existing APIs. That’s how it can be used:
>>> from returns.result import Failure, Result >>> # Some operation result: >>> user: Result[int, ValueError] = Failure(ValueError('boom')) >>> # Here we unwrap internal exception and raise it:
>>> user.fix(raise_exception) Traceback (most recent call last): ... ValueError: boom