Skip to content

graflo.architecture.schema.compare

Graded comparison of a stated value with a stored one, under a field's match.

A comparison yields a level, never agree/contradict:

  • exact: equal after the field's normalizer (or coerce_value without one);
  • compatible: one is a less specific form of the other, as the field's match.parts defines it -- a leading run of parts (general_first), a trailing run (specific_first) or a subset (unordered);
  • differs: neither, and not evidence against;
  • conflict: neither, on an exclusive field -- the one level that vetoes;
  • unknown: a value is missing on either side.

Nothing here knows what a field means; the schema that declares it does. Pure, and reads no database.

Attributes

LEVEL_ORDER = {'exact': 0, 'compatible': 1, 'differs': 2, 'conflict': 3, 'unknown': 4} module-attribute

MatchLevel = Literal['exact', 'compatible', 'differs', 'conflict', 'unknown'] module-attribute

Classes

Functions:

compare_value(field, stated, stored, *, keyed)

The level of stated against stored for field.

A list on either side is compared member by member, and the best level wins. keyed says whether the field is part of a key or an alternate key, which makes it exclusive unless its match says otherwise.

Source code in graflo/architecture/schema/compare.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def compare_value(field: Field, stated: Any, stored: Any, *, keyed: bool) -> MatchLevel:
    """The level of *stated* against *stored* for *field*.

    A list on either side is compared member by member, and the best level wins.
    *keyed* says whether the field is part of a key or an alternate key, which
    makes it ``exclusive`` unless its ``match`` says otherwise.
    """
    exclusive = is_exclusive(field, keyed=keyed)
    scalar = _scalar_field(field)
    left, right = _members(stated), _members(stored)
    if not left or not right:
        return "unknown"
    levels = [_compare_scalar(scalar, a, b, exclusive) for a in left for b in right]
    return min(levels, key=LEVEL_ORDER.__getitem__)

is_exclusive(field, *, keyed)

Whether a difference on field is a conflict.

The field's match.exclusive when declared; otherwise true exactly for a key or alternate-key field (keyed). A LIST field is never exclusive unless it says so.

Source code in graflo/architecture/schema/compare.py 
37
38
39
40
41
42
43
44
45
46
def is_exclusive(field: Field, *, keyed: bool) -> bool:
    """Whether a difference on *field* is a ``conflict``.

    The field's ``match.exclusive`` when declared; otherwise true exactly for a
    key or alternate-key field (*keyed*). A LIST field is never exclusive unless
    it says so.
    """
    if field.match is not None and field.match.exclusive is not None:
        return field.match.exclusive
    return keyed and field_type_value(field.type) != FieldType.LIST.value