Version 0.11 release

CHANGELOG.md

@@ -6,7 +6,7 @@ incremental in minor, bugfixes only are patches.
 See (0Ver)[https://0ver.org/].
 
 
-## 0.11.0 WIP
+## 0.11.0
 
 ### Features
 
@@ -17,9 +17,14 @@ See (0Ver)[https://0ver.org/].
 - **Breaking**: dropped support of zero argument functions for `Nothing.fix`
 - **Breaking**: dropped support of zero argument functions for `Nothing.rescue`
 - `Maybe` now has `.failure()` to match the same API as `Result`
+- Adds `identity` function
 - Adds `tap` function
 - Now `pipe` allows to pipe 8 steps
-- Adds `coalesce_conatiner` coverter
+- Adds `coalesce_result` and `coalesce_maybe` coverters
+
+### Bugfixes
+
+- Fixes that code inside `.fix` and `.rescue` of `Maybe` might be called twice
 
 ### Misc
 

docs/pages/functions.rst

@@ -23,6 +23,19 @@ functions with one argument and one return to be composed.
 Only works with regular functions (not async).
 
 
+identity
+--------
+
+We also ship :func:`returns.functions.identity` function
+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:
+
+- `Practical Usage of Identity Function <https://blog.bigbinary.com/2018/03/20/practical-usage-of-identity-function.html>`_ (JS)
+- `Using Identity Functions <https://emilvarga.com/posts/2016/08/01/using-identity-functions>`_ (Scala)
+
+
 box
 ---
 

pyproject.toml

@@ -9,7 +9,7 @@ style = "https://raw.githubusercontent.com/wemake-services/wemake-python-stylegu
 
 [tool.poetry]
 name = "returns"
-version = "0.10.0"
+version = "0.11.0"
 description = "Make your functions return something meaningful, typed, and safe!"
 license = "BSD-2-Clause"
 
@@ -27,6 +27,8 @@ keywords = [
   "fp",
   "monads",
   "monad",
+  "monad transformers",
+  "composition",
   "type-safety",
   "mypy",
   "railway-oriented-programming"

returns/functions.py

@@ -10,6 +10,41 @@
 _ThirdType = TypeVar('_ThirdType')
 
 
+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 fold `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
+
+
 def compose(
     first: Callable[[_FirstType], _SecondType],
     second: Callable[[_SecondType], _ThirdType],

typesafety/test_functions/test_identity.yml

@@ -0,0 +1,6 @@
+- case: identity_function
+  disable_cache: true
+  main: |
+    from returns.functions import identity
+
+    reveal_type(identity(1))  # N: Revealed type is 'builtins.int*'