Once

Primitives for containers that can be written only once. Inspired by OnceCell and LazyCell.

The Once and Lazy classes, are exposed in the package namespace.

Implementation

Once takes reference from OnceCell and the current status is as follows:

Reference OnceCell	Counterpart
get
get_mut
get_mut_or_init
get_mut_or_try_init
get_or_init
get_or_try_init
into_inner
new
set
take
try_insert

Once

A container that can be written only once. See OnceCell for more information.

This class is exposed in the package namespace.

__bool__()

Check if the Once container has been set.

Returns:

Name	Type	Description
is_set	bool	True if the Once container has been set, False otherwise.

__init__()

Create an unpopulated Once container.

Returns:

Name	Type	Description
container	Once	An unpopulated Once container.

get()

Get the inner value of the Once container if it has been set.

Returns:

Name	Type	Description
value	Maybe[T]	A Just-wrapped inner value of the Once container if it has been set, a Nothing otherwise.

get_or_init(f)

Get the inner value of the Once container, or initialize it with the given function if no value has been set.

Parameters:

Name	Type	Description	Default
f	Callable[[], T]	The function to initialize the Once container with if no value has been set.	required

Returns:

Name	Type	Description
value	T	The inner value (maybe newly set) of the Once container.

of_hint(type) classmethod

Create a Once container hinting the given type.

Parameters:

Name	Type	Description	Default
type	Type[T]	The type of the value to be stored in the Once container.	required

Returns:

Name	Type	Description
container	Once[T]	A Once container hinting the given type.

set(value)

Set the inner value of the Once container. If a value has already been set, this method returns an Err containing the existing value.

Parameters:

Name	Type	Description	Default
value	T	The value to set the Once container to.	required

Returns:

Name	Type	Description
result	Result[None, T]	Ok(None) if the value was set successfully. Err(value) if the value has already been set, containing the existing value.

unwrap()

Get the inner value of the Once container. If no value has been set, this method raises a ValueError.

Returns:

Name	Type	Description
value	T	The inner value of the Once container.

Raises:

Type	Description
ValueError	If no value has been set.

Lazy

A container that can be lazily initialized only once. The stored function will be actually called only on the first retrieval, and the result will be cached for consequent calls. See LazyCell for more information.

This class is exposed in the package namespace.

Example

from apfel.container.once import Lazy

@Lazy
def f():
    print("called")
    return object()

obj = f.value()
# print "called"
# here, the function `f` will be called and the result will be cached.

f.value() is obj # the function `f` will not be called again.

__call__()

An alias for Lazy.value. Notice that this operator overloading might be slower than calling value directly.

Example

@Lazy
def f():
    return object()

obj = f()
assert f() is obj

__init__(f)

Create a lazily initialized Lazy container.

Parameters:

Name	Type	Description	Default
f	Callable[[], T]	The function to be lazily initialized.	required

unwrap()

Get the inner value of the Lazy container. If no value has been set, this method raises a ValueError.

Returns:

Name	Type	Description
value	T	The lazily initialized value of the Lazy container.

Raises:

Type	Description
ValueError	If no value has been set.

value()

Get the inner value of the Lazy container. If no value has been set, this method initializes the value with the stored function.

Returns:

Name	Type	Description
value	T	The lazily initialized value of the Lazy container.