Renames methods

Author: sobolevn

CHANGELOG.md

@@ -3,13 +3,17 @@
 We follow Semantic Versions since the `0.1.0` release.
 
 
-## Version 0.4.0
+## Version 0.4.0 aka Goodbye, Monads!
 
 ### Features
 
 - Moves all types to `.pyi` files
 - Renames all classes according to new naming pattern
 - **HUGE** improvement of types
+- Renames `fmap` to `map`
+- Renames `do_notation` to `pipeline`, moves it to `functions.py`
+- Renames `ebind` to `rescue`
+- Renames `efmap` to `fix`
 
 
 ## Version 0.3.1

README.md

@@ -30,13 +30,13 @@ TODO: example with `requests` and `json`
 
 
 ```python
-from returns.do_notation import do_notation
+from returns.pipeline import pipeline
 from returns.result import Result, Success, Failure
 
 class CreateAccountAndUser(object):
     """Creates new Account-User pair."""
 
-    @do_notation
+    @pipeline
     def __call__(self, username: str, email: str) -> Result['User', str]:
         """Can return a Success(user) or Failure(str_reason)."""
         user_schema = self._validate_user(username, email).unwrap()

docs/pages/do-notation.rst

@@ -25,7 +25,7 @@ Here's the code to illustrate the task.
 
 .. code:: python
 
-  from returns.do_notation import do_notation
+  from returns.pipeline import pipeline
   from returns.result import Result, Success, Failure
 
 
@@ -87,7 +87,7 @@ And here's how we can refactor this monadic code to be more clear.
   class CreateAccountAndUser(object):
       """Creates new Account-User pair."""
 
-      @do_notation
+      @pipeline
       def __call__(self, username: str, email: str) -> Result['User', str]:
           """Can return a Success(user) or Failure(str_reason)."""
           user_schema = self._validate_user(username, email).unwrap()
@@ -102,7 +102,7 @@ Let's see how this new ``.unwrap()`` method works:
 - if you monad is ``Success`` it will return its inner value
 - if your monad is ``Failure`` it will raise a ``UnwrapFailedError``
 
-And that's where ``@do_notation`` decorator becomes in handy.
+And that's where ``@pipeline`` decorator becomes in handy.
 It will catch any ``UnwrapFailedError`` during the pipeline
 and then return a simple ``Failure`` monad.
 
@@ -131,7 +131,7 @@ And that's it!
 
 See also:
   - https://dry-rb.org/gems/returns/do-notation/
-  - https://en.wikibooks.org/wiki/Haskell/do_notation
+  - https://en.wikibooks.org/wiki/Haskell/pipeline
   - https://wiki.haskell.org/Do_notation_considered_harmful
 
 Limitations
@@ -143,10 +143,10 @@ due to `mypy issue <https://github.com/python/mypy/issues/3157>`_:
 
 .. code:: python
 
-  from returns.do_notation import do_notation
+  from returns.pipeline import pipeline
   from returns.result import Success
 
-  @do_notation
+  @pipeline
   def function(param: int) -> Success[int]:
       return Success(param)
 
@@ -164,5 +164,5 @@ with these implementations:
 API Reference
 -------------
 
-.. automodule:: returns.do_notation
+.. automodule:: returns.pipeline
    :members:

docs/pages/monad.rst

@@ -35,11 +35,11 @@ Creating new monads
 ~~~~~~~~~~~~~~~~~~~
 
 We use two methods to create new monads from the previous one.
-``bind`` and ``fmap``.
+``bind`` and ``map``.
 
 The difference is simple:
 
-- ``fmap`` works with functions that return regular values
+- ``map`` works with functions that return regular values
 - ``bind`` works with functions that return monads
 
 :func:`Monad.bind <returns.primitives.monad.Monad.bind>`
@@ -58,7 +58,7 @@ is used to literally bind two different monads together.
 So, the rule is: whenever you have some impure functions,
 it should return a monad instead.
 
-And we use :func:`Monad.fmap <returns.primitives.monad.Monad.fmap>`
+And we use :func:`Monad.map <returns.primitives.monad.Monad.map>`
 to use monads with pure functions.
 
 .. code:: python
@@ -68,7 +68,7 @@ to use monads with pure functions.
   def double(state: int) -> int:
       return state * 2
 
-  result = Success(1).fmap(double)
+  result = Success(1).map(double)
   # => Will be equal to Success(2)
 
 Reverse operations
@@ -77,12 +77,12 @@ Reverse operations
 We also support two special methods to work with "failed"
 monads like ``Failure`` and ``Nothing``:
 
-- :func:`Monad.efmap <returns.primitives.monad.Monad.efmap>` the opposite
-  of ``fmap`` method that works only when monad is failed
-- :func:`Monad.ebind <returns.primitives.monad.Monad.ebind>` the opposite
+- :func:`Monad.fix <returns.primitives.monad.Monad.fix>` the opposite
+  of ``map`` method that works only when monad is failed
+- :func:`Monad.rescue <returns.primitives.monad.Monad.rescue>` the opposite
   of ``bind`` method that works only when monad is failed
 
-``efmap`` can be used to fix some fixable errors
+``fix`` can be used to fix some fixable errors
 during the pipeline execution:
 
 .. code:: python
@@ -92,10 +92,10 @@ during the pipeline execution:
   def double(state: int) -> float:
       return state * 2.0
 
-  Failure(1).efmap(double)
+  Failure(1).fix(double)
   # => Will be equal to Success(2.0)
 
-``ebind`` can return any monad you want.
+``rescue`` can return any monad you want.
 It can also fix your flow and get on the Success track again:
 
 .. code:: python
@@ -107,7 +107,7 @@ It can also fix your flow and get on the Success track again:
           return Success(0)
       return Failure(state)
 
-  Failure(ZeroDivisionError).ebind(fix)
+  Failure(ZeroDivisionError).rescue(fix)
   # => Will be equal to Success(0)
 
 Unwrapping values
@@ -172,13 +172,13 @@ Using lambda functions
 Please, do not use ``lambda`` functions in ``python``. Why?
 Because all ``lambda`` functions arguments are typed as ``Any``.
 This way you won't have any practical typing features
-from ``fmap`` and ``bind`` methods.
+from ``map`` and ``bind`` methods.
 
 So, instead of:
 
 .. code:: python
 
-  some_monad.fmap(lambda x: x + 2)  #: Callable[[Any], Any]
+  some_monad.map(lambda x: x + 2)  #: Callable[[Any], Any]
 
 Write:
 
@@ -189,7 +189,7 @@ Write:
   def increment(addition: int, number: int) -> int:
       return number + addition
 
-  some_monad.fmap(partial(increment, 2))  #: functools.partial[builtins.int*]
+  some_monad.map(partial(increment, 2))  #: functools.partial[builtins.int*]
 
 This way your code will be type-safe from errors.
 

returns/do_notation.py

@@ -30,3 +30,18 @@ def decorator(*args, **kwargs):
         except Exception as exc:
             return Failure(exc)
     return decorator
+
+
+def pipeline(function):
+    """
+    Decorator to enable 'do-notation' context.
+
+    Should be used for series of computations that rely on ``.unwrap`` method.
+    """
+    @wraps(function)
+    def decorator(*args, **kwargs):
+        try:
+            return function(*args, **kwargs)
+        except UnwrapFailedError as exc:
+            return exc.halted_monad
+    return decorator

returns/do_notation.pyi

@@ -6,6 +6,7 @@ from returns.primitives.monad import Monad
 from returns.result import Result
 
 _MonadType = TypeVar('_MonadType', bound=Monad)
+_ReturnsMonadType = TypeVar('_ReturnsMonadType', bound=Callable[..., Monad])
 _ReturnType = TypeVar('_ReturnType')
 
 
@@ -16,6 +17,10 @@ def is_successful(monad: _MonadType) -> bool:
 # Typing decorators is not an easy task, see:
 # https://github.com/python/mypy/issues/3157
 
+def pipeline(function: _ReturnsMonadType) -> _ReturnsMonadType:
+    ...
+
+
 def safe(
     function: Callable[..., _ReturnType],
 ) -> Callable[..., Result[_ReturnType, Exception]]:

returns/functions.py

@@ -39,15 +39,15 @@ def __init__(self, inner_value=None):
         """
         object.__setattr__(self, '_inner_value', inner_value)
 
-    def fmap(self, function):
+    def map(self, function):  # noqa: A003
         """Returns the 'Nothing' instance that was used to call the method."""
         return self
 
     def bind(self, function):
         """Returns the 'Nothing' instance that was used to call the method."""
         return self
 
-    def efmap(self, function):
+    def fix(self, function):
         """
         Applies function to the inner value.
 
@@ -58,7 +58,7 @@ def efmap(self, function):
         """
         return Some(function(self._inner_value))
 
-    def ebind(self, function):
+    def rescue(self, function):
         """
         Applies 'function' to the result of a previous calculation.
 
@@ -87,7 +87,7 @@ class Some(Maybe[_ValueType]):
     Quite similar to ``Success`` type.
     """
 
-    def fmap(self, function):
+    def map(self, function):  # noqa: A003
         """
         Applies function to the inner value.
 
@@ -107,11 +107,11 @@ def bind(self, function):
         """
         return function(self._inner_value)
 
-    def efmap(self, function):
+    def fix(self, function):
         """Returns the 'Some' instance that was used to call the method."""
         return self
 
-    def ebind(self, function):
+    def rescue(self, function):
         """Returns the 'Some' instance that was used to call the method."""
         return self
 

returns/functions.pyi

@@ -23,7 +23,7 @@ class Maybe(GenericMonadOneSlot[_ValueType], metaclass=ABCMeta):
     def new(cls, inner_value: _ValueType) -> 'Some[_ValueType]':
         ...
 
-    def fmap(
+    def map(  # noqa: A003
         self,
         function: Callable[[_ValueType], _NewValueType],
     ) -> Union['Some[_NewValueType]', 'Maybe[_ValueType]']:
@@ -35,13 +35,13 @@ class Maybe(GenericMonadOneSlot[_ValueType], metaclass=ABCMeta):
     ) -> Union[_MonadType, 'Maybe[_ValueType]']:
         ...
 
-    def efmap(
+    def fix(
         self,
         function: Callable[[Literal[None]], '_NewValueType'],
     ) -> Union['Some[_ValueType]', 'Some[_NewValueType]']:
         ...
 
-    def ebind(
+    def rescue(
         self,
         function: Callable[[Literal[None]], _MonadType],
     ) -> Union[_MonadType, 'Maybe[_ValueType]']:
@@ -67,19 +67,19 @@ class Nothing(Maybe[Any]):
     def __init__(self, inner_value: Literal[None] = ...) -> None:
         ...
 
-    def fmap(self, function) -> 'Nothing':
+    def map(self, function) -> 'Nothing':  # noqa: A003
         ...
 
     def bind(self, function) -> 'Nothing':
         ...
 
-    def efmap(
+    def fix(
         self,
         function: Callable[[Literal[None]], '_NewValueType'],
     ) -> 'Some[_NewValueType]':
         ...
 
-    def ebind(
+    def rescue(
         self,
         function: Callable[[Literal[None]], _MonadType],
     ) -> _MonadType:
@@ -102,7 +102,7 @@ class Some(Maybe[_ValueType]):
     def __init__(self, inner_value: _ValueType) -> None:
         ...
 
-    def fmap(
+    def map(  # noqa: A003
         self,
         function: Callable[[_ValueType], _NewValueType],
     ) -> 'Some[_NewValueType]':
@@ -114,10 +114,10 @@ class Some(Maybe[_ValueType]):
     ) -> _MonadType:
         ...
 
-    def efmap(self, function) -> 'Some[_ValueType]':
+    def fix(self, function) -> 'Some[_ValueType]':
         ...
 
-    def ebind(self, function) -> 'Some[_ValueType]':
+    def rescue(self, function) -> 'Some[_ValueType]':
         ...
 
     def value_or(self, default_value: _NewValueType) -> _ValueType: