mixle.utils.exact module

Exact scalar validation for public option flags – no truthiness coercion.

bool("false") is True. Any public boundary that reads a caller-supplied flag with bool(value) or a bare if value: therefore ENABLES the feature when handed the string that names its opposite, which is exactly the form a flag arrives in when it comes from serialized configuration, an environment variable, a CLI argument, or a JSON payload (MXR-080-1907).

Two levels, because two different things are at stake:

  • require_exact_bool() – for ordinary semantic flags (graph directedness, maximize/minimize, normalization, approximation permission). A non-Boolean is a caller error, not something to coerce, because coercion silently changes what the computation means.

  • require_explicit_true() – for a gate whose “yes” authorizes code execution or another irreversible act. Here even True-like is not enough: the caller must pass the True singleton itself, so that no value which merely evaluates truthy can open the gate. This is the contract mixle.data.encoded_io.load_encoded() uses for its unpickle gate (MXR-080-1873/1881).

require_exact_bool(value, name)[source]

Return value as a bool, or raise TypeError if it is not actually Boolean.

np.bool_ is accepted and canonicalized – it is a genuine Boolean, and rejecting it would refuse values the library’s own array paths produce. Everything else, including 0/1 and any non-empty string, is refused.

Parameters:
Return type:

bool

require_explicit_true(value, name, *, because)[source]

Raise unless value is the True singleton.

For gates that authorize code execution or another act that cannot be taken back. Truthiness is not enough and neither is equality: 1 == True and np.True_ == True, so an == True test still admits a value the caller never meant as consent. because states what is being authorized and appears in the error, so a caller who hits it learns what they would be agreeing to rather than only that a flag was rejected.

Parameters:
Return type:

None