Skip to content

API reference

The generated reference documents the public declaration, operations, constructs, adapters, and errors.

Python API

betwixt

Adapter

Bases: Protocol

Adapt one boundary model to the operations required by a Betwixt mapping.

An adapter
  • defines the model's canonical Python fields and annotations
  • reads values from an existing instance
  • extracts values from a projection
  • constructs a native instance from translated values
  • reports which fields must be present for construction.

Adapters keep Betwixt independent of any particular dataclass, validation, or persistence library while leaving native construction and validation at the model boundary.

AdapterError

Bases: BetwixtError

Report an adapter lookup or configuration error.

AdapterRegistry

Resolve exact, MRO, and built-in adapters in deterministic order.

lookup 
lookup(type_: type[Any]) -> Any

Resolve an adapter using exact registration, MRO, then built-ins.

register 
register(
    type_: type[Any], adapter: Any, *, replace: bool = False
) -> None

Register adapter for type_, rejecting accidental replacement.

Betwixt

Bases: ABC

Declare and execute a bidirectional mapping between two structured types.

Concrete subclasses define left and right, then define (L, R) = field_refs(left, right) in the class body before using those proxies in mapping constructs.

explain_leftward 
explain_leftward() -> MappingExplanation

Return a declaration-only leftward explanation.

explain_rightward 
explain_rightward() -> MappingExplanation

Return a declaration-only rightward explanation.

leftward 
leftward(value: Any, *, context: Any = None) -> Any

Translate a right instance into a left instance.

leftward_partial 
leftward_partial(
    value: Mapping[str, Any], *, context: Any = None
) -> dict[str, Any]

Translate a sparse right patch into a sparse left patch.

rightward 
rightward(value: Any, *, context: Any = None) -> Any

Translate a left instance into a right instance.

rightward_partial 
rightward_partial(
    value: Mapping[str, Any], *, context: Any = None
) -> dict[str, Any]

Translate a sparse left patch into a sparse right patch.

BetwixtError

Bases: Buzz

Base class for Betwixt-owned errors.

Construct dataclass

Represent one declarative mapping construct.

DataclassAdapter

Adapt a standard-library dataclass without adding coercion.

construct 
construct(values: Mapping[str, Any]) -> Any

Construct the destination through its native constructor.

fields 
fields() -> dict[str, Any]

Return canonical field annotations.

project 
project(value: Any) -> Mapping[str, Any]

Validate and read a projected dataclass through its native boundary.

read 
read(value: Any, name: str) -> Any

Read a canonical dataclass attribute.

required 
required(name: str) -> bool

Return whether native construction requires name.

DeclarationError

Bases: BetwixtError

Report an invalid mapping declaration.

ExpansionError

Bases: DeclarationError

Report an expansion callable returning an invalid shape.

FieldRef dataclass

Identify one canonical field on one declared side.

MappingEntry dataclass

Describe one destination field in a mapping report.

MappingExplanation

Describe a mapping without reading or constructing values.

__iter__ 
__iter__()

Iterate over report entries.

MissingAdapterError

Bases: AdapterError

Report a type whose optional adapter is unavailable.

PartialInputError

Bases: BetwixtError

Report malformed partial-operation input.

TypedDictAdapter

Adapt a TypedDict as a plain mapping boundary without runtime coercion.

construct 
construct(values: Mapping[str, Any]) -> dict[str, Any]

Construct a plain dictionary from translated canonical values.

fields 
fields() -> dict[str, Any]

Return canonical field annotations, including inherited fields.

project 
project(value: Any) -> Mapping[str, Any]

Validate and copy a projected mapping through the TypedDict boundary.

read 
read(value: Any, name: str) -> Any

Read a canonical key from a TypedDict mapping.

required 
required(name: str) -> bool

Return whether native TypedDict construction requires name.

UnloadedFieldError

Bases: AdapterError

Report an unloaded native field.

UnmappedFieldError

Bases: BetwixtError

Report a required destination field with no produced value.

__init__ 
__init__(
    message: str,
    *,
    direction: str | None = None,
    source_type: type[object] | None = None,
    destination_type: type[object] | None = None,
    source_field: str | None = None,
    destination_field: str | None = None,
    source_annotation: object = None,
    destination_annotation: object = None,
    omission_reason: str | None = None,
    explanation: str | None = None,
    remedies: tuple[str, ...] = (),
) -> None

Store the mapping contract details needed to correct an omission.

disable_implicit_leftward 

disable_implicit_leftward(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping from a right field to a left field.

disable_implicit_pairwise 

disable_implicit_pairwise(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping for a field pair in both directions.

disable_implicit_rightward 

disable_implicit_rightward(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping from a left field to a right field.

expand_leftward 

expand_leftward(
    *,
    right: FieldRef,
    left: tuple[FieldRef, ...],
    leftward: Any,
) -> Construct

Expand one right-side source value into multiple left-side fields.

expand_rightward 

expand_rightward(
    *,
    left: FieldRef,
    right: tuple[FieldRef, ...],
    rightward: Any,
) -> Construct

Expand one left-side source value into multiple right-side fields.

field_refs 

field_refs(
    left: type[Any], right: type[Any]
) -> tuple[FieldProxy, FieldProxy]

Return typed proxies for the left and right declaration types.

get_adapter 

get_adapter(type_: type[Any]) -> Any

Resolve an adapter from the process-local registry.

map_leftward 

map_leftward(
    *,
    right: FieldRef | tuple[FieldRef, ...],
    left: FieldRef,
    leftward: Any,
) -> Construct

Map referenced right fields to one left field.

map_pairwise 

map_pairwise(
    *,
    left: FieldRef | tuple[FieldRef, ...],
    right: FieldRef,
    rightward: Any,
    leftward: Any,
) -> Construct

Map referenced fields with independent callables in both directions.

map_rightward 

map_rightward(
    *,
    left: FieldRef | tuple[FieldRef, ...],
    right: FieldRef,
    rightward: Any,
) -> Construct

Map referenced left fields to one right field.

nested_leftward 

nested_leftward(
    *,
    right: FieldRef,
    left: FieldRef,
    via: Any,
    leftward: Any,
    context_leftward: Any = None,
) -> Construct

Map one nested value from right to left through another Betwixt declaration.

nested_pairwise 

nested_pairwise(
    *,
    left: FieldRef,
    right: FieldRef,
    via: Any,
    rightward: Any,
    leftward: Any,
    context_rightward: Any = None,
    context_leftward: Any = None,
) -> Construct

Map one nested value in both directions through another Betwixt declaration.

nested_rightward 

nested_rightward(
    *,
    left: FieldRef,
    right: FieldRef,
    via: Any,
    rightward: Any,
    context_rightward: Any = None,
) -> Construct

Map one nested value from left to right through another Betwixt declaration.

project_leftward 

project_leftward(*, leftward: Any) -> Construct

Project a complete right object into a left object.

project_rightward 

project_rightward(*, rightward: Any) -> Construct

Project a complete left object into a right object.

reduce_leftward 

reduce_leftward(
    *, left: FieldRef, leftward: Any
) -> Construct

Reduce a complete right object to one left field.

reduce_rightward 

reduce_rightward(
    *, right: FieldRef, rightward: Any
) -> Construct

Reduce a complete left object to one right field.

register_adapter 

register_adapter(
    type_: type[Any], adapter: Any, *, replace: bool = False
) -> None

Register an adapter in the process-local registry.

betwixt.constructs

Declarative construct factories.

map_pairwise 

map_pairwise(
    *,
    left: FieldRef | tuple[FieldRef, ...],
    right: FieldRef,
    rightward: Any,
    leftward: Any,
) -> Construct

Map referenced fields with independent callables in both directions.

reduce_rightward 

reduce_rightward(
    *, right: FieldRef, rightward: Any
) -> Construct

Reduce a complete left object to one right field.

reduce_leftward 

reduce_leftward(
    *, left: FieldRef, leftward: Any
) -> Construct

Reduce a complete right object to one left field.

project_rightward 

project_rightward(*, rightward: Any) -> Construct

Project a complete left object into a right object.

project_leftward 

project_leftward(*, leftward: Any) -> Construct

Project a complete right object into a left object.

nested_pairwise 

nested_pairwise(
    *,
    left: FieldRef,
    right: FieldRef,
    via: Any,
    rightward: Any,
    leftward: Any,
    context_rightward: Any = None,
    context_leftward: Any = None,
) -> Construct

Map one nested value in both directions through another Betwixt declaration.

nested_rightward 

nested_rightward(
    *,
    left: FieldRef,
    right: FieldRef,
    via: Any,
    rightward: Any,
    context_rightward: Any = None,
) -> Construct

Map one nested value from left to right through another Betwixt declaration.

nested_leftward 

nested_leftward(
    *,
    right: FieldRef,
    left: FieldRef,
    via: Any,
    leftward: Any,
    context_leftward: Any = None,
) -> Construct

Map one nested value from right to left through another Betwixt declaration.

disable_implicit_pairwise 

disable_implicit_pairwise(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping for a field pair in both directions.

disable_implicit_rightward 

disable_implicit_rightward(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping from a left field to a right field.

disable_implicit_leftward 

disable_implicit_leftward(
    *, left: FieldRef, right: FieldRef
) -> Construct

Disable implicit mapping from a right field to a left field.