httk.core.views.coercion

General coercion into registered view or value classes.

Two verbs share the machinery here: coerce_view() is the backend-aware, best-effort coercion (results may be httk Views retaining their exact backend, and lossless fallbacks of another type are allowed), while coerce() is strict (the result is a non-View instance of the requested target, or TypeError).

Attributes

Coercer

Functions

register_coercer(coercer, target)	Append coercer to the registry, preserving registration order.
view_class_coercer(view_classes)	Create a coercer that tries matching view classes in view_classes order.
coerce_view(value, target)	Coerce value to a target class or prototype instance, backend-aware and best-effort.
coerce(value, target)	Coerce value strictly: return a non-View instance of the requested target or raise.

Module Contents

type httk.core.views.coercion.Coercer = Callable[[Any, type], Any | None]

httk.core.views.coercion.register_coercer(coercer, target)

Append coercer to the registry, preserving registration order.

target declares what the coercer can coerce into: a class, a tuple of classes, or typing.Any for a fully general coercer. During coerce(), a registered coercer is only tried when the requested target class is a subclass of (one of) its declared targets; Any matches every target. Invalid declarations raise TypeError eagerly.

Parameters:

• coercer (Coercer) – Conversion function to append to the registry.

• target (Any) – Class, tuple of classes, or Any accepted by the coercer.

Raises:

TypeError – If target is not a class, tuple of classes, or Any.

httk.core.views.coercion.view_class_coercer(view_classes)

Create a coercer that tries matching view classes in view_classes order.

Parameters:

view_classes (collections.abc.Sequence[type]) – View classes to try in order.

Returns:

A coercer for the supplied view classes.

Return type:

Coercer

httk.core.views.coercion.coerce_view(value, target)

Coerce value to a target class or prototype instance, backend-aware and best-effort.

The exact string "natural" is a documented sentinel that returns value unchanged. Otherwise, a class target is used directly and an instance target is treated as a prototype, using its type. Values already matching the target are returned unchanged — including httk Views that subclass the target, so the exact backend is retained. A target that is a View subclass is then tried directly as a view conversion of value, so any view family works without a registered coercer. Failing that, registered coercers whose declared targets match are tried in registration order, and the first non-None result wins. If none succeeds, TypeError is raised naming the value type and target. Coercion is best effort and favors lossless view wrapping; a coercer may return a lossless fallback of another type (e.g. Fraction(1, 2) for target int), and individual coercers document any deliberately lossy conversion. Callers that need a plain, exactly-typed result use coerce() instead.

Parameters:

• value (Any) – Value to convert.

• target (Any) – Target class, prototype instance, or the "natural" sentinel.

Returns:

The best available backend-aware conversion.

Raises:

TypeError – If no registered or direct conversion succeeds.

Return type:

Any

httk.core.views.coercion.coerce(value, target)

Coerce value strictly: return a non-View instance of the requested target or raise.

The exact string "natural" returns value unchanged (no coercion, even for a View). Otherwise the resolution of coerce_view() applies, and then: an httk View result is shed via unview() unless the requested target is itself a View class; a View result that cannot shed raises unview’s own TypeError; and the final result must satisfy isinstance(result, target) — a lossless fallback of another type (available through coerce_view()) makes strict coercion fail with TypeError. An existing non-View subtype of the target is an identity result.

Parameters:

• value (Any) – Value to convert.

• target (Any) – Target class, prototype instance, or the "natural" sentinel.

Returns:

A non-View instance matching the requested target.

Raises:

TypeError – If strict conversion cannot produce the requested target.

Return type:

Any