API

Package absence

Sentinel for absent values.

Sentinel is distinct from None. Package als has support for creating package-specific absence sentinels. Particularly useful in contexts where None is a valid value but you need to detect the absence of a value.

Module absence.objects

Absence sentinel factory, global singleton, and helper functions.

absence.objects.absent: absence.objects.AbsentSingleton = absence.absent

type absence.objects.Absential = absence.objects._V | absence.objects.AbsentSingleton

class absence.objects.AbsenceFactory(repr_function=None, str_function=None)

Bases: Falsifier

Produces arbitrary absence sentinels.

class absence.objects.AbsentSingleton

Bases: AbsenceFactory

Produces global absence sentinel.

absence.objects.is_absence(value)

Checks if value is an absence sentinel.

Parameters:

value (object)

Return type:

typing_extensions.TypeIs[ absence.objects.AbsenceFactory ]

absence.objects.is_absent(value)

Checks if value is the global absence sentinel.

Parameters:

value (object)

Return type:

typing_extensions.TypeIs[ absence.objects.AbsentSingleton ]

absence.objects.is_present(value)

Checks if value is present (not the global absent sentinel).

Parameters:

value (absence.objects._V | absence.objects.AbsentSingleton)

Return type:

typing_extensions.TypeIs[ absence.objects._V ]

Module absence.cell

Immutable container wrapping Absential[T] with conditional API.

class absence.cell.AbsenceCell(value=absence.absent)

Bases: Generic[_T]

Wraps an Absential[T] value with a rich conditional API.

Provides safe extraction, evaluation, transformation, and chaining for values that may be absent, without requiring manual boolean checks or repeated is_absent guards.

evaluate_or(func, default)

Applies func to value, or returns default if cell is empty.

Parameters:

• self

• func (collections.abc.Callable[ [ absence.cell._T ], absence.cell._R ]) – Function applied to contained value.

• default (absence.cell._R) – Result for empty cells.

Return type:

absence.cell._R

evaluate_or_false(predicate)

Applies predicate, returning False if cell is empty.

Parameters:

• self

• predicate (collections.abc.Callable[ [ absence.cell._T ], bool ]) – Predicate applied to contained value.

Return type:

bool

evaluate_or_true(predicate)

Applies predicate, returning True if cell is empty.

Parameters:

• self

• predicate (collections.abc.Callable[ [ absence.cell._T ], bool ]) – Predicate applied to contained value.

Return type:

bool

extract()

Extracts the contained value.

Raises CellStateError if cell is empty.

Parameters:

self

Return type:

absence.cell._T

extract_or(default)

Extracts value, or returns default if cell is empty.

Parameters:

• self

• default (absence.cell._T) – Fallback for empty cells.

Return type:

absence.cell._T

extract_or_compute(factory)

Extracts value, or returns factory() if cell is empty.

Parameters:

• self

• factory (collections.abc.Callable[ [ ], absence.cell._T ]) – Factory called for empty cells.

Return type:

absence.cell._T

classmethod from_optional(value, none_is_absent=True)

Creates cell from Optional[T], bridging None semantics.

When none_is_absent is True (default), None produces an empty cell. When False, None is stored as an occupied value.

Parameters:

• cls

• value (absence.cell._T | None) – Optional value to bridge.

• none_is_absent (bool) – Whether None produces empty cell.

Return type:

typing_extensions.Self

is_absent()

Checks if cell contains the absent sentinel.

Parameters:

self

Return type:

bool

is_present()

Checks if cell contains a present value.

Parameters:

self

Return type:

bool

or_else(alternative)

Returns self if occupied, or alternative if empty.

Parameters:

• self

• alternative (AbsenceCell[ _T ]) – Cell returned if self is empty.

Return type:

AbsenceCell[ _T ]

to_optional()

Returns value if occupied, or None if cell is empty.

Parameters:

self

Return type:

absence.cell._T | None

transform(func)

Returns new cell with func applied, or empty cell.

Parameters:

• self

• func (collections.abc.Callable[ [ absence.cell._T ], absence.cell._R ]) – Function applied to contained value.

Return type:

AbsenceCell[ _R ]

Module absence.installers

Convenience to expose global sentinel and sentinel checker in builtins.

absence.installers.install(sentinel_name='Absent', predicate_name='isabsent')

Installs absence sentinel and predicate as builtins.

Parameters:

• sentinel_name (str | None) – Name to use for sentinel in builtins. None to skip.

• predicate_name (str | None) – Name to use for predicate in builtins. None to skip.

Module absence.exceptions

Family of exceptions for package API.

exception absence.exceptions.CellStateError

Bases: Omnierror, ValueError

Attempt to interact with cell in incompatible state.

exception absence.exceptions.Omnierror(*posargs, **nomargs)

Bases: Omniexception, Exception

Base for error exceptions raised by package API.

exception absence.exceptions.Omniexception(*posargs, **nomargs)

Bases: BaseException, Object

Base for all exceptions raised by package API.

exception absence.exceptions.OperationValidityError(name)

Bases: Omnierror, RuntimeError, TypeError

Attempt to perform invalid operation.