gluonts.maybe module

This module contains functions that work on Optional values. It supports wrapping of values into a dedicated type (Maybe), but also works on normal Python values, which are of type Optional[T].

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

maybe.Some(1).map(fn) -> Maybe[T]

maybe.map(1, fn) -> Optional[T]

Methods on Maybe return Maybe types, while functions return Optional values.

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: abc.ABC, Generic[gluonts.maybe.T]

abstract and_(other: Union[gluonts.maybe.U, None, Maybe[T]]) → gluonts.maybe.Maybe[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.

>>> Some(1).and_(2)
Some(2)
>>> Some(1).and_(None)
Nothing
>>> Nothing.and_(2)
Nothing

abstract and_then(fn: Callable[Concatenate[T, P], OptionalOrMaybe[U]], *args: P.args, **kwargs: P.kwargs) → 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.

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

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

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

>>> Some(1).contains(1)
True
>>> Some(1).contains(2)
False
>>> Nothing.contains(3)
False

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

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

>>> Some("a").do(print)
a
Some('a')
>>> Nothing.do(print)
Nothing

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

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

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

abstract filter(pred: Callable[[gluonts.maybe.T], bool]) → gluonts.maybe.Maybe[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
>>> Some(1).filter(is_even)
Nothing
>>> Some(2).filter(is_even)
Some(2)
>>> Nothing.filter(is_even)
Nothing

abstract flatten() → gluonts.maybe.Maybe[gluonts.maybe.T]

Flatten nested optional value.

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

is_none() → bool

abstract is_some() → bool

abstract iter() → List[gluonts.maybe.T]

Wrap val into a list, if it is not None.

Allows to use for loops on optional values.

abstract map(fn: Callable[[gluonts.maybe.T, gluonts.maybe.P], gluonts.maybe.U], *args, **kwargs) → gluonts.maybe.Maybe[gluonts.maybe.U]

Apply fn to val if val is not None.

>>> Some(1).map(lambda x: x + 1)
Some(2)
>>> Nothing.map(lambda x: x + 1)
Nothing

Allows to pass additional arguments that are passed to fn:

>>> Some(10).map(divmod, 3)
Some((3, 1))

abstract 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.

>>> Some(["x"]).map_or(len, 0)
1
>>> Nothing.map_or(len, 0)
0

abstract 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.

>>> Some(1).map_or_else(lambda n: [n], list)
[1]
>>> Nothing.map_or_else(lambda n: [n], list)
[]

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

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

>>> Some(1).or_(2)
Some(1)
>>> Some(1).or_(None)
Some(1)
>>> Nothing.or_(2)
Some(2)

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

Like unwrap_or_else, except that it returns an optional value.

>>> Some([42]).or_else(list)
Some([42])
>>> Nothing.or_else(list)
Some([])

abstract unbox() → Optional[gluonts.maybe.T]

Turn Maybe[T] into Optional[T].

>>> Some(1).unbox()
1
>>> Some(None).unbox() is None
True

abstract unwrap() → gluonts.maybe.T

Assert that the value is not None.

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

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

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

>>> Some(1).unwrap_or(2)
1
>>> Nothing.unwrap_or(2)
2

abstract 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.

>>> Some([1, 2, 3]).unwrap_or_else(list)
[1, 2, 3]
>>> Nothing.unwrap_or_else(list)
[]

abstract xor(other: Union[gluonts.maybe.T, None, Maybe[T]]) → gluonts.maybe.Maybe[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)

abstract zip(other: Union[gluonts.maybe.U, None, Maybe[T]]) → gluonts.maybe.Maybe[Tuple[gluonts.maybe.T, gluonts.maybe.U]]

Abstract zip.

abstract zip_with(other: Union[gluonts.maybe.U, None, Maybe[T]], fn: Callable[[gluonts.maybe.T, gluonts.maybe.U], gluonts.maybe.R]) → gluonts.maybe.Maybe[gluonts.maybe.R]

Apply function to two optional values, if neither of them is None:

>>> add = lambda left, right: left + right
>>> Some(1).zip_with(2, add)
Some(3)
>>> Some(1).zip_with(None, add)
Nothing
>>> Nothing.zip_with(2, add)
Nothing

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

Bases: gluonts.maybe.Maybe[gluonts.maybe.T]

and_(other: Union[gluonts.maybe.U, None, Maybe[T]]) → gluonts.maybe.Maybe[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.

>>> Some(1).and_(2)
Some(2)
>>> Some(1).and_(None)
Nothing
>>> Nothing.and_(2)
Nothing

and_then(fn: Callable[Concatenate[T, P], OptionalOrMaybe[U]], *args: P.args, **kwargs: P.kwargs) → 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.

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

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

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

>>> Some(1).contains(1)
True
>>> Some(1).contains(2)
False
>>> Nothing.contains(3)
False

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

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

>>> Some("a").do(print)
a
Some('a')
>>> Nothing.do(print)
Nothing

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

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

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

filter(pred: Callable[[gluonts.maybe.T], bool]) → gluonts.maybe.Maybe[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
>>> Some(1).filter(is_even)
Nothing
>>> Some(2).filter(is_even)
Some(2)
>>> Nothing.filter(is_even)
Nothing

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

Flatten nested optional value.

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

is_some()

iter() → List[gluonts.maybe.T]

Wrap val into a list, if it is not None.

Allows to use for loops on optional values.

map(fn: Callable[[gluonts.maybe.T, gluonts.maybe.P], gluonts.maybe.U], *args, **kwargs) → gluonts.maybe.Maybe[gluonts.maybe.U]

Apply fn to val if val is not None.

>>> Some(1).map(lambda x: x + 1)
Some(2)
>>> Nothing.map(lambda x: x + 1)
Nothing

Allows to pass additional arguments that are passed to fn:

>>> Some(10).map(divmod, 3)
Some((3, 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.

>>> Some(["x"]).map_or(len, 0)
1
>>> Nothing.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.

>>> Some(1).map_or_else(lambda n: [n], list)
[1]
>>> Nothing.map_or_else(lambda n: [n], list)
[]

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

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

>>> Some(1).or_(2)
Some(1)
>>> Some(1).or_(None)
Some(1)
>>> Nothing.or_(2)
Some(2)

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

Like unwrap_or_else, except that it returns an optional value.

>>> Some([42]).or_else(list)
Some([42])
>>> Nothing.or_else(list)
Some([])

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

Turn Maybe[T] into Optional[T].

>>> Some(1).unbox()
1
>>> Some(None).unbox() is None
True

unwrap() → gluonts.maybe.T

Assert that the value is not None.

>>> Some(1).unwrap()
1
>>> Nothing.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.

>>> Some(1).unwrap_or(2)
1
>>> Nothing.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.

>>> Some([1, 2, 3]).unwrap_or_else(list)
[1, 2, 3]
>>> Nothing.unwrap_or_else(list)
[]

val: gluonts.maybe.T

xor(other: Union[gluonts.maybe.T, None, Maybe[T]]) → gluonts.maybe.Maybe[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)

zip(other: Union[gluonts.maybe.U, None, Maybe[T]]) → gluonts.maybe.Maybe[Tuple[gluonts.maybe.T, gluonts.maybe.U]]

Abstract zip.

zip_with(other: Union[gluonts.maybe.U, None, Maybe[T]], fn: Callable[[gluonts.maybe.T, gluonts.maybe.U], gluonts.maybe.R]) → gluonts.maybe.Maybe[gluonts.maybe.R]

Apply function to two optional values, if neither of them is None:

>>> add = lambda left, right: left + right
>>> Some(1).zip_with(2, add)
Some(3)
>>> Some(1).zip_with(None, add)
Nothing
>>> Nothing.zip_with(2, add)
Nothing

gluonts.maybe.and_(val: Union[gluonts.maybe.T, None, Maybe[T]], other: Union[gluonts.maybe.U, None, Maybe[T]]) → 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: OptionalOrMaybe[T], fn: Callable[Concatenate[T, P], OptionalOrMaybe[U]], *args: P.args, **kwargs: P.kwargs) → Optional[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.box(val: Union[gluonts.maybe.T, None, Maybe[T]]) → gluonts.maybe.Maybe[gluonts.maybe.T]

Turn Optional[T] into Maybe[T].

gluonts.maybe.contains(val: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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.iter(val: Union[gluonts.maybe.T, None, Maybe[T]]) → List[gluonts.maybe.T]

Wrap val into a list, if it is not None.

Allows to use for loops on optional values.

gluonts.maybe.map(val: OptionalOrMaybe[T], fn: Callable[Concatenate[T, P], U], *args: P.args, **kwargs: P.kwargs) → Optional[U]

Apply fn to val if val is not None.

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

Allows to pass additional arguments that are passed to fn:

>>> map(10, divmod, 3)
(3, 1)

gluonts.maybe.map_or(val: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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.unbox(val: Union[gluonts.maybe.T, None, Maybe[T]]) → Optional[gluonts.maybe.T]

Turn Optional[T] into Maybe[T].

gluonts.maybe.unwrap(val: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, 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: Union[gluonts.maybe.T, None, Maybe[T]], other: Union[gluonts.maybe.T, None, 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)

gluonts.maybe.zip(val: Union[gluonts.maybe.T, None, Maybe[T]], other: Union[gluonts.maybe.U, None, Maybe[T]]) → Optional[Tuple[gluonts.maybe.T, gluonts.maybe.U]]

Return tuple of (val, other) if neither is None, otherwise return None.

gluonts.maybe.zip_with(val: Union[gluonts.maybe.T, None, Maybe[T]], other: Union[gluonts.maybe.U, None, Maybe[T]], fn: Callable[[gluonts.maybe.T, gluonts.maybe.U], gluonts.maybe.R]) → Optional[gluonts.maybe.R]

Apply function to two optional values, if neither of them is None:

>>> add = lambda left, right: left + right
>>> zip_with(1, 2, add)
3
>>> zip_with(1, None, add)
>>> zip_with(None, 2, add)