Adding some utility methods to Maybe/Result

[ariebovenberg]

Have you considered adding some handy utility functions to Maybe and Result?
In using returns I'm missing many helpful methods you can find in Rust, for example.
Adding a few of these could increase the usability of the containers of returns.

Related: #1091

Here they are, in my subjective order of usefulness:

Setdefault

Set a value if one is not yet present.
The name setdefault would be consistent with the python dict method.
(Although it might be good to choose another name to make clear that
the method doesn't mutate.)

>>> Some(6).setdefault(7)
Some(6)
>>> Nothing.setdefault(3)
Some(3)

Zip

Combine the values from two containers into a tuple, if both are successful.

>>> Some(8).zip(Some(2))
Some((8, 2))
>>> Some(7).zip(Nothing)
Nothing
>>> Nothing.zip(Some(3))
Nothing
>>> Nothing.zip(Nothing)
Nothing

Filter

Keep a value based on a predicate

>>> Some("9").filter(str.isdigit)
Some("9")
>>> Some("foo3").filter(str.isdigit)
Nothing
>>> Nothing.filter(str.isdigit)
Nothing

And

AND logic operation

>>> Some(5).and_(Some(9))
Some(9)
>>> Some(9).and_(Nothing)
Nothing
>>> Nothing.and_(Some(8))
Nothing

Or

OR logic operation

>>> Some(5).or_(Some(9))
Some(5)
>>> Some(9).or_(Nothing)
Some(9)
>>> Nothing.or_(Some(8))
Some(8)
>>> Nothing.or_(Nothing)
Nothing

[CucumisSativus]

I think Setdefault is already in the library, in the form of value_or().
With zip (or map_n) and filter I really think those would be valuable additions to the library.
Could you show how would you use and and or, I think I am missing the idea how could those be used in the real source code

[ariebovenberg]

I'll illustrate with this example:

from typing import NamedTuple


class User(NamedTuple):
    id: int
    nickname: Maybe[str]
    first_name: Maybe[str]
    last_name: str
    joined: datetime
    job: Maybe[str]
    location: Maybe[int]

Setdefault

There difference with value_or() is that setdefault() doesn't unwrap the value. This can be useful when you want to keep the container. For example when updating a Maybe attribute.

user = user._replace(
    status=user.status.setdefault('Hello World')
)
# equivalent to
user = user._replace(
    status=user.status.success_type(user.status.value_or('Hello World'))
)

Or

Like Python's or, it is useful for fallback values:

# same behavior as python's `or` operator: returns the first success value, otherwise the second
salutation: Maybe[str] = user.nickname.or_(user.first_name)

(The difference with value_or() is that you combine two wrapped values)

And

I can't think of a super convincing case here, but it'd make sense to have it as a complement to or_(). I'm sure this basic logical operation would be useful to some people. Also, it's probably more useful in Result, where the failure type contains useful information.

# same behavior as python's `and` operator: returns the first failure value, otherwise the second
work_location: Maybe[str] = user.job.and_(user.location)

[CucumisSativus]

Thanks a lot for the clarifications, I should take a look at the issue slightly later in the morning :)

I am happy to implement zip and filter, for the other methods I'm not entirely convinced. But if @sobolevn says those are ok to be implemented, i am happy to do it as well :)

[ariebovenberg]

@CucumisSativus Thanks for the feedback!

😉 If you don't mind though, I was actually really looking forward to implementing these, after being given the green light. I'm really interested in diving into returns internals 🤩

edit: reading back I see I didn't make this clear before. How about we each take half of whatever methods get approved to add?

[CucumisSativus]

@ariebovenberg Sorry I rushed a bit and started with filter, but there are plenty of other methods and I'm happy to share them with you :). My time is a bit limited so I don't think I can realistically do more than filter this week, so please choose the methods you want to implement. Let's use this issue for coordination when it comes to implementing them.

[sobolevn]

🎉

[ariebovenberg]

@sobolevn agree to implement all methods?

• filter
• zip
• setdefault -- also agree on the name?
• and_ and or_

Then we can start the work.

[sobolevn]

@ariebovenberg you would love to have as much utils as possible, but. There's one very important step here:

We really prefer to have functions over methods. For example. We can create def and_(self, other) method in Maybe / Result / IOResult / etc. Or we can create a single function which works with any (or only some) given containers.

The difference is not just semantical. If we add these as methods, we would have to add HKT interfaces on top of that. And make our classes more complex by adding more utility methods.

Functions on the other hand only require existing interfaces and do not polute classes with extra methods.

[sobolevn]

We store utils here: https://github.com/dry-python/returns/tree/master/returns/methods

[ariebovenberg]

I'm definitely willing to defer to your preference on this matter. But let's see if I can make the case for methods...

In the absence of first-class support for currying and composition in Python, I feel methods have an advantage on readability.

x.filter(str.isdigit).or_(y).setdefault('foo')

setdefault(or_(filter(x, str.isdigit), y), 'foo')  # less readable IMHO

For these particular methods:

• zip, and_ and or_ would work OK as standalone functions (i.e. they work on all success/failure types).
• setdefault is mainly a convenience helper. Having to import it separately kind of defeats the purpose IMHO. I'd go for a method.
• filter looks like something only possible for Maybe (since it needs to be able to 'empty' a container). Seems like a method would be more appropriate?

[sobolevn]

zip, and_ and or_ would work OK as standalone functions

Awesome! 👍

Having to import it separately kind of defeats the purpose IMHO. I'd go for a method.

Ok, let's make it the very last item to implement then! We can think some more about different choices.

filter looks like something only possible for Maybe (since it needs to be able to 'empty' a container). Seems like a method would be more appropriate?

It is still fine to use it as a function, because we have MaybeLikeN (or MaybeBasedN) and people can theoretically make their own Maybe types. So, function can help to remove one extra implementaion step to them.

[ariebovenberg]

@CucumisSativus probably best if you pick up zip as well. Just like filter it only works on maybes. I'll pick up setdefault, and_, or_

[CucumisSativus]

I am happy to pick zip, but I would like to challenge that it should be only implemented for maybe.

For result I would see it like this

>>> Success(1).zip(Success("str"))
Success(1, "str")
>>>Failure(Exception("a")).zip(Success(1))
Failure(Exception("a")
>>>Failure(Exception("a")).zip(Failure(Exception("b"))
Failure(Exception("a"))
>>>Success(1).zip(Failure(Exception("a"))
Failure(Exception("a"))

For IO

>>>IO(1).zip(IO(2))
IO((1,2))

With IOResult I think it could work if both results have the same error type.

@sobolevn @ariebovenberg what do you think about it?