httk.core.views.coercion
========================

.. py:module:: httk.core.views.coercion

.. autoapi-nested-parse::

   General best-effort coercion into registered view or value classes.



Attributes
----------

.. autoapisummary::

   httk.core.views.coercion.Coercer


Functions
---------

.. autoapisummary::

   httk.core.views.coercion.register_coercer
   httk.core.views.coercion.view_class_coercer
   httk.core.views.coercion.coerce


Module Contents
---------------

.. py:type:: Coercer
   :canonical: Callable[[Any, type], Any | None]


.. py:function:: register_coercer(coercer: Coercer) -> None

   Append ``coercer`` to the registry, preserving registration order.


.. py:function:: view_class_coercer(view_classes: collections.abc.Sequence[type]) -> Coercer

   Return a coercer that tries matching view classes in ``view_classes`` order.

   A ``TypeError``, ``ValueError``, or ``OverflowError`` from a view constructor means that view
   cannot represent the value, so construction continues with the next matching class.


.. py:function:: coerce(value: Any, target: Any) -> Any

   Coerce ``value`` to a target class or prototype instance.

   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. Registered coercers
   are then 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; individual coercers document any deliberately lossy conversion.