option package

Modules

option.option_ module

This module contains the Option class.

option.option_.NONE

Represents a None value.

class option.option_.Option(value: T, is_some: bool, *, _force: bool = False)

Bases: Generic[T]

Option represents an optional value. Every Option is either Some and contains a value, or NONE and does not.

To create a Some value, please use Option.Some() or Some().

To create a NONE value, please use Option.NONE() or import the constant NONE directly.

To let Option guess the type of Option to create, please use Option.maybe() or maybe().

Calling the __init__ method directly will raise a TypeError.

Examples:

>>> Option.Some(1)
Some(1)
>>> Option.NONE()
NONE
>>> Option.maybe(1)
Some(1)
>>> Option.maybe(None)
NONE

classmethod NONE() → Option[T]

No Value.

classmethod Some(val: T) → Option[T]

Some value val.

expect(msg: object) → T

Unwraps the option. Raises an exception if the value is NONE.

Args:

msg: The exception message.

Returns:

The wrapped value.

Raises:

ValueError with message provided by msg if the value is NONE.

Examples:

>>> Some(0).expect('sd')
0
>>> try:
...     NONE.expect('Oh No!')
... except ValueError as e:
...     print(e)
Oh No!

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

Returns NONE if the Option is NONE, otherwise filter the contained value by predicate.

Args:

predicate: The fitler function.

Returns:

NONE if the contained value is NONE, otherwise:

• The option itself if the predicate returns True

• NONE if the predicate returns False

Examples:

>>> Some(0).filter(lambda x: x % 2 == 1)
NONE
>>> Some(1).filter(lambda x: x % 2 == 1)
Some(1)
>>> NONE.filter(lambda x: True)
NONE

flatmap(callback: Callable[[T], Option[U]]) → Option[U]

Applies the callback to the contained value if the option is not NONE.

This is different than Option.map() because the result of the callback isn’t wrapped in a new Option

Args:

callback: The callback to apply to the contained value.

Returns:

NONE if the option is NONE.

otherwise calls callback with the contained value and returns the result.

Examples:

>>> def square(x): return Some(x * x)
>>> def nope(x): return NONE
>>> Some(2).flatmap(square).flatmap(square)
Some(16)
>>> Some(2).flatmap(square).flatmap(nope)
NONE
>>> Some(2).flatmap(nope).flatmap(square)
NONE
>>> NONE.flatmap(square).flatmap(square)
NONE

get(key: K, default: Optional[V] = None) → Option[V]

Gets a mapping value by key in the contained value or returns default if the key doesn’t exist.

Args:

key: The mapping key. default: The defauilt value.

Returns:

• Some variant of the mapping value if the key exists

  and the value is not None.

• Some(default) if default is not None.

• NONE if default is None.

Examples:

>>> Some({'hi': 1}).get('hi')
Some(1)
>>> Some({}).get('hi', 12)
Some(12)
>>> NONE.get('hi', 12)
Some(12)
>>> NONE.get('hi')
NONE

property is_none: bool

Returns True if the option is a NONE value.

Examples:

>>> Some(0).is_none
False
>>> NONE.is_none
True

property is_some: bool

Returns True if the option is a Some value.

Examples:

>>> Some(0).is_some
True
>>> NONE.is_some
False

map(callback: Callable[[T], U]) → Option[U]

Applies the callback with the contained value as its argument or returns NONE.

Args:

callback: The callback to apply to the contained value.

Returns:

The callback result wrapped in an Option if the contained value is Some, otherwise NONE

Examples:

>>> Some(10).map(lambda x: x * x)
Some(100)
>>> NONE.map(lambda x: x * x)
NONE

map_or(callback: Callable[[T], U], default: A) → Union[U, A]

Applies the callback to the contained value or returns default.

Args:

callback: The callback to apply to the contained value. default: The default value.

Returns:

The callback result if the contained value is Some, otherwise default.

Notes:

If you wish to use the result of a function call as default, it is recommended to use map_or_else() instead.

Examples:

>>> Some(0).map_or(lambda x: x + 1, 1000)
1
>>> NONE.map_or(lambda x: x * x, 1)
1

map_or_else(callback: Callable[[T], U], default: Callable[[], A]) → Union[U, A]

Applies the callback to the contained value or computes a default with default.

Args:

callback: The callback to apply to the contained value. default: The callback fot the default value.

Returns:

The callback result if the contained value is Some, otherwise the result of default.

Examples:

>>> Some(0).map_or_else(lambda x: x * x, lambda: 1)
0
>>> NONE.map_or_else(lambda x: x * x, lambda: 1)
1

classmethod maybe(val: Optional[T]) → Option[T]

Shortcut method to return Some or NONE based on val.

Args:

val: Some value.

Returns:

Some(val) if the val is not None, otherwise NONE.

Examples:

>>> Option.maybe(0)
Some(0)
>>> Option.maybe(None)
NONE

unwrap() → T

Returns the value in the Option if it is Some.

Returns:

The `Some value of the Option.

Raises:

ValueError if the value is NONE.

Examples:

>>> Some(0).unwrap()
0
>>> try:
...     NONE.unwrap()
... except ValueError as e:
...     print(e)
Value is NONE.

unwrap_or(default: U) → Union[T, U]

Returns the contained value or default.

Args:

default: The default value.

Returns:

The contained value if the Option is Some, otherwise default.

Notes:

If you wish to use a result of a function call as the default, it is recommnded to use unwrap_or_else() instead.

Examples:

>>> Some(0).unwrap_or(3)
0
>>> NONE.unwrap_or(0)
0

unwrap_or_else(callback: Callable[[], U]) → Union[T, U]

Returns the contained value or computes it from callback.

Args:

callback: The the default callback.

Returns:

The contained value if the Option is Some, otherwise callback().

Examples:

>>> Some(0).unwrap_or_else(lambda: 111)
0
>>> NONE.unwrap_or_else(lambda: 'ha')
'ha'

property value: T

Property version of unwrap().

option.option_.Some(val: T) → Option[T]

Shortcut function to Option.Some().

option.option_.maybe(val: Optional[T]) → Option[T]

Shortcut function to Option.maybe().

option.result module

This module contains the Result type.

option.result.Err(err: E) → Result[Any, E]

Shortcut function for Result.Err().

option.result.Ok(val: T) → Result[T, Any]

Shortcut function for Result.Ok().

class option.result.Result(val: Union[T, E], is_ok: bool, *, _force: bool = False)

Bases: Generic[T, E]

Result is a type that either success (Result.Ok()) or failure (Result.Err()).

To create an Ok value, use Result.Ok() or Ok().

To create a Err value, use Result.Err() or Err().

Calling the Result constructor directly will raise a TypeError.

Examples:

>>> Result.Ok(1)
Ok(1)
>>> Result.Err('Fail!')
Err('Fail!')

classmethod Err(err: E) → Result[Any, E]

Contains the error value.

Args:

err: The error value.

Returns:

The Result containing the error value.

Examples:

>>> res = Result.Err('Oh No')
>>> res
Err('Oh No')
>>> res.is_err
True

classmethod Ok(val: T) → Result[T, Any]

Contains the success value.

Args:

val: The success value.

Returns:

The Result containing the success value.

Examples:

>>> res = Result.Ok(1)
>>> res
Ok(1)
>>> res.is_ok
True

err() → Option[E]

Converts from Result [T, E] to option.option_.Option [E].

Returns:

Option containing the error value if self is Result.Err(), otherwise option.option_.NONE.

Examples:

>>> Ok(1).err()
NONE
>>> Err(1).err()
Some(1)

expect(msg: object) → T

Returns the success value in the Result or raises a ValueError with a provided message.

Args:

msg: The error message.

Returns:

The success value in the Result if it is a Result.Ok() value.

Raises:

ValueError with msg as the message if the Result is a Result.Err() value.

Examples:

>>> Ok(1).expect('no')
1
>>> try:
...     Err(1).expect('no')
... except ValueError as e:
...     print(e)
no

expect_err(msg: object) → E

Returns the error value in a Result, or raises a ValueError with the provided message.

Args:

msg: The error message.

Returns:

The error value in the Result if it is a Result.Err() value.

Raises:

ValueError with the message provided by msg if the Result is a Result.Ok() value.

Examples:

>>> try:
...     Ok(1).expect_err('Oh No')
... except ValueError as e:
...     print(e)
Oh No
>>> Err(1).expect_err('Yes')
1

flatmap(op: Callable[[T], Result[U, E]]) → Result[U, E]

Applies a function to the contained Result.Ok() value.

This is different than Result.map() because the function result is not wrapped in a new Result.

Args:

op: The function to apply to the contained Result.Ok() value.

Returns:

The result of the function if self is an Result.Ok() value,

otherwise returns self.

Examples:

>>> def sq(x): return Ok(x * x)
>>> def err(x): return Err(x)
>>> Ok(2).flatmap(sq).flatmap(sq)
Ok(16)
>>> Ok(2).flatmap(sq).flatmap(err)
Err(4)
>>> Ok(2).flatmap(err).flatmap(sq)
Err(2)
>>> Err(3).flatmap(sq).flatmap(sq)
Err(3)

property is_err: bool

Returns True if the result is Result.Err().

Examples:

>>> Ok(1).is_err
False
>>> Err(1).is_err
True

property is_ok: bool

Returns True if the result is Result.Ok().

Examples:

>>> Ok(1).is_ok
True
>>> Err(1).is_ok
False

map(op: Callable[[T], U]) → Union[Result[U, E], Result[T, E]]

Applies a function to the contained Result.Ok() value.

Args:

op: The function to apply to the Result.Ok() value.

Returns:

A Result with its success value as the function result if self is an Result.Ok() value, otherwise returns self.

Examples:

>>> Ok(1).map(lambda x: x * 2)
Ok(2)
>>> Err(1).map(lambda x: x * 2)
Err(1)

map_err(op: Callable[[E], F]) → Union[Result[T, F], Result[T, E]]

Applies a function to the contained Result.Err() value.

Args:

op: The function to apply to the Result.Err() value.

Returns:

A Result with its error value as the function result if self is a Result.Err() value, otherwise returns self.

Examples:

>>> Ok(1).map_err(lambda x: x * 2)
Ok(1)
>>> Err(1).map_err(lambda x: x * 2)
Err(2)

ok() → Option[T]

Converts from Result [T, E] to option.option_.Option [T].

Returns:

Option containing the success value if self is Result.Ok(), otherwise option.option_.NONE.

Examples:

>>> Ok(1).ok()
Some(1)
>>> Err(1).ok()
NONE

unwrap() → T

Returns the success value in the Result.

Returns:

The success value in the Result.

Raises:

ValueError with the message provided by the error value

if the Result is a Result.Err() value.

Examples:

>>> Ok(1).unwrap()
1
>>> try:
...     Err(1).unwrap()
... except ValueError as e:
...     print(e)
1

unwrap_err() → E

Returns the error value in a Result.

Returns:

The error value in the Result if it is a Result.Err() value.

Raises:

ValueError with the message provided by the success value

if the Result is a Result.Ok() value.

Examples:

>>> try:
...     Ok(1).unwrap_err()
... except ValueError as e:
...     print(e)
1
>>> Err('Oh No').unwrap_err()
'Oh No'

unwrap_or(optb: T) → T

Returns the success value in the Result or optb.

Args:

optb: The default return value.

Returns:

The success value in the Result if it is a Result.Ok() value, otherwise optb.

Notes:

If you wish to use a result of a function call as the default, it is recommnded to use unwrap_or_else() instead.

Examples:

>>> Ok(1).unwrap_or(2)
1
>>> Err(1).unwrap_or(2)
2

unwrap_or_else(op: Callable[[E], U]) → Union[T, U]

Returns the sucess value in the Result or computes a default from the error value.

Args:

op: The function to computes default with.

Returns:

The success value in the Result if it is

a Result.Ok() value, otherwise op(E).

Examples:

>>> Ok(1).unwrap_or_else(lambda e: e * 10)
1
>>> Err(1).unwrap_or_else(lambda e: e * 10)
10