Skip to content

Commit 6e8f531

Browse files
committed
Rename is in progress
1 parent 4f0c97c commit 6e8f531

File tree

2 files changed

+37
-36
lines changed

2 files changed

+37
-36
lines changed

docs/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Contents
1616
:maxdepth: 2
1717
:caption: Userguide
1818

19-
pages/monad.rst
19+
pages/container.rst
2020
pages/maybe.rst
2121
pages/result.rst
2222
pages/functions.rst

docs/pages/container.rst

Lines changed: 36 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,7 @@
11
Container: the concept
22
======================
33

4-
.. currentmodule:: returns.primitives.monads
5-
6-
We won't say that monad is `a monoid in the category of endofunctors <https://stackoverflow.com/questions/3870088/a-monad-is-just-a-monoid-in-the-category-of-endofunctors-whats-the-problem>`_.
4+
.. currentmodule:: returns.primitives.container
75

86
Container is a concept that allows you
97
to write code without traditional error handling
@@ -14,12 +12,13 @@ We will show you its simple API of one attribute and several simple methods.
1412
Internals
1513
---------
1614

17-
The main idea behind a monad is that it wraps some internal state.
15+
The main idea behind a container is that it wraps some internal state.
1816
That's what
19-
:py:attr:`Container._inner_value <returns.primitives.monad.Container._inner_value>`
17+
:py:attr:`_inner_value <returns.primitives.container.Container._inner_value>`
2018
is used for.
2119

22-
And we have several functions to create new monads based on the previous state.
20+
And we have several functions
21+
to create new containers based on the previous state.
2322
And we can see how this state is evolving during the execution.
2423

2524
.. mermaid::
@@ -31,19 +30,19 @@ And we can see how this state is evolving during the execution.
3130
F3 --> F4["State(FailedLoginAttempt(1))"]
3231
F4 --> F5["State(SentNotificationId(992))"]
3332

34-
Creating new monads
35-
~~~~~~~~~~~~~~~~~~~
33+
Creating new containers
34+
~~~~~~~~~~~~~~~~~~~~~~~
3635

37-
We use two methods to create new monads from the previous one.
36+
We use two methods to create new containers from the previous one.
3837
``bind`` and ``map``.
3938

4039
The difference is simple:
4140

4241
- ``map`` works with functions that return regular values
43-
- ``bind`` works with functions that return monads
42+
- ``bind`` works with functions that return containers
4443

45-
:func:`Container.bind <returns.primitives.monad.Container.bind>`
46-
is used to literally bind two different monads together.
44+
:func:`Container.bind <returns.primitives.container.Container.bind>`
45+
is used to literally bind two different containers together.
4746

4847
.. code:: python
4948
@@ -56,10 +55,10 @@ is used to literally bind two different monads together.
5655
# => Will be equal to Result Success[int] or Failure[str]
5756
5857
So, the rule is: whenever you have some impure functions,
59-
it should return a monad instead.
58+
it should return a container type instead.
6059

61-
And we use :func:`Container.map <returns.primitives.monad.Container.map>`
62-
to use monads with pure functions.
60+
And we use :func:`Container.map <returns.primitives.container.Container.map>`
61+
to use containers with `pure functions <https://en.wikipedia.org/wiki/Pure_function>`_.
6362

6463
.. code:: python
6564
@@ -75,12 +74,14 @@ Reverse operations
7574
~~~~~~~~~~~~~~~~~~
7675

7776
We also support two special methods to work with "failed"
78-
monads like ``Failure`` and ``Nothing``:
77+
types like ``Failure`` and ``Nothing``:
7978

80-
- :func:`Container.fix <returns.primitives.monad.Container.fix>` the opposite
81-
of ``map`` method that works only when monad is failed
82-
- :func:`Container.rescue <returns.primitives.monad.Container.rescue>` the opposite
83-
of ``bind`` method that works only when monad is failed
79+
- :func:`Container.fix <returns.primitives.container.Container.fix>`
80+
is the opposite of ``map`` method
81+
that works only when container is in failed state
82+
- :func:`Container.rescue <returns.primitives.container.Container.rescue>`
83+
is the opposite of ``bind`` method
84+
that works only when container is in failed state
8485

8586
``fix`` can be used to fix some fixable errors
8687
during the pipeline execution:
@@ -95,8 +96,8 @@ during the pipeline execution:
9596
Failure(1).fix(double)
9697
# => Will be equal to Success(2.0)
9798
98-
``rescue`` can return any monad you want.
99-
It can also fix your flow and get on the Success track again:
99+
``rescue`` can return any container type you want.
100+
It can also fix your flow and get on the successful track again:
100101

101102
.. code:: python
102103
@@ -114,12 +115,12 @@ Unwrapping values
114115
~~~~~~~~~~~~~~~~~
115116

116117
And we have two more functions to unwrap
117-
inner state of monads into a regular types:
118+
inner state of containers into a regular types:
118119

119-
- :func:`Container.value_or <returns.primitives.monad.Container.value_or>` - returns
120-
a value if it is possible, returns ``default_value`` otherwise
121-
- :func:`Container.unwrap <returns.primitives.monad.Container.unwrap>` - returns
122-
a value if it possible, raises ``UnwrapFailedError`` otherwise
120+
- :func:`Container.value_or <returns.primitives.container.Container.value_or>`
121+
returns a value if it is possible, returns ``default_value`` otherwise
122+
- :func:`Container.unwrap <returns.primitives.container.Container.unwrap>`
123+
returns a value if it is possible, raises ``UnwrapFailedError`` otherwise
123124

124125
.. code:: python
125126
@@ -139,9 +140,9 @@ inner state of monads into a regular types:
139140
140141
The most user-friendly way to use ``unwrap`` method is with :ref:`do-notation`.
141142

142-
For failing monads you can
143-
use :func:`Container.failure <returns.primitives.monad.Container.failure>`
144-
to unwrap failed state:
143+
For failing containers you can
144+
use :func:`Container.failure <returns.primitives.container.Container.failure>`
145+
to unwrap the failed state:
145146

146147
.. code:: python
147148
@@ -152,16 +153,16 @@ to unwrap failed state:
152153
# => Traceback (most recent call last): UnwrapFailedError
153154
154155
Be careful, since this method will raise an exception
155-
when you try to ``failure`` a successful monad.
156+
when you try to ``failure`` a successful container.
156157

157158
Immutability
158159
------------
159160

160161
We like to think of ``returns`` as immutable structures.
161-
You cannot mutate the inner state of the created monad,
162+
You cannot mutate the inner state of the created container,
162163
because we redefine ``__setattr__`` and ``__delattr__`` magic methods.
163164

164-
You cannot also set new attributes to monad instances,
165+
You cannot also set new attributes to container instances,
165166
since we are using ``__slots__`` for better performance and strictness.
166167

167168
Well, nothing is **really** immutable in python, but you were warned.
@@ -178,7 +179,7 @@ So, instead of:
178179

179180
.. code:: python
180181
181-
some_monad.map(lambda x: x + 2) #: Callable[[Any], Any]
182+
some_container.map(lambda x: x + 2) #: Callable[[Any], Any]
182183
183184
Write:
184185

@@ -189,7 +190,7 @@ Write:
189190
def increment(addition: int, number: int) -> int:
190191
return number + addition
191192
192-
some_monad.map(partial(increment, 2)) #: functools.partial[builtins.int*]
193+
some_container.map(partial(increment, 2)) # functools.partial[builtins.int]
193194
194195
This way your code will be type-safe from errors.
195196

0 commit comments

Comments
 (0)