Skip to main content

Multiple argument dispatching.

Project description

image image image image build image CodeQL CodSpeed Badge 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.

Usage

There are a couple options which trade-off dispatch speed for flexibility.

Decorator Speed Dispatch Arguments
multimethod faster cached lookup positional only
multidispatch slower binds to first signature + cached lookup positional + keywords

Dispatching on simple types which use issubclass is cached. Advanced types which use isinstance require a linear scan.

multimethod

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. Note typing aliases do not support issubclass consistently, and are no longer needed for subscripts. Using ABCs instead is recommended. 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 there are 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.

multidispatch

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.

instance checks

subtype provisionally provides isinstance and issubclass checks for generic types. When called on a non-generic, it will return the origin type.

from multimethod import subtype

cls = subtype(int | list[int])

for obj in (0, False, [0], [False], []):
    assert isinstance(obj, cls)
for obj in (0.0, [0.0], (0,)):
    assert not isinstance(obj, cls)

for subclass in (int, bool, list[int], list[bool]):
    assert issubclass(subclass, cls)
for subclass in (float, list, list[float], tuple[int]):
    assert not issubclass(subclass, cls)

If a type implements a custom __instancecheck__, it can opt-in to dispatch (without caching) by registering its metaclass and bases with subtype.origins. parametric provides a convenient constructor, which will match the base class, predicate functions, and check attributes.

from multimethod import parametric

Coroutine = parametric(Callable, inspect.iscoroutinefunction)
IntArray = parametric(array, typecode='i')

classes

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 Cls:
    # @classmethod: only works here if there are no more functions
    @multimethod
    def meth(cls, arg: str): ...

    # @classmethod: can not be used with `register` because `_` is not the multimethod
    @meth.register
    def _(cls, arg: int): ...

    meth = classmethod(meth)  # done with registering

If a method spans multiple classes, then the namespace lookup can not work. The register method can be used instead.

class Base:
    @multimethod
    def meth(self, arg: str): ...

class Subclass(Base):
    @Base.meth.register
    def _(self, arg: int): ...

If the base class can not be modified, the decorator - like any - can be called explicitly.

class Subclass(Base):
    meth = multimethod(Base.meth)
    ...

multimeta creates a class with a special namespace which converts callables to multimethods, and registers duplicate callables with the original.

class Cls(metaclass=multimeta):
    ... # all methods are multimethods

Installation

% pip install multimethod

Tests

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-2.0.tar.gz (16.1 kB view details)

Uploaded Source

Built Distribution

multimethod-2.0-py3-none-any.whl (9.8 kB view details)

Uploaded Python 3

File details

Details for the file multimethod-2.0.tar.gz.

File metadata

  • Download URL: multimethod-2.0.tar.gz
  • Upload date:
  • Size: 16.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for multimethod-2.0.tar.gz
Algorithm Hash digest
SHA256 c628b6d2e7d61fbe58484dd884d990901e8314faf58af062e72b65e3423cb109
MD5 75f94caf5ac408a5f8f81dd8c135be75
BLAKE2b-256 551434e8c84ba4f1ab1186dc07426e0e84be71d3336cc57e8d076ee14331d50e

See more details on using hashes here.

Provenance

The following attestation bundles were made for multimethod-2.0.tar.gz:

Publisher: release.yml on coady/multimethod

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file multimethod-2.0-py3-none-any.whl.

File metadata

  • Download URL: multimethod-2.0-py3-none-any.whl
  • Upload date:
  • Size: 9.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.0.1 CPython/3.12.8

File hashes

Hashes for multimethod-2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 45aa231dc9dbb7f980c0f2ad8179e2c2b72a8cd5c7d7534337be66dde29d35be
MD5 5e7f6003b09baf63a84589800d0e2f56
BLAKE2b-256 8442a285fc4b89b3a249538954779cd4082a85bf35dc7d0a9c93e48e146e3dc7

See more details on using hashes here.

Provenance

The following attestation bundles were made for multimethod-2.0-py3-none-any.whl:

Publisher: release.yml on coady/multimethod

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

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