bagof-dispatchers

bagof.dispatchers provides multiple dispatch for Python. Register several implementations of a function, and each call runs the implementation whose declared parameter types most specifically match the runtime types of the arguments, the way Julia's multiple dispatch works.

>>> from bagof.dispatchers import dispatch
>>> @dispatch
... def area(width: int, height: int) -> int:
...     return width * height
>>> @dispatch
... def area(radius: float) -> float:
...     return 3 * radius * radius
>>> area(3, 4)
12
>>> area(2.0)
12.0

The second def named area does not replace the first. It adds an overload, and the name area stays bound to a single dispatched function that chooses between the two on every call. Getting started walks through registering overloads in more detail.

What sets it apart

• Dispatch reads the full vocabulary of type hints, not only plain classes. Unions, literals, generics, TypedDict, and type variables ordered by their declared variance all narrow which overload applies. See Variance.
• Exact[C] matches a value only when its type is exactly C, for the cases where a subclass should not quietly take over another overload's place; bool is otherwise also an int. See Exact types.
• Hint[X] dispatches on a type hint passed as a value, matching the hints that are sub-hints of X, so a function handed a hint can branch on what the hint is. See Dispatching on hints.
• Super[C] accepts a value whose class is C or a class above it, and inside Type[...] or Hint[...] it accepts the class or hint C and everything above it, so Type[Super[Dog]] accepts the class Dog and each class it derives from. Between[L, U] bounds from both sides at once, so Between[Dog, Animal] accepts a value whose class lies between Dog and Animal, both included, and Type[Between[Dog, Animal]] accepts those classes themselves. As the type argument of an invariant generic, a bound names a range of arguments, so List[Super[int]] accepts a list declared to hold int, numbers.Integral or object. See Exact types and Variance.
• A call that matches no overload, or that matches two equally specific overloads, is always a clear error rather than a silent guess. NoMethodError is a TypeError carrying the closest candidates, and AmbiguousMethodError names the overloads that tie. A function's ambiguities() finds such ties before any call is made, so a test suite can assert that there are none. See When two overloads are equally specific and When nothing matches.
• Dispatch is aware of argument names as well as positions, so a call binds by position or by keyword, either way, against the same overloads. See Registering overloads.
• Registries are explicit. @dispatch keeps functions separate per module; build a Dispatcher when several modules should extend one shared function instead.
• The library supports Python 3.8 through the current release, and depends on nothing beyond typing_extensions.

Install

pip install git+https://github.com/bagofseeds/bagof-dispatchers.git

Status

The project is at an early stage: the API is still settling, and some of it may still move. Issues and ideas are welcome at bagofseeds/bagof-dispatchers.

bagof.dispatchers is the low-level root of the bagof family. It owns the hint subtype relation and the introspection helpers the other bags build on; see Part of bagof and the project overview. For how it compares with plum, multipledispatch, functools.singledispatch, and Julia's own multiple dispatch, see the comparison page.