This package implements pattern matching in Python. Pattern matching is a powerful tool for symbolic computations, operating on symbolic expressions. Given a pattern and an expression (which is usually called subject), the goal of pattern matching is to find a substitution for all the variables in the pattern such that the pattern becomes the subject. As an example, consider the pattern \(f(x)\), where \(f\) is a function and \(x\) is a variable, and the subject \(f(a)\), where \(a\) is a constant symbol. Then the substitution that replaces \(x\) with \(a\) is a match. MatchPy supports associative and/or commutative function symbols, as well as sequence variables, similar to pattern matching in Mathematica.

Given a pattern and an expression (which is usually called subject), the idea of pattern matching is to find a substitution that maps wildcards to expressions such that the pattern becomes the subject. In MatchPy, a substitution is a dict that maps variable names to expressions.

When a fixed set of patterns is matched repeatedly against different subjects, matching can be sped up significantly by using many-to-one matching. The idea of many-to-one matching is to construct a so called discrimination net, a data structure similar to a decision tree or a finite automaton that exploits similarities between patterns. In MatchPy, there are two such data structures, implemented as classes: DiscriminationNet and ManyToOneMatcher. The DiscriminationNet class only supports syntactic pattern matching, that is, operations are neither associative nor commutative. Sequence variables are not supported either. The ManyToOneMatcher class supports associative and/or commutative matching with sequence variables. For syntactic pattern matching, the DiscriminationNet should be used, as it is usually faster.

Besides the existing features, we plan on adding the following to MatchPy:

Support for Mathematica’s Alternatives: For example f(a|b) would match either f(a) or f(b).

Support for Mathematica’s Repeated: For example f(a..) would match f(a), f(a,a), f(a,a,a), etc.

Support pattern sequences (PatternSequence in Mathematica). These are mainly useful in combination with
Alternatives or Repeated, e.g. f(a|(b,c)) would match either f(a) or f(b,c).
f((aa)..) would match any f with an even number of a arguments.

All these additional pattern features need to be supported in the ManyToOneMatcher as well.

Better integration with existing types such as dict.

Code generation for both one-to-one and many-to-one matching. There is already an experimental implementation, but it still has some dependencies on MatchPy which can probably be removed.

Improving the documentation with more examples.

Better test coverage with more randomized tests.

Implementation of the matching algorithms in a lower-level language, for example C, both for performance and to make MatchPy’s functionality available in other languages.