sigmatch 0.0.9

A quick way to verify function signatures in Python

ⓘ

This small library allows you to quickly check whether a callable can be called in an expected way. This can be useful, for example, if you write libraries that accept callbacks.

Table of contents

• Installation
• Usage
• Combining different expectations
• Comparing functions with each other

Installation

Install sigmatch with pip:

pip install sigmatch

You can also use instld to quickly try out this package and others without installing them.

Usage

To check the signature of a callable, you first need to «bake» your expectations into a special object. Here's how to do it:

from sigmatch import PossibleCallMatcher

expectation = PossibleCallMatcher('.., c')

You see, we passed a strange string to the PossibleCallMatcher constructor. What does it mean? It is a short description of the expected signature in a special micro-language. Let's learn how to compose short expressions in it! Here are a few rules:

• You list the expected arguments of the function separated by commas, like this: a, b, c. The spaces are recommended, but not required
• You indicate positional arguments using dots, like this: ., ., .. The points do not necessarily have to be separated by commas, so a completely equivalent expression would be ....
• If you specify a name, it means that the argument will be passed to the function by name (rather than by position). For example, the expression x, y means that the function will be called like this: function(x=1, y=2) (not function(1, 2)!).
• If you use unpacking when calling a function, use * for iterable unpacking and ** for mapping unpacking.
• The arguments in the expression must be in the following order: first positional, then keyword, then usual unpacking, then dictionary unpacking. Do not violate this!
• If the function does not accept any arguments, do not pass anything to the PossibleCallMatcher constructor.

Here are some examples of expressions:

• .. means «the function will be called with 2 positional arguments».
• ., first, second means «the function will be called with 1 positional argument and 2 keyword arguments: first and second».
• .., * means «the function will be called with 2 positional arguments, and a list can also be unpacked when calling», like this: function(1, 2, *[3, 4, 5]).
• .., first, ** means «the function will be called with 2 positional arguments, the argument first will be passed by name, and a dictionary can be unpacked when calling», like this: function(1, 2, first=3, **{'second': 4, 'third': 5}).

Now let's use this matcher on a few functions:

def first_suitable_function(a, b, c):
    ...

def second_suitable_function(a, b, c=None, d=None):  # This function also suits us, because the argument "d" does not have to be passed.
    ...

def not_suitable_function(a, b):  # Attention!
    ...

print(expectation.match(first_suitable_function))
#> True
print(expectation.match(second_suitable_function))
#> True
print(expectation.match(not_suitable_function))
#> False

⚠️ Some built-in functions, such as next, are written in C and therefore cannot be extracted from them. But if you wrote the function yourself and it is in Python, it should work fine.

As you can see, the same expression can correspond to functions with different signatures. This is because our expressions describe not the signature of the function, but how it will be called. Python allows the same function to be called in different ways.

If you want an exception to be raised when the signature does not match expectations, pass the argument raise_exception=True when calling the match() method:

expectation.match(not_suitable_function, raise_exception=True)
#> ...
#> sigmatch.errors.SignatureMismatchError: The signature of the callable object does not match the expected one.

In this case, an exception will also be raised if the signature cannot be extracted from the passed object.

Combining different expectations

Sometimes the same function can be called differently in different parts of a program, and that's perfectly normal. But how can you express this situation concisely in terms of sigmatch? Just combine several expectation objects with +:

expectation = PossibleCallMatcher('...') + PossibleCallMatcher('.., c') + PossibleCallMatcher('.., d')

⚠️ The current variation selection algorithm has one known flaw: it ignores the presence of default values for positional-only parameters. However, this problem rarely occurs in real code.

The resulting object behaves just like a regular matcher object, i.e., it will also have a match() method. However, it will check several signatures, and if at least one of them matches the callable, it will return True, otherwise False:

def now_its_suitable(a, b):  # This one matches now.
    ...
    
print(expectation.match(now_its_suitable))
#> True

You can treat the combined matcher as a regular collection: iterate over it, get its length, and test membership.

Comparing functions with each other

Sometimes you may not know in advance what callable interface you expect, but you need it to match the signature of some other function so that they are compatible with each other. How can you do this?

To generate all valid ways to call a function, use the from_callable() method of the PossibleCallMatcher class:

def function(a, b):
    ...

possible_arguments = PossibleCallMatcher.from_callable(function)

print(possible_arguments)
#> SignatureSeriesMatcher(PossibleCallMatcher('., a'), PossibleCallMatcher('., b'), PossibleCallMatcher('..'), PossibleCallMatcher('a, b'))

This is the same combined matcher described above.

If you need to make sure that the signatures of two functions are completely identical, simply compare the resulting matchers:

def function_1(a, b):
    ...

def function_2(a, b):
    ...

def different_function(a, b, c):
    ...

print(PossibleCallMatcher.from_callable(function_1) == PossibleCallMatcher.from_callable(function_2))
#> True
print(PossibleCallMatcher.from_callable(function_2) == PossibleCallMatcher.from_callable(different_function))
#> False

But sometimes, the set of valid calls for one function is a subset of the set of valid calls for another, even though the signatures are not completely equal. And you want to make sure that any way you can call the first function, you can also call the second. How can you do this? Use the in operator:

def function_1(a, b):
    ...

def function_2(a, b, c=None):
    ...

print(PossibleCallMatcher.from_callable(function_1) in PossibleCallMatcher.from_callable(function_2))
#> True

And finally, the least strict check: sometimes you need to make sure that two different functions have at least one valid call in common. To do this, you can compute the intersection of their valid calls using the & operator:

def function_1(a, b, d=None):
    ...

def function_2(a, b, c=None):
    ...

print(bool(PossibleCallMatcher.from_callable(function_1) & PossibleCallMatcher.from_callable(function_2)))
#> True