gluonts.maybe module

This module contains functions that work on Optional values. In contrast to other approaches, this does not wrap values into a dedicated type, but works on normal Python values, which are of type Optional[T].

Thus, some functions are implemented identically but have different type signatures. For example, both map and and_then both just apply a function to a value if it is not None, but the result of map is T and the result of and_then is Optional[T].

Each function is implemented twice, as a simple function and as a method on maybe.Maybe:

maybe.Maybe(1).map(fn)

maybe.map(1, fn)

The names are taken from Rust, see: https://doc.rust-lang.org/stable/std/option/enum.Option.html

Note

The argument order for map_or and map_or_else is reversed compared to their Rust counterparts.

do is not implemented in Rust but mimics toolz.do instead.

class gluonts.maybe.Maybe(*args, **kwds)

Bases: Generic[gluonts.maybe.T]

and_(other: Optional[gluonts.maybe.U]) → Optional[gluonts.maybe.U]

Like a and b in Python, except only considering None.

This is implement identical to unwrap_or, but different with respect to types.

>>> Maybe(1).and_(2)
2
>>> Maybe(1).and_(None)
>>> Maybe(None).and_(2)

and_then(fn: Callable[[gluonts.maybe.T], Optional[gluonts.maybe.U]]) → Optional[gluonts.maybe.U]

Apply fn to val if it is not None and return the result.

In contrast to map, fn always returns an Optional, which is consequently flattened.

>>> Maybe([42]).and_then(lambda xs: xs[0] if xs else None)
42
>>> Maybe([]).and_then(lambda xs: xs[0] if xs else None)
>>> Maybe(None).and_then(lambda xs: xs[0] if xs else None)

contains(other: gluonts.maybe.U) → bool

Check if val equals other, always return False if val is None.

>>> Maybe(1).contains(1)
True
>>> Maybe(1).contains(2)
False
>>> Maybe(None).contains(3)
False

do(fn: Callable[[gluonts.maybe.T], gluonts.maybe.U]) → Optional[gluonts.maybe.T]

Apply fn to val then return val, if val is not None.

>>> Maybe("a").do(print)
a
'a'
>>> Maybe(None).do(print)

expect(msg: str) → gluonts.maybe.T

Ensure that val is not None, raises a ValueError using msg otherwise.

>>> Maybe(1).expect("My message")
1
>>> Maybe(None).expect("My message")
Traceback (most recent call last):
    ...
ValueError: My message

filter(pred: Callable[[gluonts.maybe.T], bool]) → Optional[gluonts.maybe.T]

Return None if val is None or if pred(val) does not return True, otherwise return val.

>>> is_even = lambda n: n % 2 == 0
>>> Maybe(1).filter(is_even)
>>> Maybe(2).filter(is_even)
2
>>> Maybe(None).filter(is_even)

flatten() → Optional[gluonts.maybe.T]

Flatten nested optional value.

Note: This just returns the value, but changes the type from Optional[Optional[T]] to Optional[T].

map(fn: Callable[[gluonts.maybe.T], gluonts.maybe.U]) → Optional[gluonts.maybe.U]

Apply fn to val if val is not None.

>>> Maybe(1).map(lambda x: x + 1)
2
>>> Maybe(None).map(lambda x: x + 1)

map_or(fn: Callable[[gluonts.maybe.T], gluonts.maybe.U], default: gluonts.maybe.U) → gluonts.maybe.U

Apply fn to val if val is not None and return the result. In case of None the provided default is returned instead.

This is similar to calling map and unwrap_or in succession.

>>> Maybe(["x"]).map_or(len, 0)
1
>>> Maybe(None).map_or(len, 0)
0

map_or_else(fn: Callable[[gluonts.maybe.T], gluonts.maybe.U], factory: Callable[[], gluonts.maybe.U]) → gluonts.maybe.U

Similar to map_or, except that the returned value is lazily evaluated.

This is similar to calling map and unwrap_or_else in succession.

>>> Maybe(1).map_or_else(lambda n: [n], list)
[1]
>>> Maybe(None).map_or_else(lambda n: [n], list)
[]

or_(default: Optional[gluonts.maybe.T]) → Optional[gluonts.maybe.T]

Like a or b in Python, except only considering None.

>>> Maybe(1).or_(2)
1
>>> Maybe(1).or_(None)
1
>>> Maybe(None).or_(2)
2

or_else(factory: Callable[[], Optional[gluonts.maybe.T]]) → Optional[gluonts.maybe.T]

Like unwrap_or_else, except that it returns an optional value.

>>> Maybe([42]).or_else(list)
[42]
>>> Maybe(None).or_else(list)
[]

unwrap() → gluonts.maybe.T

Assert that the value is not None.

>>> Maybe(1).unwrap()
1
>>> Maybe(None).unwrap()
Traceback (most recent call last):
    ...
ValueError: Trying to unwrap `None` value.

unwrap_or(default: gluonts.maybe.T) → gluonts.maybe.T

Get val if it is not None, or default otherwise.

>>> Maybe(1).unwrap_or(2)
1
>>> Maybe(None).unwrap_or(2)
2

unwrap_or_else(fn: Callable[[], gluonts.maybe.T]) → gluonts.maybe.T

Get val if it is not None, or invoke factory to get a fallback.

>>> Maybe([1, 2, 3]).unwrap_or_else(list)
[1, 2, 3]
>>> Maybe(None).unwrap_or_else(list)
[]

val: Optional[gluonts.maybe.T]

xor(other: Optional[gluonts.maybe.T]) → Optional[gluonts.maybe.T]

Return either val or other if the other is None. Also return None if both are not None.

>>> Maybe(1).xor(None)
1
>>> Maybe(None).xor(2)
2
>>> Maybe(1).xor(2)
>>> Maybe(None).xor(None)

gluonts.maybe.and_(val: Optional[gluonts.maybe.T], other: Optional[gluonts.maybe.U]) → Optional[gluonts.maybe.U]

Like a and b in Python, except only considering None.

This is implement identical to unwrap_or, but different with respect to types.

>>> and_(1, 2)
2
>>> and_(1, None)
>>> and_(None, 2)

gluonts.maybe.and_then(val: Optional[gluonts.maybe.T], fn: Callable[[gluonts.maybe.T], Optional[gluonts.maybe.U]]) → Optional[gluonts.maybe.U]

Apply fn to val if it is not None and return the result.

In contrast to map, fn always returns an Optional, which is consequently flattened.

>>> and_then([42], lambda xs: xs[0] if xs else None)
42
>>> and_then(None, lambda xs: xs[0] if xs else None)

gluonts.maybe.contains(val: Optional[gluonts.maybe.T], other: gluonts.maybe.U) → bool

Check if val equals other, always return False if val is None.

>>> contains(1, 1)
True
>>> contains(1, 2)
False
>>> contains(None, 3)
False

gluonts.maybe.do(val: Optional[gluonts.maybe.T], fn: Callable[[gluonts.maybe.T], gluonts.maybe.U]) → Optional[gluonts.maybe.T]

Apply fn to val then return val, if val is not None.

>>> do("a", print)
a
'a'
>>> do(None, print)

gluonts.maybe.expect(val: Optional[gluonts.maybe.T], msg: str) → gluonts.maybe.T

Ensure that val is not None, raises a ValueError using msg otherwise.

>>> expect(1, "My message")
1
>>> expect(None, "My message")
Traceback (most recent call last):
    ...
ValueError: My message

gluonts.maybe.filter(val: Optional[gluonts.maybe.T], pred: Callable[[gluonts.maybe.T], bool]) → Optional[gluonts.maybe.T]

Return None if val is None or if pred(val) does not return True, otherwise return val.

>>> is_even = lambda n: n % 2 == 0
>>> filter(1, is_even)
>>> filter(2, is_even)
2
>>> filter(None, is_even)

gluonts.maybe.flatten(val: Optional[gluonts.maybe.T]) → Optional[gluonts.maybe.T]

Flatten nested optional value.

Note: This just returns the value, but changes the type from Optional[Optional[T]] to Optional[T].

gluonts.maybe.map(val: Optional[gluonts.maybe.T], fn: Callable[[gluonts.maybe.T], gluonts.maybe.U]) → Optional[gluonts.maybe.U]

Apply fn to val if val is not None.

>>> map(1, lambda x: x + 1)
2
>>> map(None, lambda x: x + 1)

gluonts.maybe.map_or(val: Optional[gluonts.maybe.T], fn: Callable[[gluonts.maybe.T], gluonts.maybe.U], default: gluonts.maybe.U) → gluonts.maybe.U

Apply fn to val if val is not None and return the result. In case of None the provided default is returned instead.

This is similar to calling map and unwrap_or in succession.

>>> map_or(["x"], len, 0)
1
>>> map_or(None, len, 0)
0

gluonts.maybe.map_or_else(val: Optional[gluonts.maybe.T], fn: Callable[[gluonts.maybe.T], gluonts.maybe.U], factory: Callable[[], gluonts.maybe.U]) → gluonts.maybe.U

Similar to map_or, except that the returned value is lazily evaluated.

This is similar to calling map and unwrap_or_else in succession.

>>> map_or_else(1, lambda n: [n], list)
[1]
>>> map_or_else(None, lambda n: [n], list)
[]

gluonts.maybe.or_(val: Optional[gluonts.maybe.T], default: Optional[gluonts.maybe.T]) → Optional[gluonts.maybe.T]

Like a or b in Python, except only considering None.

>>> or_(1, 2)
1
>>> or_(1, None)
1
>>> or_(None, 2)
2

gluonts.maybe.or_else(val: Optional[gluonts.maybe.T], factory: Callable[[], Optional[gluonts.maybe.T]]) → Optional[gluonts.maybe.T]

Like unwrap_or_else, except that it returns an optional value.

>>> or_else([42], list)
[42]
>>> or_else(None, list)
[]

gluonts.maybe.unwrap(val: Optional[gluonts.maybe.T]) → gluonts.maybe.T

Assert that the value is not None.

>>> unwrap(1)
1
>>> unwrap(None)
Traceback (most recent call last):
    ...
ValueError: Trying to unwrap `None` value.

gluonts.maybe.unwrap_or(val: Optional[gluonts.maybe.T], default: gluonts.maybe.T) → gluonts.maybe.T

Get val if it is not None, or default otherwise.

>>> unwrap_or(1, 2)
1
>>> unwrap_or(None, 2)
2

gluonts.maybe.unwrap_or_else(val: Optional[gluonts.maybe.T], factory: Callable[[], gluonts.maybe.T]) → gluonts.maybe.T

Get val if it is not None, or invoke factory to get a fallback.

>>> unwrap_or_else([1, 2, 3], list)
[1, 2, 3]
>>> unwrap_or_else(None, list)
[]

gluonts.maybe.xor(val: Optional[gluonts.maybe.T], other: Optional[gluonts.maybe.T]) → Optional[gluonts.maybe.T]

Return either val or other if the other is None. Also return None if both are not None.

>>> xor(1, None)
1
>>> xor(None, 2)
2
>>> xor(1, 2)
>>> xor(None, None)