rics.mapping#

Mapping implementations for matching groups of elements.

Classes

`Cardinality`(value)	Enumeration type for cardinality relationships.
`HeuristicScore`(score_function, heuristics)	Callable wrapper for computing heuristic scores.
`DirectionalMapping`([cardinality, ...])	A two-way mapping between hashable elements.
`Mapper`([score_function, ...])	Map values and candidates.

class Cardinality(value)[source]#

Bases: Enum

Enumeration type for cardinality relationships.

Cardinalities are comparable using numerical operators, and can be thought of as comparing “preciseness”. The less ambiguity there is for a given cardinality, the smaller it is in comparison to the others. The hierarchy is given by 1:1 < 1:N = N:1 < M:N. Note that 1:N and N:1 are considered equally precise.

Examples

Comparing cardinalities

>>> from rics.mapping import Cardinality
>>> Cardinality.ManyToOne
<Cardinality.ManyToOne: 'N:1'>
>>> Cardinality.OneToOne
<Cardinality.OneToOne: '1:1'>
>>> Cardinality.ManyToOne < Cardinality.OneToOne
False

ParseType#

Types that may be interpreted as a cardinality.

alias of Union[str, Cardinality]

OneToOne = '1:1'#: One-to-one relationship.

OneToMany = '1:N'#: One-to-many relationship.

ManyToOne = 'N:1'#: Many-to-one relationship.

ManyToMany = 'M:N'#: Many-to-many relationship.

property many_left: bool#: Many-relationship on the left, True for N:1 and M:N.

property many_right: bool#: Many-relationship on the right, True for 1:N and M:N.

property one_left: bool#: One-relationship on the left, True for 1:1 and 1:N.

property one_right: bool#: One-relationship on the right, True for 1:1 and N:1.

property inverse: Cardinality#

Inverse cardinality. For symmetric cardinalities, self.inverse == self.

Returns: Inverse cardinality.

See also

inverse

classmethod from_counts(left_count: int, right_count: int) → Cardinality[source]#

Derive a Cardinality from counts.

Parameters

left_count – Number of elements on the left-hand side.
right_count – Number of elements on the right-hand side.

Returns

A Cardinality.

Raises

ValueError – For counts < 1.

classmethod parse(arg: Union[str, Cardinality], strict: bool = False) → Cardinality[source]#

Convert to cardinality.

Parameters

arg – Argument to parse.
strict – If True, arg must match exactly when it is given as a string.

Returns

A Cardinality.

Raises

ValueError – If the argument could not be converted.

class HeuristicScore(score_function: Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Iterable[float]]], heuristics: Iterable[Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Tuple[ValueType, Iterable[CandidateType]]], Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Set[CandidateType]], Tuple[Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Tuple[ValueType, Iterable[CandidateType]]], Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Set[CandidateType]]], Dict[str, Any]]]])[source]#

Bases: Generic[ValueType, CandidateType, ContextType]

Callable wrapper for computing heuristic scores.

Instances are callable. Signature is given by ScoreFunction.

Short-circuiting:

A mechanism for forced matching. Score is set to +∞ for short-circuited candidates, and -∞ for the rest. No further matching will be performed after this point, so ensure that all desired candidates are returned by chosen filters.

Procedure:

Trigger short-circuiting if there is an exact value-candidate match.
All heuristics are applied and scores are computed.
If no short-circuiting is triggered in step 2, yield max score for each candidate.

Parameters

score_function – A ScoreFunction to wrap.
heuristics – Iterable of heuristics or tuples (heuristic, kwargs) to apply to the (value, candidates) inputs to the score_function.

Heuristic types:

An AliasFunction, which accepts and returns a tuple (value, candidates) to be evaluated.
A FilterFunction, which accepts a tuple (value, candidates) and returns a subset of candidates. If any candidates are returned, short-circuiting is triggered.

Notes

Heuristic function input order = application order.
You may add mutate=True to the heuristics kwargs to forward to the modifications made by that function.

add_heuristic(heuristic: Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Tuple[ValueType, Iterable[CandidateType]]], Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Set[CandidateType]]], kwargs: Optional[Dict[str, Any]] = None) → None[source]#: Add a new heuristic.

class DirectionalMapping(cardinality: Optional[Union[str, Cardinality]] = None, left_to_right: Optional[Dict[HL, Tuple[HR, ...]]] = None, right_to_left: Optional[Dict[HR, Tuple[HL, ...]]] = None, _verify: bool = True)[source]#

Bases: Generic[HL, HR]

A two-way mapping between hashable elements.

Parameters

cardinality – Explicit cardinality. Derive if None.
left_to_right – A left-to-right mapping of elements.
right_to_left – A right-to-left mapping of elements.
_verify – If False, input checks are disabled. Intended for internal use.

Raises

ValueError – If both of left_to_right and right_to_left are None.
ValueError – If verification of two-sided input fails, and verify=True.
CardinalityError – If explicit cardinality < cardinality, and verify=True.

property cardinality: Cardinality#

Cardinality with which this mapping was created.

Returns: Cardinality with which this mapping was created.

property left: Tuple[HL, ...]#: Left-side elements in the mapping.

property right: Tuple[HR, ...]#: Right-side elements in the mapping.

property left_to_right: Dict[HL, Tuple[HR, ...]]#: Left-to-right element mappings.

property right_to_left: Dict[HR, Tuple[HL, ...]]#: Right-to-left element mappings.

property reverse: DirectionalMapping[HR, HL]#

Reverse the mapping by swapping the sides.

Returns: A copy with data identical to the calling instance, but with sides inversed compared to the caller.

flatten() → Dict[HL, HR][source]#

Return a flattened version of self as a dict.

Returns: A dict {left: right}.
Raises: CardinalityError – If cardinality is not OneToOne or ManyToOne.

select_left(elements: Iterable[HL], exclude: bool = False) → DirectionalMapping[source]#

Perform a selection on left-side elements.

Parameters

elements – Elements to select.
exclude – If True, return everything except the given elements.

Returns

A new Mapping for the selection.

Raises

KeyError – If any of the chosen elements do not exist and exclude=False.

select_right(elements: Iterable[HR], exclude: bool = False) → DirectionalMapping[source]#

Perform a selection on right-side elements.

Parameters

elements – Elements to select.
exclude – If True, return everything except the given elements.

Returns

A new instance for the selection.

Raises

KeyError – If any of the chosen elements do not exist and exclude=False.

class Mapper(score_function: Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Iterable[float]]] = 'equality', score_function_kwargs: Optional[Dict[str, Any]] = None, filter_functions: Iterable[Tuple[Union[str, Callable[[ValueType, Iterable[CandidateType], Optional[ContextType]], Set[CandidateType]]], Dict[str, Any]]] = (), min_score: float = 1.0, overrides: Optional[Union[InheritedKeysDict, Dict[ValueType, CandidateType]]] = None, unmapped_values_action: Union[Literal['ignore', 'warn', 'raise', 'IGNORE', 'WARN', 'RAISE'], ActionLevel] = 'ignore', unknown_user_override_action: Union[Literal['ignore', 'warn', 'raise', 'IGNORE', 'WARN', 'RAISE'], ActionLevel] = 'raise', cardinality: Optional[Union[str, Cardinality]] = Cardinality.ManyToOne)[source]#

Bases: Generic[ValueType, CandidateType, ContextType]

Map values and candidates.

Parameters

score_function – A callable which accepts a value k and an ordered collection of candidates c, returning a score s_i for each candidate c_i in c. Default: s_i = float(k == c_i). Higher=better match.
score_function_kwargs – Keyword arguments for score_function.
filter_functions – Function-kwargs pairs of filters to apply before scoring.
min_score – Minimum score s_i, as given by score(k, c_i), to consider k a match for c_i.
overrides – If a dict, assumed to be 1:1 mappings (value to candidate) which override the scoring logic. If InheritedKeysDict, the context passed to apply() is used to retrieve specific overrides.
unmapped_values_action – Action to take if mapping fails for any values.
unknown_user_override_action – Action to take if a UserOverrideFunction returns an unknown candidate.
cardinality – Desired cardinality for mapped values. Derive if None.

apply(values: Iterable[ValueType], candidates: Iterable[CandidateType], context: Optional[ContextType] = None, override_function: Optional[Callable[[ValueType, Set[CandidateType], Optional[ContextType]], Optional[CandidateType]]] = None, **kwargs: Any) → DirectionalMapping[ValueType, CandidateType][source]#

Map values to candidates.

Parameters

values – Iterable of elements to match to candidates.
candidates – Iterable of candidates to match with value. Duplicate elements will be discarded.
context – Context in which mapping is being done.
override_function – A callable that takes inputs (value, candidates, context) that returns either None (let the regular mapping logic decide) or one of the candidates. Unlike static overrides, override functions may not return non-candidates as matches. How non-candidates returned by override functions is handled is determined by the unknown_user_override_action property.
**kwargs – Runtime keyword arguments for score and filter functions. May be used to add information which is not known when the Mapper is initialized.

Returns

A DirectionalMapping on the form {value: (matched_candidate,)}. May be turned into a plain {value: candidate} dict by using the DirectionalMapping.flatten() function.

Raises

MappingError – If any values failed to match and unmapped_values_action='raise'.
BadFilterError – If a filter returns candidates that are not a subset of the original candidates.
UserMappingError – If func returns an unknown candidate.

property unmapped_values_action: ActionLevel#: Return the action to take if mapping fails for any values.

property unknown_user_override_action: ActionLevel#: Return the action to take if an override function returns an unknown candidate.

property context_sensitive_overrides: bool#: Return True if overrides are context sensitive.

copy() → Mapper[source]#: Make a copy of this Mapper.

Modules

`rics.mapping.exceptions`	Mapping errors.
`rics.mapping.filter_functions`	Functions that remove candidates.
`rics.mapping.heuristic_functions`	Functions which perform heuristics for score functions.
`rics.mapping.score_functions`	Functions which return a likeness score.
`rics.mapping.types`	Types used for mapping.