Source code for returns.functions
# -*- coding: utf-8 -*-
from typing import Any, Callable, NoReturn, TypeVar
# Aliases:
_FirstType = TypeVar('_FirstType')
_SecondType = TypeVar('_SecondType')
_ThirdType = TypeVar('_ThirdType')
[docs]def identity(instance: _FirstType) -> _FirstType:
"""
Function that returns its argument.
.. code:: python
>>> 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 :func:`returns.converters.coalesce_result`
like so:
.. code:: python
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!
See also:
- https://en.wikipedia.org/wiki/Identity_function
- https://stackoverflow.com/a/21506571/4842742
"""
return instance
[docs]def compose(
first: Callable[[_FirstType], _SecondType],
second: Callable[[_SecondType], _ThirdType],
) -> Callable[[_FirstType], _ThirdType]:
"""
Allows function composition.
Works as: ``second . first`` or ``first() |> second()``.
You can read it as "second after first".
.. code:: python
>>> compose(float, int)('123.5')
123
We can only compose functions with one argument and one return.
Type checked.
"""
return lambda argument: second(first(argument))
[docs]def tap(
function: Callable[[_FirstType], Any],
) -> Callable[[_FirstType], _FirstType]:
"""
Allows to apply some function and return an argument, instead of a result.
Is usefull for composing functions with
side-effects like ``print()``, ``logger.log()``, etc.
.. code:: python
>>> tap(print)(1)
1
1
>>> tap(lambda _: 1)(2)
2
See also:
- https://github.com/dry-python/returns/issues/145
"""
def decorator(argument_to_return: _FirstType) -> _FirstType:
function(argument_to_return)
return argument_to_return
return decorator
[docs]def untap(
function: Callable[[_FirstType], Any],
) -> Callable[[_FirstType], None]:
"""
Allows to apply some function and always return ``None`` as a result.
Is usefull for composing functions that do some side effects
and return some nosense.
Is the kind of a reverse of the ``tap`` function.
.. code:: python
>>> def strange_log(arg: int) -> int:
... print(arg)
... return arg
>>> untap(strange_log)(2)
2
>>> untap(tap(lambda _: 1))(2)
See also:
- https://github.com/dry-python/returns/issues/145
"""
def decorator(argument_to_return: _FirstType) -> None:
function(argument_to_return)
return decorator
[docs]def raise_exception(exception: Exception) -> NoReturn:
"""
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:
.. code:: python
>>> from returns.result import Failure, Result
>>> # Some operation result:
>>> user: Result[int, ValueError] = Failure(ValueError('boom'))
>>> # Here we unwrap internal exception and raise it:
..code::
>>> user.fix(raise_exception)
Traceback (most recent call last):
...
ValueError: boom
See also:
- https://github.com/dry-python/returns/issues/56
"""
raise exception