apfel.container.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
get_mut	/
get_mut_or_init	/
get_mut_or_try_init	/
get_or_init	get_or_init
get_or_try_init	-
into_inner	-
new	-
set	set
take	-
try_insert	-

API#

Classes

Name	Description
Lazy	A container that can be lazily initialized only once.
LazyLock	A thread-safe version of Lazy.
Once	A container that can be written only once.
OnceLock	A thread-safe version of Once.

Lazyclass#

View source

class Lazy(func: Callable[[], T], /)

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.

from apfel.container.once import Lazy

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

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

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

__slots__attributeclass attributeinstance attribute#

View source

__slots__ = ('_value', '_has_value', '_init')

__bool__method#

View source

def __bool__() -> bool

__call__method#

View source

def __call__() -> T

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

@Lazy
def func():
    return object()

obj = func()
assert func() is obj

__class_getitem__method#

View source

def __class_getitem__(item: U) -> Lazy[U]

__init__method#

View source

def __init__(func: Callable[[], T], /) -> None

Create a lazily initialized Lazy container.

Parameters

Name	Type	Description
func	Callable[[], T]	The function to be lazily initialized.

unwrapmethod#

View source

def unwrap() -> T

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

Returns

T

The lazily initialized value of the Lazy container.

Raises

ValueError

If no value has been set.

valuemethod#

View source

def value() -> T

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

Returns

T

The lazily initialized value of the Lazy container.

LazyLockclass#

View source

class LazyLock(func: Callable[[], T], /)

A thread-safe version of Lazy. See LazyCell for more information.

__slots__attributeclass attributeinstance attribute#

View source

__slots__ = ('_value', '_has_value', '_init', '_lock')

__bool__method#

View source

def __bool__() -> bool

__call__method#

View source

def __call__() -> T

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

from apfel.container.once import LazyLock

lazy_lock = LazyLock(lambda: object())
obj = lazy_lock()
assert lazy_lock() is obj

__class_getitem__method#

View source

def __class_getitem__(item: U) -> LazyLock[U]

__init__method#

View source

def __init__(func: Callable[[], T], /) -> None

Create a thread-safe lazily initialized LazyLock container.

Parameters

Name	Type	Description
func	Callable[[], T]	The function to be lazily initialized.

unwrapmethod#

View source

def unwrap() -> T

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

Returns

T

The inner value of the LazyLock container.

Raises

ValueError

If no value has been set.

valuemethod#

View source

def value() -> T

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

Returns

T

The lazily initialized value of the LazyLock container.

Onceclass#

View source

class Once()

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

This class is exposed in the package namespace.

__slots__attributeclass attributeinstance attribute#

View source

__slots__ = ('_value', '_has_value')

__bool__method#

View source

def __bool__() -> bool

Check if the Once container has been set.

Returns

bool

True if the Once container has been set, False otherwise.

__class_getitem__method#

View source

def __class_getitem__(item: U) -> Once[U]

__init__method#

View source

def __init__()

Create an unpopulated Once container.

Returns

Once

An unpopulated Once container.

getmethod#

View source

def get() -> _maybe.Maybe[T]

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

Returns

_maybe.Maybe[T]

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

get_or_initmethod#

View source

def get_or_init(func: Callable[[], T], /) -> T

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
func	Callable[[], T]	The function to initialize the Once container with if no value has been set.

Returns

T

The inner value (maybe newly set) of the Once container.

of_hintmethodclassmethod#

View source

def of_hint(type: type[U], /) -> Once[U]

Create a Once container hinting the given type.

Parameters

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

Returns

Once[U]

Once[T]: A Once container hinting the given type.

setmethod#

View source

def set(value: T) -> _result.Result[None, T]

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
value	T	The value to set the Once container to.

Returns

_result.Result[None, T]

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

unwrapmethod#

View source

def unwrap() -> T

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

Returns

T

The inner value of the Once container.

Raises

ValueError

If no value has been set.

OnceLockclass#

View source

class OnceLock()

A thread-safe version of Once. See OnceLock for more information.

__slots__attributeclass attributeinstance attribute#

View source

__slots__ = ('_value', '_has_value', '_lock')

__bool__method#

View source

def __bool__() -> bool

Check if the OnceLock container has been set.

Returns

bool

True if the OnceLock container has been set, False otherwise.

__class_getitem__method#

View source

def __class_getitem__(item: U) -> OnceLock[U]

__init__method#

View source

def __init__() -> None

Create an unpopulated OnceLock container.

Returns

OnceLockNone

An unpopulated OnceLock container.

getmethod#

View source

def get() -> _maybe.Maybe[T]

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

Returns

_maybe.Maybe[T]

Maybe[T]: A Just-wrapped inner value of the OnceLock container if it has been set, a Nothing otherwise.

get_or_initmethod#

View source

def get_or_init(func: Callable[[], T], /) -> T

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

Parameters

Name	Type	Description
func	Callable[[], T]	The function to initialize the OnceLock container with if no value has been set.

Returns

T

The inner value (maybe newly set) of the OnceLock

setmethod#

View source

def set(value: T) -> _result.Result[None, T]

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

Parameters

Name	Type	Description
value	T	The value to set the OnceLock container to.

Returns

_result.Result[None, T]

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

unwrapmethod#

View source

def unwrap() -> T

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

Returns

T

The inner value of the OnceLock container.

Raises

ValueError

If no value has been set.