`maybetype` module¶

class maybetype.Err(val: E)¶: Indicates a failed result of type E.

class maybetype.Maybe(val: T | None)¶

Wraps a value that may be T or None, providing methods for conditionally using that value or short-circuiting to None without longer checks.

and_then(func: Callable[[T], Maybe[U]]) → Maybe[U]¶: Returns the result of func (which must return a Maybe) called with the wrapped value if Some, otherwise returns Nothing.

attr(name: str, default: U | None = None, typ: type[U] | None = None) → Maybe¶

Attempts to access an attribute name on the wrapped object, returning a Some instance wrapping the the value if it exists, or Nothing otherwise.

Parameters:

name – The name of the attribute to access.
default – An optional default value to use if the attribute does not exist, returning Some(default) in that case.
typ – Specifies the generic type of the resulting Maybe. This does not affect the value’s real type at runtime; it is only used for type checkers. This is generally unnecessary if the default parameter is given, as the type will be inferred from its value.

bind(func: Callable[[T], Maybe[U]]) → Maybe[U]¶: Returns the result of func called with the wrapped value as its argument if Some, otherwise returns Nothing.

cast(typ: type[U]) → Maybe¶: Returns a reference to this instance after casting its type as Maybe[typ].

static cat(vals: Iterable[Maybe[T]]) → list[T]¶

Takes an iterable of Maybe and returns a list of the unwrapped values of all Some objects.

>>> vals = [maybe(5), maybe(None), maybe(10), maybe(None)]
>>> assert vals == [Some(5), Nothing, Some(10), Nothing]
>>> assert Maybe.cat(vals) == [5, 10]

filter(predicate: Callable[[T], bool]) → Maybe[T]¶

Returns self if Some and predicate called with this instance’s wrapped value returns True, otherwise returns Nothing.

>>> assert Some(1).filter(lambda n: n > 0).unwrap() == 1
>>> assert Some(1).filter(lambda n: n > 1) is Nothing
>>> assert Nothing.filter(lambda n: n > 1) is Nothing

flatten() → Maybe[T]¶

Returns a new Maybe[T] from a Maybe[Maybe[T]]. Only flattens one level at a time, and will raise a TypeError if called when the wrapped value is not Maybe.

Note

It’s expected that the resulting type of this method may not be correctly inferred and will return returning Maybe[Unknown]. For now, cast() can be used to specify a type for type checkers.

Raises:: TypeError – The wrapped value is not Maybe.

get(accessor: Any, typ: type[U] | None = None, *, err: bool = False, default: U | None = None) → Maybe¶

Attempts to access an item by accessor on the wrapped object if it supports __getitem__. If it does not, or if the value does not exist (list index out of range, key does not exist on a dictionary, etc.), Nothing is returned.

Parameters:

typ – Specifies the generic type of the resulting Maybe. No conversion is performed; this argument is only for typing purposes.
err – By default, IndexError and KeyError are not raised when __getitem__ is called on the wrapped value, and Nothing is returned instead. Setting err to True allows these errors to be raised as they normally would. Note that if __getitem__ did not exist on the wrapped value in the first placed (such as with Nothing), no error is raised, and Nothing is returned regardless.
default – Specifies an alternate value to return a Some of instead of returning Nothing.

inspect(func: Callable[[T], Any]) → Self¶: Calls a function with the wrapped value if Some, otherwise does nothing. Returns this instance.

map(func: Callable[[T], U]) → Maybe[U]¶: Returns a new Maybe with the result of calling func with the wrapped value of this instance if Some, otherwise returns Nothing.

ok_or(err: E) → Result[T, E]¶

Converts this Maybe[T] to a Result[T, E].

Some(v) becomes Ok(v) where v is the wrapped value, and Nothing becomes Err(err).

ok_or_else(err: Callable[[], E]) → Result[T, E]¶

Converts this Maybe[T] to a Result[T, E].

Some(v) becomes Ok(v) where v is the wrapped value, and Nothing becomes Err(err()).

reduce(other: Maybe[U], func: Callable[[T, U], R], *, strict: bool = False) → Maybe[T] | Maybe[U] | Maybe[R]¶

Reduces the values of two Maybe instances to one value returned in a new Maybe using func.

If only one of self and other is Some, that instance is returned. If neither are, Nothing is returned.

>>> assert Some(1).reduce(Some(2), lambda a, b: a + b) == Some(3)
>>> assert Some(1).reduce(Nothing, lambda a, b: a + b) == Some(1)
>>> assert Nothing.reduce(Some(2), lambda a, b: a + b) == Some(2)
>>> assert Nothing.reduce(Nothing, lambda a, b: a + b) is Nothing

Parameters:: strict – If True, returns Nothing if self and other are not both Some.

replace(new_val: T) → Maybe[T]¶: Replaces the wrapped value with new_val and returns a reference to this same instance if Some, otherwise returns Nothing.

static sequence(vals: Iterable[Maybe[T]]) → Maybe[list[T]]¶

Returns Nothing if any of vals is Nothing, otherwise returns a Some of a list of unwrapped items of vals.

>>> assert Maybe.sequence([Some(1), Some(2), Some(3)]) == Some([1, 2, 3])
>>> assert Maybe.sequence([Some(1), Nothing, Some(3)]) is Nothing

then(func: Callable[[T], U]) → U | None¶

Returns func called with this instance’s wrapped value if Some, otherwise returns None.

Parameters:: func – A Callable which takes a type of the possible wrapped value (T) and can return any type (U).

transpose() → Result[Maybe[Any], Any]¶

Transposes a Maybe of Result to a Result of Maybe.

Some(Ok(x)) becomes Ok(Some(x)), Some(Err(x)) becomes Err(x), Nothing becomes Ok(Nothing).

Note

Currently the type information of the wrapped Result can’t be known and used for the return type of this method, so it will return Result[Maybe[Any], Any]. You can use the cast() method to work around this for now.

Raises:: TypeError – The wrapped value is not Result.

static try_int(val: Any) → Maybe[int]¶: Attempts to convert val to an int, returning a Some-wrapped int if successful, or Nothing on failure.

unwrap(exc: str | Exception | Callable[[], Never] = 'unwrapped Nothing') → T¶

Returns the wrapped value if Some, otherwise raises ValueError or fails according to exc.

Parameters:: exc – The exception to raise when unwrapping Nothing. If a string is given, ValueError is raised as ValueError(exc). If an Exception object is given, it is raised. If a Callable is given, it is called with no arguments.

unwrap_or(other: T) → T¶: Returns the wrapped value if Some, otherwise returns other.

unwrap_or_else(func: Callable[[], T]) → T¶: Returns the wrapped value if Some, otherwise returns the result of calling func.

unzip() → tuple[Maybe[T], Maybe[U]]¶

Returns (Some(a), Some(b)) if the wrapped value is a tuple of two items. If Nothing, (Nothing, Nothing) is returned. Otherwise, TypeError is raised.

Raises:: TypeError – The wrapped value is not a 2-tuple.

xor(other: Maybe[T]) → Maybe[T]¶: Returns Some if exactly one of self and other is Some, otherwise returns Nothing.

zip(other: Maybe[U]) → Maybe[tuple[T, U]]¶: Returns a wrapped tuple of this and another Maybe instance’s wrapped values if both are Some, otherwise returns Nothing.

class maybetype.NothingType(_: None = None)¶

class maybetype.Ok(val: T)¶: Indicates a successful result of type T.

class maybetype.Result(val: T | E)¶

A class which wraps a value of T if the instance is of the subclass Ok, or wraps E if Err. The Result class itself should only be using for type annotations and not instancing; use the Ok and Err constructors otherwise.

Ok instances are always truthy, while Err instances are always falsy.

and_then(func: Callable[[T], Result[U, E]]) → Result[U, E]¶: Returns func called with the wrapped value if Ok, otherwise returns this instance.

cast(t_type: type[U], e_type: type[F]) → Result¶: Returns a reference to this instance after casting its type as Result[t_type, e_type].

err() → Maybe[E]¶: Returns a Some with the wrapped value if Err, otherwise returns Nothing.

flatten() → Result[T, E]¶

Returns a new Result[T, E] from a``Result[Result[T, E], E]``. Only flattens one level at a time, and will raise a TypeError if called when the wrapped value is not Result.

Note

It’s expected that the resulting type of this method may not be correctly inferred and will return returning Result[Unknown, Unknown]. For now, cast() can be used to specify a type for type checkers.

Raises:: TypeError – The wrapped value is not Result.

inspect(func: Callable[[T], Any]) → Self¶: Calls a function with the wrapped value if Ok, otherwise does nothing. Returns this instance.

inspect_err(func: Callable[[E], Any]) → Self¶: Calls a function with the wrapped value if Err, otherwise does nothing. Returns this instance.

map(func: Callable[[T], U]) → Result[U, E]¶: Returns a new Result with func mapped onto an Ok value, leaving an Err unmodified.

map_err(func: Callable[[E], F]) → Result[T, F]¶: Returns a new Result with func mapped onto an Err value, leaving an Ok unmodified.

map_or(default: U, func: Callable[[T], U]) → U¶: Returns func mapped onto the wrapped value if Ok, otherwise returns default.

map_or_else(default: Callable[[E], U], func: Callable[[T], U]) → U¶: Returns func mapped onto the wrapped value if Ok, otherwise applying default to the Err value and returning that.

ok() → Maybe[E]¶: Returns a Some with the wrapped value if Ok, otherwise returns Nothing.

transpose() → Maybe[Result[T, E]]¶

Transposes a Result of Maybe to a Maybe of Result.

Ok(Nothing) becomes Nothing, Ok(Some(x)) becomes Some(Ok(x)), and Err(x) becomes Some(Err(x)).

Raises:: TypeError – This is an Ok instance and the wrapped value is not Maybe.

unwrap(exc: str | type[Exception] | Callable[[E], Never] = <class 'maybetype.errors.ResultUnwrapError'>) → T¶

Returns the wrapped value if Ok, otherwise raises an error according to exc with the wrapped value as the passed argument if exc is callable.

Parameters:: exc – If None, a ResultUnwrapError is raised with the wrapped value as the exception message. If given a string, ResultUnwrapError is raised with the message format {msg}: {repr(val)}, where val is the wrapped Err value. If given an Exception type, that type of exception is raised with the wrapped value as the exception argument. If given a Callable, exc is called with the wrapped value as the passed argument.

unwrap_err(exc: str | type[Exception] | Callable[[E], Never] = <class 'maybetype.errors.ResultUnwrapError'>) → E¶

Returns the wrapped value if Err, otherwise raises an error according to exc with the wrapped value as the passed argument if exc is callable.

Parameters:: exc – If None, a ResultUnwrapError is raised with the wrapped value as the exception message. If given a string, ResultUnwrapError is raised with the message format {msg}: {repr(val)}, where val is the wrapped Ok value. If given an Exception type, that type of exception is raised with the wrapped value as the exception argument. If given a Callable, exc is called with the wrapped value as the passed argument.

unwrap_or(default: T) → T¶: Returns the wrapped value if Ok, otherwise returns default.

unwrap_or_else(func: Callable[[E], T]) → T¶: Returns the wrapped value if Ok, otherwise calls func with the wrapped Err value and returns its result.

class maybetype.Some(val: T)¶

maybetype.maybe(val: T | None, predicate: ~collections.abc.Callable[[T], bool] = <function <lambda>>) → Maybe¶

Returns a Some instance wrapping val if either val is not None or predicate(val) is True, otherwise returns the Nothing singleton.

Parameters:

val – A value to wrap.
predicate – A function that must return True for predicate(val) in addition to val not being None in order for a Some to be returned; maybe(val, predicate) is then effectively shorthand for maybe(val).filter(predicate).

maybetype module¶

`maybetype` module¶