Skip to main content

Multiple argument dispatching.

Project description

image image image image image image image image image

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

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.

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.

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 and typing. Subscripted generics are supported:

  • Union[...] or ... | ...
  • Mapping[...] - the first key-value pair is checked
  • tuple[...] - all args are checked
  • Iterable[...] - the first arg is checked
  • Type[...]
  • Literal[...]
  • Callable[[...], ...] - parameter types are contravariant, return type is covariant

Naturally 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:

  • If an exact match isn't registered, the next closest method is called (and cached).
  • If the issubclass relation is ambiguous, mro position is used as a tie-breaker.
  • If there are still ambiguous methods - or none - a custom TypeError is raised.
  • Keyword-only parameters may be annotated, but won't affect dispatching.
  • A skipped annotation is equivalent to : object.
  • If no types are specified, it will inherently match all arguments.

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
    def bar(cls, x: str):

    # @classmethod: can not be used with `register` because `_` is not the multimethod
    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

def func(obj: str):

def func(obj: str.isalnum):

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:
    def bar(self, x: str):
    def bar(self, x: int):


% pip install multimethod


100% branch coverage.

% pytest [--cov]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

multimethod-1.10.tar.gz (12.1 kB view hashes)

Uploaded source

Built Distribution

multimethod-1.10-py3-none-any.whl (9.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page