API reference

NullableOptional = typing.Union[Optional[_T], Optional[None]] module-attribute

A nullable optional.

This is just an alias to typing.Union[Optional[_T], Optional[None]].

Empty

Bases: Optional[Any]

Represents an optional empty value.

This is ideal to put in function argument default values as this object does not hold any data and therefore is not mutable.

Usage example:

from optional import Optional, Empty, Of


def multiply(optional_value: Optional[int]=Empty(), multiplier: Optional[int]=Empty()) -> int:
    return optional_value.or_else(2).value * multiplier.or_else(2).value

Of

Bases: Optional[_T], Generic[_T]

An optional value wrapper.

This is an optional value wrapping a concrete value.

Example usage:

from optional import Optional, Empty, Of

def update_something(entity_id: int, *, name: Optional[str]=Empty())->bool:
    if name:
        print(f"Setting name to {name.value}")
        return True
    return False

update_something(1, name=Of("Karl"))

Note that this is not like the python None value. This can hold None values too

Parameters:

Name	Type	Description	Default
value	_T	The value to wrap	required

Optional

Bases: ABC, Generic[_T]

Represents an optional value.

See the of and empty classes.

has_value: bool abstractmethod property

Get wether this object has a value in it.

If the value is not present, an exception is raised.

Returns:

Name	Type	Description
True	bool	If the value is present
False	bool	If the Optional object is empty

is_empty: bool property

Get wether this instance is empty

This just returns the opposite of has_value.

Returns:

Type	Description
bool	True if the value is not present, False otherwise

value: _T abstractmethod property

Get the wrapped value.

Raises:

Type	Description
ValueNotProvidedError	If the value were not provided

Returns:

Name	Type	Description
_T	_T	The wrapped value

apply(func, *, if_empty=None)

Call a function if the value is present.

Parameters:

Name	Type	Description	Default
func	Callable[[_T], None]	The code to call if the value is present	required
if_empty	Union[Callable[[], None], None]	The function to be called if the value is not present.	None

apply_async(func, *, if_empty=None) async

Call an async function if the value is present.

Parameters:

Name	Type	Description	Default
func	Callable[[_T], Awaitable[None]]	The async function to call	required
if_empty	Union[Callable[[], Awaitable[None]], None]	The function to be called if the value is not present.	None

empty() staticmethod

Build an empty Optional object.

This method is deprecated. Use Empty class directly.

Returns:

Type	Description
Optional[Any]	An empty optional instance

map(mapper)

Build a value mapper.

The returned value is another Optional implementation that runs the mapper function.

The provided callable is run once for every instance and after the value has been mapped it is cached on the object.

For example:

>>> from optional import Optional
>>> opt=Optional.of(33).map(lambda x: x*2)
>>> opt.value
66
>>>

Parameters:

Name	Type	Description	Default
mapper	Callable[[_T], _TR]	The mapper function	required

Returns:

Type	Description
Optional[_TR]	A new Optional object

of(value) staticmethod

Build an Optional object.

This method is deprecated. Use Of class directly.

Parameters:

Name	Type	Description	Default
value	Any	The value to wrap	required

Returns:

Type	Description
Optional[Any]	The [Optional] wrapper.

or_else(value)

Return an optional value wrapping this.

If this optional has a value, the value is returned. Otherwise, the supplied value is returned from the returned object's value property.

Parameters:

Name	Type	Description	Default
value	_T	The value to retrieve if the instance is empty	required

Returns:

Type	Description
Optional[_T]	The Optional object wrapping this

OptionalProperty

Bases: Generic[_V]

An optional property.

This construct holds a value only if was set. Otherwise, a callable object supplies the default value.

Example usage

>>> from optional import OptionalProperty

>>> class Foo:
...     @OptionalProperty
...     def my_property(self):
...         return "default"

>>> obj=Foo()
>>> # Get the default value
>>> obj.my_property
'default'
>>> # Check wether the value is present
>>> Foo.my_property.is_present(obj)
False
>>> # Set another value and retrieve it
>>> obj.my_property="other"
>>> obj.my_property
'other'
>>> Foo.my_property.is_present(obj)
True
>>> # Just use python syntax to restore to the default value
>>> del obj.my_property
>>> obj.my_property
'default'

The type parameter _V if the type accepted and returned by the property.

is_present(obj)

Check wether the property was set.

Parameters:

Name	Type	Description	Default
obj	object	The object to check	required

Returns:

Type	Description
bool	True if the property was set. Otherwise returns False

raw(obj)

Retrieve the raw optional object.

Parameters:

Name	Type	Description	Default
obj	Any	Theobject to check	required

Returns:

Type	Description
Optional[_V]	The raw optional object powering the property.

ValueNotProvidedError

Bases: Exception

Raised if a value were not provided to an optional object.

optionalproperty(func)

Alias for OptionalProperty.

Parameters:

Name	Type	Description	Default
func	Callable[[Any], _V]	The default value supplier.	required

Returns:

Type	Description
OptionalProperty[_V]	An optional property construct.