matchpy.expressions.constraints module

Contains several pattern constraint classes.

A pattern constraint is used to further filter which subjects a pattern matches.

The most common use would be the CustomConstraint, which wraps a lambda or function to act as a constraint:

>>> a_symbol_constraint = CustomConstraint(lambda x: x.name.startswith('a'))
>>> pattern = Pattern(x_, a_symbol_constraint)
>>> is_match(Symbol('a1'), pattern)
True
>>> is_match(Symbol('b1'), pattern)
False

There is also the EqualVariablesConstraint which will try to unify the substitutions of the variables and only match if it succeeds:

>>> equal_constraint = EqualVariablesConstraint('x', 'y')
>>> pattern = Pattern(f(x_, y_), equal_constraint)
>>> is_match(f(a, a), pattern)
True
>>> is_match(f(a, b), pattern)
False

You can also create a subclass of the Constraint class to create your own custom constraint type.

class Constraint

Bases: object

Base for pattern constraints.

A constraint is essentially a callback, that receives the match Substitution and returns a bool indicating whether the match is valid.

You have to override all the abstract methods if you wish to create your own subclass.

__call__(match: matchpy.expressions.substitution.Substitution) → bool

Return True, iff the constraint is fulfilled by the substitution.

Override this in your subclass to define the actual constraint behavior.

Parameters:match – The (current) match substitution. Note that the matching is done from left to right, so not all variables may have a value yet. You need to override variables so that the constraint gets called once all the variables it depends on have a value assigned to them.
Returns:True, iff the constraint is fulfilled by the substitution.
__eq__(other)

Constraints need to be equatable.

__hash__()

Constraints need to be hashable.

variables

The names of the variables the constraint depends upon.

Used by matchers to decide when a constraint can be evaluated (which is when all the dependency variables have been assigned a value). If the set is empty, the constraint will only be evaluated once the whole match is complete.

with_renamed_vars(renaming: Dict[str, str]) → matchpy.expressions.constraints.Constraint

Return a copy of the constraint with renamed variables. This is called when the variables in the expression are renamed and hence the ones in the constraint have to be renamed as well. A later invocation of __call__() will have the new variable names. You will have to implement this if your constraint needs to use the variables of the match substitution. Note that this can be called multiple times and you might have to account for that. Also, this should not modify the original constraint but rather return a copy. :param renaming: A dictionary mapping old names to new names.

Returns:A copy of the constraint with renamed variables.
class EqualVariablesConstraint(*variables)

Bases: matchpy.expressions.constraints.Constraint

A constraint that ensure multiple variables are equal.

The constraint tries to unify the substitutions for the variables and is fulfilled iff that succeeds.

__init__(*variables) → None
Parameters:*variables – The names of the variables to check for equality.
variables

The names of the variables the constraint depends upon.

Used by matchers to decide when a constraint can be evaluated (which is when all the dependency variables have been assigned a value). If the set is empty, the constraint will only be evaluated once the whole match is complete.

with_renamed_vars(renaming)

Return a copy of the constraint with renamed variables. This is called when the variables in the expression are renamed and hence the ones in the constraint have to be renamed as well. A later invocation of __call__() will have the new variable names. You will have to implement this if your constraint needs to use the variables of the match substitution. Note that this can be called multiple times and you might have to account for that. Also, this should not modify the original constraint but rather return a copy. :param renaming: A dictionary mapping old names to new names.

Returns:A copy of the constraint with renamed variables.
class CustomConstraint(constraint: Callable[..., bool])

Bases: matchpy.expressions.constraints.Constraint

Wrapper for lambdas of functions as constraints.

The parameter names have to be the same as the the variable names in the expression:

>>> constraint = CustomConstraint(lambda x, y: x.name < y.name)
>>> pattern = Pattern(f(x_, y_), constraint)
>>> is_match(f(a, b), pattern)
True
>>> is_match(f(b, a), pattern)
False

The ordering of the parameters is not important. You only need to have the parameters needed for the constraint, not all variables occurring in the pattern.

Note, that the matching happens from left left to right, so not all variables may have been assigned a value when constraint is called. For constraints over multiple variables you should attach the constraint to the last variable occurring in the pattern or a surrounding operation.

__init__(constraint: Callable[..., bool]) → None
Parameters:constraint – The constraint callback.
Raises:ValueError – If the callback has positional-only or variable parameters (*args and **kwargs).
variables

The names of the variables the constraint depends upon.

Used by matchers to decide when a constraint can be evaluated (which is when all the dependency variables have been assigned a value). If the set is empty, the constraint will only be evaluated once the whole match is complete.

with_renamed_vars(renaming)

Return a copy of the constraint with renamed variables. This is called when the variables in the expression are renamed and hence the ones in the constraint have to be renamed as well. A later invocation of __call__() will have the new variable names. You will have to implement this if your constraint needs to use the variables of the match substitution. Note that this can be called multiple times and you might have to account for that. Also, this should not modify the original constraint but rather return a copy. :param renaming: A dictionary mapping old names to new names.

Returns:A copy of the constraint with renamed variables.