From 22309952fd7be3ab219730ede9221b822b263682 Mon Sep 17 00:00:00 2001
From: sobolevn <mail@sobolevn.me>
Date: Fri, 30 Aug 2019 00:32:17 +0300
Subject: [PATCH] Version 0.11 release

---
 CHANGELOG.md                                |  9 ++++--
 docs/pages/functions.rst                    | 13 ++++++++
 pyproject.toml                              |  4 ++-
 returns/functions.py                        | 35 +++++++++++++++++++++
 typesafety/test_functions/test_identity.yml |  6 ++++
 5 files changed, 64 insertions(+), 3 deletions(-)
 create mode 100644 typesafety/test_functions/test_identity.yml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 543c8a0f1..6f9286a0e 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/docs/pages/functions.rst b/docs/pages/functions.rst
index 1777ac6bf..f10af7f9b 100644
--- a/docs/pages/functions.rst
+++ b/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
 ---
 
diff --git a/pyproject.toml b/pyproject.toml
index 33cbacd2a..5a741ebbe 100644
--- a/pyproject.toml
+++ b/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"
diff --git a/returns/functions.py b/returns/functions.py
index a1aedffd6..666a43727 100644
--- a/returns/functions.py
+++ b/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],
diff --git a/typesafety/test_functions/test_identity.yml b/typesafety/test_functions/test_identity.yml
new file mode 100644
index 000000000..58575146a
--- /dev/null
+++ b/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*'