httk.core.views

Submodules

• httk.core.views.backend
• httk.core.views.coercion
• httk.core.views.unviewing
• httk.core.views.unwrapping
• httk.core.views.view

Attributes

Coercer

Classes

Backend	Abstract base class to be subclassed into classes that keep track of alternative
View	A set of views allow manipulating data and state of a backend through different interfaces.

Functions

coerce(value, target)	Coerce value strictly: return a non-View instance of the requested target or raise.
coerce_view(value, target)	Coerce value to a target class or prototype instance, backend-aware and best-effort.
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.
unview(obj)	Shed the httk View wrapper from obj, returning a plain instance of the presented type.
unwrap(obj)	Given a Backend or a View, return the most raw representation possible, i.e., if the backend has an internal representaion -

Package Contents

class httk.core.views.Backend[BackendT: Backend](backend, **hints)

Bases: abc.ABC

Abstract base class to be subclassed into classes that keep track of alternative representations of certain types of data, all adhering to a common API interface.

The class variable backend_classes is a list of all classes that can carry the kind of data the subclass represents.

A system of “hints” are used primarily to disambiguate between multiple valid interpretations of the same input object. Unless otherwise documented for a specific backend, extra hints that do not affect this interpretation are ignored.

A set of backends are meant to be combined with a set of Views.

Concrete backends implement _backend_adopt to accept an object and return an initialized backend instance, or None to decline it. The kind hint convention is used to disambiguate between multiple valid interpretations.

Parameters:

• backend (Any) – Source value or backend being adopted by the concrete backend.

• **hints (Any) – Backend-specific initialization hints.

backend_classes: ClassVar[list[type[Backend[Any]]]]

classmethod create(obj, **hints)

Given a source data (obj) and a set of hints, create a backend from one of the alternatives in the class variable backend_classes.

By design this creation depends heavily on order of the classes in backend_classes. Each class is tried in the order they appear until one of them is successful, in the sense that their _backend_adopt returns an initialized instance. Sometimes multiple backend classes can handle the same input type. In that case, dispatch is guided by keyword arguments **hints, with the convention that:

• if a hint named kind is given, a backend class should accept the object only if it matches that kind;

• when kind matches, additional unrecognized hints may be ignored.

Parameters:

• obj (Any) – Source object to represent with a registered backend.

• **hints (Any) – Backend-selection and disambiguation hints.

Returns:

A backend that represents obj.

Raises:

TypeError – If no registered backend accepts obj and the hints.

Return type:

Self

unwrap()

Return the most raw representation possible of this backend, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Returns:

The backend’s most raw available representation.

Return type:

Any

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

httk.core.views.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

httk.core.views.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.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.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.unview(obj)

Shed the httk View wrapper from obj, returning a plain instance of the presented type.

Unlike unwrap(), which goes down to the backend’s raw source representation, unview goes sideways: it removes the httk wrapper while keeping the presentation the view exposes. The result is not promised to be a copy — it may alias the view’s (or the original input’s) storage; use the target representation’s normal copy operation when independent mutation is required. A non-View input is returned unchanged. Views that only adapt an interface and have no faithful standalone value raise TypeError.

Parameters:

obj (Any) – Value or view to shed.

Returns:

The presented value without its httk view wrapper.

Raises:

TypeError – If a view has no faithful standalone value.

Return type:

Any

httk.core.views.unwrap(obj)

Given a Backend or a View, return the most raw representation possible, i.e., if the backend has an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Parameters:

obj (Any) – Value, backend, or view to unwrap.

Returns:

The most raw available representation.

Return type:

Any

class httk.core.views.View[BackendT: httk.core.views.backend.Backend]

A set of views allow manipulating data and state of a backend through different interfaces. Hence, creating a View from a Backend, or from another View, allows to read and operate on the data through the interface of that view, even if it is not the natural representation of the underlying data.

Important: views are always meant to reference the data and state of the same underlying object, hence, e.g.:

• If a function is given an X object, and the function applies an Xvariant1View and then calls, e.g., close() via that view, the expectation should be that the original X object is also closed.

• When, e.g., a TextstreamStringView is created on an already partially read stream, only the unread data will appear through that string interface.

All backends and views of the same kind of data (X) should be combined into a type union XLike that functions use to declare they support this kind of data. Such functions should start with creating a View on the passed data, giving them access to the data in a single desired format.

Views are lazy by default: construction stores only the backend, while cached_property shadows and group fills materialize presentation state on first access. Size fills to the subset served by each backend call; validate before assigning, never read a shadowed attribute from a fill, and document why a view must remain eager. The explicit coerce_view()/coerce() paths materialize via _ensure_materialized(); laziness is for pass-through use.

unwrap()

Return the most raw representation possible of this view, i.e., if it uses a backend with an internal representaion - or if it can (possibly lossly) convert itself into a more raw representation that still would be recognized as a <Something>Like type, that representation will be returned. If this is not possible, the instance itself is returned.

Returns:

The backend’s most raw available representation.

Return type:

Any

unview()

Return the view’s presented representation as a plain, non-View instance.

Concrete views that mimic a value type override this to shed the httk wrapper; the result may alias the view’s storage (no copy is promised). The default raises TypeError, which is the correct behavior for views that only adapt an interface and have no faithful standalone value.

Returns:

The presented value as a plain, non-View instance.

Raises:

TypeError – If this interface-only view has no standalone plain value.

Return type:

Any