Dispatch

Dynamic dispatch facilities for Python.

This addresses the lack of runtime-available, inheritance-free interfaces in Python. It partially resembles the extension and trait.

Rationale

Why not functools.singledispatch?

• Runtime behavior based on type hints can be confusing.
• It's method variant functools.singledispatchmethod dispatches methods based on the first non-self argument, which is very different from the single dispatch found in other object-oriented programming languages.

Why not abc.ABC?

• It does not enable virtual-like or dyn-like dispatch. An abstractmethod in an abstract class will not forward the call to the concrete implementation based on the real type. i.e., there is no facilities for implementation selection based on concrete types.
• Although ABCMeta.register can be used to register non-child classes, it cannot inject implementations to the registered classes. Some classes do not allow monkey-patching and the implementations must be stored elsewhere, registering them to the ABC is logical error, as the implementations are not part of the concrete class.

Using ABCDispatch defined in this module,

• All ABC features work out of the box. Supports static type checking (inheritance-based usages only), non-inheritance based runtime type checking, and @abstractmethod.
• Abstract methods defined in an ABCDispatch can dynamically forward the call to the concrete implementation based on the real type, and the implementations can be externally provided. For example, an ABCDispatch can be used to extend built-in classes.

Usage

First, define a class that subclasses ABCDispatch. This class will be semantically similar to Rust traits. All interface functions defined in this method shall be decorated with @abc.abstractmethod. Class methods and static methods can also be defined with the same decorator.

Warning

The @abstractmethod decorator must be placed after the @classmethod or @staticmethod decorator.

class Trait(ABCDispatch):
    @abstractmethod
    def method(self, f): ...

    @classmethod
    @abstractmethod
    def class_method(cls, f): ...

    @staticmethod
    @abstractmethod
    def static_method(f): ...

Then, we can implement the "trait" for a class by using the @impl decorator. The implementor class is passed as the first argument to the decorator. The implementation is written in the class syntax, with each trait method implemented as a method of the class. The class name doesn't matter, but it should subclass the trait class.

@impl(Class)
class _(Trait):
    def method(self, f): """Concrete implementation goes here"""

    @classmethod
    def class_method(cls, f): """Concrete implementation goes here"""

    @staticmethod
    def static_method(f): """Concrete implementation goes here"""

In this case, Class.method does not exist during runtime so you may not call it, and calling .method on an instance of Class will also fail. But you can call Trait.method on an instance of Class and it will dispatch to the concrete implementation defined in the @impl construct.

c = Class()
Trait.method(c, f)  # Calls the implementation within the @impl

If you have control to the source code, you can add Trait to the base classes of Class, so Class.method(instance) and instance.method() will work as expected, Trait.method(instance, f) shall also work.

Class methods and static methods shall be called with the generic syntax, as the concrete class is not inferrable from the function's call arguments.

Trait.class_method[Class](f)
Trait.static_method[Class](f)

It's also possible to define a dispatchable function using the @dispatch decorator. Then an method impl_for will be on the function, which can be used to register implementations.

@dispatch
def f(x): ...

@f.impl_for(int)
def _(x: int):
    """Implementation for int goes here"""

Example

You can check the Functor's source code as an example of how to use this module.

By default ABCDispatch and @dispatch defines a single dispatch. This means the runtime imlementation selection is based on the concrete type of first argument of the function, or of the receiver in the case of methods.

ABCDispatch

An ABC that enables single dispatch for its abstract methods. This behaves similarly to abc.ABC but with the added feature of dynamic concrete implementation selection under single dispatch. Stick to built-in abc.abstractmethod to define abstract methods.

See the usage section for more information.

Example

from abc import abstractmethod
from apfel.core.dispatch import ABCDispatch

class A(ABCDispatch):
    @abstractmethod
    def hi(self):
        print(self)

    @classmethod
    @abstractmethod
    def hey(cls):
        print(cls)

a: A = some_instance()
A.hi(a)

dispatch(func)

A decorator for creating a single-dispatchable function. It will add an impl_for method to the function, which can be used to register implementations. Calling the function will dispatch to the correct implementation based on the type of the first argument.

This is similar to functools.singledispatch, but does not use type hints for dispatching, and static type unions are not supported.

Example

@dispatch
def show(x):
    ...

@show.impl_for(int)
def _(x: int):
    return f"int: {x}"

@show.impl_for(str)
def _(x: str):
    return f"str: {x}"

show(1)       # "int: 1"
show("hello") # "str: hello"

impl(definition)

Decorator for registering an implementation using the class syntax.

See the usage section for more information.

Example

Here Class is a concrete class and Trait is an ABCDispatch.

@impl(Class)
class _(Trait):
    def method(self, f): """Concrete implementation goes here"""

    @classmethod
    def class_method(cls, f): """Concrete implementation goes here"""

    @staticmethod
    def static_method(f): """Concrete implementation goes here"""

add_impl(definition, impl, *impl_for_args, **impl_for_kwargs)

An imperative interface for adding implementations to a dispatchable class. For a declarative interface, use the @impl decorator.

If the dispatchable class is an ABCDispatch which does single dispatch, the impl_for_args param should be the type of the implementor class.

Parameters:

Name	Type	Description	Default
definition	type	The dispatchable class.	required
impl	Mapping[str, Callable]	A mapping from method names to implementations.	required
*impl_for_args		Arguments that the dispatch mechanism will use for selecting the implementation.	()
**impl_for_kwargs		Keyword arguments that the dispatch mechanism will use for selecting the implementation.	{}

Example

# The following imperative code ...
add_impl(Trait, {"method": lambda self, f: f}, Class)

# ... is equivalent to the following declarative code:
@impl(Class)
class _(Trait):
    def method(self, f): return f