cadrumo.core.type_guards module

Runtime narrowing predicates for untrusted, unparameterised containers.

A bare isinstance(value, dict) narrows to an unparameterised dict, so every key and value the caller then touches is Unknown to a type checker. That is not a checker quirk to be silenced: the check genuinely proves only “this is a mapping”, and these predicates say the rest – the entries are untrusted object until something validates them.

The predicates exist here rather than beside each caller because the same three shapes are needed wherever a deserialised payload, a parsed TOML root, or a third-party return value is walked. Before this module the pattern was copied into five places under two different names.

is_str_keyed_mapping is deliberately NOT here: the two copies in domain/iva assert string keys because their input came from rtoml, which is a caller-specific justification rather than a general narrowing.

is_object_dict(value)

Narrow to a concrete dict with untrusted key/value entries.

Distinct from is_object_mapping() on purpose: a caller that rebuilds a dict, or that deliberately admits only the concrete type, must not silently start accepting every other mapping.

Return type:

TypeGuard[dict[object, object]]

Parameters:

value (object)

is_object_mapping(value)

Narrow to any Mapping with untrusted key/value entries.

Return type:

TypeGuard[Mapping[object, object]]

Parameters:

value (object)

is_object_list(value)

Narrow an unparameterised runtime list to untrusted entries.

Return type:

TypeGuard[list[object]]

Parameters:

value (object)

is_object_tuple(value)

Narrow an unparameterised runtime tuple to untrusted entries.

Return type:

TypeGuard[tuple[object, ...]]

Parameters:

value (object)

is_object_set(value)

Narrow an unparameterised runtime set to untrusted entries.

Return type:

TypeGuard[set[object]]

Parameters:

value (object)

is_object_list_or_tuple(value)

Narrow to a list or tuple of untrusted entries.

Deliberately not Sequence: str is a sequence, and every caller of this shape walks elements only after handling text separately.

Return type:

TypeGuard[list[object] | tuple[object, ...]]

Parameters:

value (object)

is_object_collection(value)

Narrow to any of the four unordered-or-ordered element containers.

Deliberately not Iterable: str and bytes are iterable, and every caller of this shape has already handled text and raw bytes separately.

Return type:

TypeGuard[list[object] | tuple[object, ...] | set[object] | frozenset[object]]

Parameters:

value (object)

is_object_set_or_frozenset(value)

Narrow to either set flavour with untrusted entries.

Return type:

TypeGuard[set[object] | frozenset[object]]

Parameters:

value (object)

is_str_keyed_dict(value)

Narrow to a dict whose keys are all strings, checking the keys.

Unlike the container guards above this one does real work at runtime, and it must: a caller that goes on to index by str is relying on the key type, so asserting it without looking would be a guess dressed as a proof.

Return type:

TypeGuard[dict[str, object]]

Parameters:

value (object)