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 abool
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.
-