Initial pyi stubs are created

Author: sobolevn

.editorconfig

@@ -12,3 +12,6 @@ indent_size = 2
 
 [*.py]
 indent_size = 4
+
+[*.pyi]
+indent_size = 4

.travis.yml

@@ -19,6 +19,7 @@ install:
 script:
   - poetry run flake8 returns tests docs
   - poetry run mypy returns tests/**/*.py
+  - poetry run mypy returns/**/*.pyi
   - poetry run pytest
   - poetry run doc8 -q docs
   - poetry check

README.md

@@ -3,7 +3,7 @@
 [![wemake.services](https://img.shields.io/badge/%20-wemake.services-green.svg?label=%20&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC%2FxhBQAAAAFzUkdCAK7OHOkAAAAbUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP%2F%2F%2F5TvxDIAAAAIdFJOUwAjRA8xXANAL%2Bv0SAAAADNJREFUGNNjYCAIOJjRBdBFWMkVQeGzcHAwksJnAPPZGOGAASzPzAEHEGVsLExQwE7YswCb7AFZSF3bbAAAAABJRU5ErkJggg%3D%3D)](https://wemake.services) [![Build Status](https://travis-ci.org/dry-python/returns.svg?branch=master)](https://travis-ci.org/dry-python/returns) [![Coverage Status](https://coveralls.io/repos/github/dry-python/returns/badge.svg?branch=master)](https://coveralls.io/github/dry-python/returns?branch=master) [![Documentation Status](https://readthedocs.org/projects/returns/badge/?version=latest)](https://returns.readthedocs.io/en/latest/?badge=latest) [![Python Version](https://img.shields.io/pypi/pyversions/returns.svg)](https://pypi.org/project/returns/) [![wemake-python-styleguide](https://img.shields.io/badge/style-wemake-000000.svg)](https://github.com/wemake-services/wemake-python-styleguide)
 
 
-Make your functions return something meaningful and safe!and safe.
+Make your functions return something meaningful and safe!
 
 
 ## Features

poetry.lock

@@ -49,6 +49,7 @@ sphinxcontrib-mermaid = "^0.3.1"
 doc8 = "^0.8.0"
 m2r = "^0.2.1"
 tomlkit = "^0.5.3"
+flake8-pyi = "^18.3"
 
 [build-system]
 requires = ["poetry>=0.12"]

pyproject.toml

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable
+
+from returns.primitives.types import MonadType
+
+
+def do_notation(
+    function: Callable[..., MonadType],
+) -> Callable[..., MonadType]:
+    ...

returns/do_notation.pyi

@@ -9,14 +9,14 @@
 from returns.primitives.monad import Monad, NewValueType, ValueType
 from returns.primitives.types import MonadType
 
-ErrorType = TypeVar('ErrorType')
+_ErrorType = TypeVar('_ErrorType')
 
 
 # That's the most ugly part.
 # We need to express `Either` with two type parameters and
 # Left and Right with just one parameter.
 # And that's how we do it. Any other and more cleaner ways are appreciated.
-class Either(Generic[ValueType, ErrorType], metaclass=ABCMeta):
+class Either(Generic[ValueType, _ErrorType], metaclass=ABCMeta):
     """
     Represents a calculation that may either fail or succeed.
 
@@ -26,7 +26,7 @@ class Either(Generic[ValueType, ErrorType], metaclass=ABCMeta):
     and 'Left' (or its alias 'Failure').
     """
 
-    _inner_value: Union[ValueType, ErrorType]
+    _inner_value: Union[ValueType, _ErrorType]
 
     @abstractmethod
     def unwrap(self) -> ValueType:  # pragma: no cover
@@ -40,33 +40,33 @@ def unwrap(self) -> ValueType:  # pragma: no cover
 
 
 @final
-class Left(Either[Any, ErrorType], Monad[ErrorType]):
+class Left(Either[Any, _ErrorType], Monad[_ErrorType]):
     """
     Represents a calculation which has failed.
 
     It should contain an error code or message.
     To help with readability you may alternatively use the alias 'Failure'.
     """
 
-    def __init__(self, inner_value: ErrorType) -> None:
+    def __init__(self, inner_value: _ErrorType) -> None:
         """
         Wraps the given value in the Container.
 
         'value' is any arbitrary value of any type including functions.
         """
         object.__setattr__(self, '_inner_value', inner_value)
 
-    def fmap(self, function) -> 'Left[ErrorType]':
+    def fmap(self, function) -> 'Left[_ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
         return self
 
-    def bind(self, function) -> 'Left[ErrorType]':
+    def bind(self, function) -> 'Left[_ErrorType]':
         """Returns the 'Left' instance that was used to call the method."""
         return self
 
     def efmap(
         self,
-        function: Callable[[ErrorType], NewValueType],
+        function: Callable[[_ErrorType], NewValueType],
     ) -> 'Right[NewValueType]':
         """
         Applies function to the inner value.
@@ -78,7 +78,7 @@ def efmap(
         """
         return Right(function(self._inner_value))
 
-    def ebind(self, function: Callable[[ErrorType], MonadType]) -> MonadType:
+    def ebind(self, function: Callable[[_ErrorType], MonadType]) -> MonadType:
         """
         Applies 'function' to the result of a previous calculation.
 
@@ -95,7 +95,7 @@ def unwrap(self) -> NoReturn:
         """Raises an exception, since it does not have a value inside."""
         raise UnwrapFailedError(self)
 
-    def failure(self) -> ErrorType:
+    def failure(self) -> _ErrorType:
         """Unwraps inner error value from failed monad."""
         return self._inner_value
 

returns/either.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+
+from abc import ABCMeta, abstractmethod
+from typing import Any, Callable, Generic, NoReturn, TypeVar, Union
+
+from typing_extensions import final
+
+from returns.primitives.monad import Monad, NewValueType, ValueType
+from returns.primitives.types import MonadType
+
+_ErrorType = TypeVar('_ErrorType')
+
+
+class Either(Generic[ValueType, _ErrorType], metaclass=ABCMeta):
+    _inner_value: Union[ValueType, _ErrorType]
+
+    @abstractmethod
+    def unwrap(self) -> ValueType:  # pragma: no cover
+        ...
+
+
+@final
+class Left(Either[Any, _ErrorType], Monad[_ErrorType]):
+    _inner_value: _ErrorType
+
+    def __init__(self, inner_value: _ErrorType) -> None:
+        ...
+
+    def fmap(self, function) -> 'Left[_ErrorType]':
+        ...
+
+    def bind(self, function) -> 'Left[_ErrorType]':
+        ...
+
+    def efmap(
+        self,
+        function: Callable[[_ErrorType], NewValueType],
+    ) -> 'Right[NewValueType]':
+        ...
+
+    def ebind(self, function: Callable[[_ErrorType], MonadType]) -> MonadType:
+        ...
+
+    def value_or(self, default_value: NewValueType) -> NewValueType:
+        ...
+
+    def unwrap(self) -> NoReturn:
+        ...
+
+    def failure(self) -> _ErrorType:
+        ...
+
+
+@final
+class Right(Either[ValueType, Any], Monad[ValueType]):
+    _inner_value: ValueType
+
+    def __init__(self, inner_value: ValueType) -> None:
+        ...
+
+    def fmap(
+        self,
+        function: Callable[[ValueType], NewValueType],
+    ) -> 'Right[NewValueType]':
+        ...
+
+    def bind(
+        self,
+        function: Callable[[ValueType], MonadType],
+    ) -> MonadType:
+        ...
+
+    def efmap(self, function) -> 'Right[ValueType]':
+        ...
+
+    def ebind(self, function) -> 'Right[ValueType]':
+        ...
+
+    def value_or(self, default_value: NewValueType) -> ValueType:
+        ...
+
+    def unwrap(self) -> ValueType:
+        ...
+
+    def failure(self) -> NoReturn:
+        ...
+
+
+# Useful aliases for end users:
+
+Result = Either
+Success = Right
+Failure = Left

returns/either.pyi

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+from typing import Callable, TypeVar
+
+from returns.either import Either
+from returns.primitives.types import MonadType
+
+_ReturnType = TypeVar('_ReturnType')
+
+
+def is_successful(monad: MonadType) -> bool:
+    ...
+
+
+def safe(
+    function: Callable[..., _ReturnType],
+) -> Callable[..., Either[_ReturnType, Exception]]:
+    ...

returns/functions.pyi

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 
+from abc import ABCMeta
 from typing import Callable, NoReturn, Union, overload
 
 from typing_extensions import Literal, final
@@ -9,7 +10,7 @@
 from returns.primitives.types import MonadType
 
 
-class Maybe(Monad[ValueType]):
+class Maybe(Monad[ValueType], metaclass=ABCMeta):
     """
     Represents a result of a series of commutation that can return ``None``.
 

returns/maybe.py

@@ -0,0 +1,91 @@
+# -*- coding: utf-8 -*-
+
+from abc import ABCMeta
+from typing import Callable, NoReturn, overload
+
+from typing_extensions import Literal, final
+
+from returns.primitives.monad import Monad, NewValueType, ValueType
+from returns.primitives.types import MonadType
+
+
+class Maybe(Monad[ValueType], metaclass=ABCMeta):
+    @overload
+    @classmethod
+    def new(cls, inner_value: Literal[None]) -> 'Nothing':  # type: ignore
+        ...
+
+    @overload  # noqa: F811
+    @classmethod
+    def new(cls, inner_value: ValueType) -> 'Some[ValueType]':
+        ...
+
+
+@final
+class Nothing(Maybe[Literal[None]]):
+    _inner_value: Literal[None]
+
+    def __init__(self, inner_value: Literal[None] = ...) -> None:
+        ...
+
+    def fmap(self, function) -> 'Nothing':
+        ...
+
+    def bind(self, function) -> 'Nothing':
+        ...
+
+    def efmap(
+        self,
+        function: Callable[[Literal[None]], 'NewValueType'],
+    ) -> 'Some[NewValueType]':
+        ...
+
+    def ebind(
+        self,
+        function: Callable[[Literal[None]], MonadType],
+    ) -> MonadType:
+        ...
+
+    def value_or(self, default_value: NewValueType) -> NewValueType:
+        ...
+
+    def unwrap(self) -> NoReturn:
+        ...
+
+    def failure(self) -> None:
+        ...
+
+
+@final
+class Some(Maybe[ValueType]):
+    _inner_value: ValueType
+
+    def __init__(self, inner_value: ValueType) -> None:
+        ...
+
+    def fmap(
+        self,
+        function: Callable[[ValueType], NewValueType],
+    ) -> 'Some[NewValueType]':
+        ...
+
+    def bind(
+        self,
+        function: Callable[[ValueType], MonadType],
+    ) -> MonadType:
+        ...
+
+    def efmap(self, function) -> 'Some[ValueType]':
+        ...
+
+    def ebind(self, function) -> 'Some[ValueType]':
+        ...
+
+    def value_or(self, default_value: NewValueType) -> ValueType:
+        ...
+
+    def unwrap(self) -> ValueType:
+        ...
+
+    def failure(self) -> NoReturn:
+        ...

returns/maybe.pyi

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+from returns.primitives.types import MonadType
+
+
+class UnwrapFailedError(Exception):
+    def __init__(self, monad: MonadType) -> None:
+        self.halted_monad = monad
+
+
+class ImmutableStateError(Exception):
+    ...