Multiple argument dispatching.
Multimethod provides a decorator for adding multiple argument dispatching to functions. The decorator creates a multimethod object as needed, and registers the function with its annotations.
There are several multiple dispatch libraries on PyPI. This one aims for simplicity and speed. With caching of argument types, it should be the fastest pure Python implementation possible.
There are a few options which trade-off dispatch speed for flexibility.
Decorator | Speed | Dispatch | Arguments |
---|---|---|---|
multimethod | fastest | cached lookup | positional only |
multidispatch | - | binds to first signature + cached lookup | + keywords |
overload | slowest | checks all signatures serially | + keywords & predicates |
from multimethod import multimethod
@multimethod
def func(x: int, y: float):
...
func
is now a multimethod
which will delegate to the above function, when called with arguments of the specified types. Subsequent usage will register new types and functions to the existing multimethod of the same name.
@multimethod
def func(x: float, y: int):
...
Alternatively, functions can be explicitly registered in the same style as functools.singledispatch. This syntax is also compatible with mypy, which by default checks that each name is defined once.
@func.register
def _(x: bool, y: bool):
...
@func.register(object, bool)
@func.register(bool, object)
def _(x, y): # stackable without annotations
...
Multimethods are implemented as mappings from signatures to functions, and can be introspected as such.
method[type, ...] # get registered function
method[type, ...] = func # register function by explicit types
Multimethods support any types that satisfy the issubclass
relation, including abstract base classes in collections.abc
and typing
. Subscripted generics are supported:
Union[...]
or ... | ...
Mapping[...]
- the first key-value pair is checkedtuple[...]
- all args are checkedIterable[...]
- the first arg is checkedType[...]
Literal[...]
Callable[[...], ...]
- parameter types are contravariant, return type is covariantNaturally checking subscripts is slower, but the implementation is optimized, cached, and bypassed if no subscripts are in use in the parameter. Empty iterables match any subscript, but don't special-case how the types are normally resolved.
Dispatch resolution details:
issubclass
relation is ambiguous,
mro position is used as a tie-breaker.TypeError
is raised.: object
.classmethod
and staticmethod
may be used with a multimethod, but must be applied last, i.e., wrapping the final multimethod definition after all functions are registered. For class and instance methods, cls
and self
participate in the dispatch as usual. They may be left blank when using annotations, otherwise use object
as a placeholder.
class Foo:
# @classmethod: only works here if there are no more functions
@multimethod
def bar(cls, x: str):
...
# @classmethod: can not be used with `register` because `_` is not the multimethod
@bar.register
def _(cls, x: int):
...
bar = classmethod(bar) # done with registering
multidispatch
is a wrapper to provide compatibility with functools.singledispatch
. It requires a base implementation and use of the register
method instead of namespace lookup. It also supports dispatching on keyword arguments.
Overloads dispatch on annotated predicates. Each predicate is checked in the reverse order of registration.
The implementation is separate from multimethod
due to the different performance characteristics. If an annotation is a type instead of a predicate, it will be converted into an isinstance
check. Provisionally supports generics as well.
from multimethod import overload
@overload
def func(obj: str):
...
@overload
def func(obj: str.isalnum):
...
@overload
def func(obj: str.isdigit):
...
Use metaclass=multimeta
to create a class with a special namespace which converts callables to multimethods, and registers duplicate callables with the original.
from multimethod import multimeta
class Foo(metaclass=multimeta):
def bar(self, x: str):
...
def bar(self, x: int):
...
Equivalent to:
from multimethod import multimethod
class Foo:
@multimethod
def bar(self, x: str):
...
@bar.register
def bar(self, x: int):
...
% pip install multimethod
100% branch coverage.
% pytest [--cov]