Skip to content

Overload

framework3.container.overload

R = TypeVar('R') module-attribute

T = TypeVar('T') module-attribute

DispatchableMethod

Bases: Protocol[R]

Protocol for a dispatchable method.

This protocol defines the interface for a method that can be dispatched based on the type of its arguments and can register new implementations.

Key Features
  • Defines a callable interface
  • Provides a register method for new implementations
Usage

This protocol is typically used as a type hint for methods that support dynamic dispatch based on argument types.

Methods:

Name Description
__call__

Any, **kwargs: Any) -> R: Call the method with the given arguments.
register

type[T], func: Callable[..., R]) -> Callable[..., R]: Register a new implementation for the given class.
Note

This is a Protocol class and is not meant to be instantiated directly. It serves as a structural subtyping tool for static type checking.

Source code in framework3/container/overload.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class DispatchableMethod(Protocol[R]):
    """
    Protocol for a dispatchable method.

    This protocol defines the interface for a method that can be dispatched
    based on the type of its arguments and can register new implementations.

    Key Features:
        - Defines a callable interface
        - Provides a register method for new implementations

    Usage:
        This protocol is typically used as a type hint for methods that support
        dynamic dispatch based on argument types.

    Methods:
        __call__(*args: Any, **kwargs: Any) -> R:
            Call the method with the given arguments.
        register(cls: type[T], func: Callable[..., R]) -> Callable[..., R]:
            Register a new implementation for the given class.

    Note:
        This is a Protocol class and is not meant to be instantiated directly.
        It serves as a structural subtyping tool for static type checking.
    """

    def __call__(self, *args: Any, **kwargs: Any) -> R:
        """
        Call the method with the given arguments.

        This method represents the main functionality of the dispatchable method.
        It will be called when the method is invoked and will dispatch to the
        appropriate implementation based on the types of the arguments.

        Args:
            *args (Any): Positional arguments passed to the method.
            **kwargs (Any): Keyword arguments passed to the method.

        Returns:
            R: The result of calling the appropriate implementation of the method.
        """
        ...

    def register(self, cls: type[T], func: Callable[..., R]) -> Callable[..., R]:
        """
        Register a new implementation for the given class.

        This method allows registering new implementations for specific types.
        When the dispatchable method is called with an instance of the registered
        class as its argument, the corresponding implementation will be used.

        Args:
            cls (type[T]): The class for which to register the implementation.
            func (Callable[..., R]): The function to be used as the implementation
                for the given class.

        Returns:
            Callable[..., R]: The registered function, allowing for decorator-style usage.

        Example:
            ```python
            @my_method.register(int)
            def _(self, arg: int):
                return f"Integer implementation: {arg}"
            ```
        """
        ...
__call__(*args, **kwargs)

Call the method with the given arguments.

This method represents the main functionality of the dispatchable method. It will be called when the method is invoked and will dispatch to the appropriate implementation based on the types of the arguments.

Parameters:

Name Type Description Default
*args Any

Positional arguments passed to the method.

 ()
**kwargs Any

Keyword arguments passed to the method.

 {}

Returns:

Name Type Description
R R

The result of calling the appropriate implementation of the method.
Source code in framework3/container/overload.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def __call__(self, *args: Any, **kwargs: Any) -> R:
    """
    Call the method with the given arguments.

    This method represents the main functionality of the dispatchable method.
    It will be called when the method is invoked and will dispatch to the
    appropriate implementation based on the types of the arguments.

    Args:
        *args (Any): Positional arguments passed to the method.
        **kwargs (Any): Keyword arguments passed to the method.

    Returns:
        R: The result of calling the appropriate implementation of the method.
    """
    ...
register(cls, func)

Register a new implementation for the given class.

This method allows registering new implementations for specific types. When the dispatchable method is called with an instance of the registered class as its argument, the corresponding implementation will be used.

Parameters:

Name Type Description Default
cls type[T]

The class for which to register the implementation.

 required
func Callable[..., R]

The function to be used as the implementation for the given class.

 required

Returns:

Type Description
Callable[..., R]

Callable[..., R]: The registered function, allowing for decorator-style usage.
Example 
@my_method.register(int)
def _(self, arg: int):
    return f"Integer implementation: {arg}"
Source code in framework3/container/overload.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def register(self, cls: type[T], func: Callable[..., R]) -> Callable[..., R]:
    """
    Register a new implementation for the given class.

    This method allows registering new implementations for specific types.
    When the dispatchable method is called with an instance of the registered
    class as its argument, the corresponding implementation will be used.

    Args:
        cls (type[T]): The class for which to register the implementation.
        func (Callable[..., R]): The function to be used as the implementation
            for the given class.

    Returns:
        Callable[..., R]: The registered function, allowing for decorator-style usage.

    Example:
        ```python
        @my_method.register(int)
        def _(self, arg: int):
            return f"Integer implementation: {arg}"
        ```
    """
    ...

SingleDispatch

Bases: Protocol[R]

Protocol for a single dispatch function.

This protocol defines the interface for a function that can be dispatched based on the type of its first argument and can register new implementations.

Key Features
  • Defines a callable interface
  • Provides methods for registering and dispatching implementations
Usage

This protocol is typically used as a type hint for functions that support single dispatch based on the type of the first argument.

Methods:

Name Description
__call__

Any, **kwargs: Any) -> R: Call the function with the given arguments.
register

type, func: Callable[..., R]) -> Callable[..., R]: Register a new implementation for the given class.
dispatch

type) -> Callable[..., R]: Return the implementation for the given class.
Note

This is a Protocol class and is not meant to be instantiated directly. It serves as a structural subtyping tool for static type checking.

Source code in framework3/container/overload.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
class SingleDispatch(Protocol[R]):
    """
    Protocol for a single dispatch function.

    This protocol defines the interface for a function that can be dispatched
    based on the type of its first argument and can register new implementations.

    Key Features:
        - Defines a callable interface
        - Provides methods for registering and dispatching implementations

    Usage:
        This protocol is typically used as a type hint for functions that support
        single dispatch based on the type of the first argument.

    Methods:
        __call__(*args: Any, **kwargs: Any) -> R:
            Call the function with the given arguments.
        register(cls: type, func: Callable[..., R]) -> Callable[..., R]:
            Register a new implementation for the given class.
        dispatch(cls: type) -> Callable[..., R]:
            Return the implementation for the given class.

    Note:
        This is a Protocol class and is not meant to be instantiated directly.
        It serves as a structural subtyping tool for static type checking.
    """

    def __call__(self, *args: Any, **kwargs: Any) -> R:
        """
        Call the function with the given arguments.

        This method represents the main functionality of the single dispatch function.
        It will be called when the function is invoked and will dispatch to the
        appropriate implementation based on the type of the first argument.

        Args:
            *args (Any): Positional arguments passed to the function.
            **kwargs (Any): Keyword arguments passed to the function.

        Returns:
            R: The result of calling the appropriate implementation of the function.
        """
        ...

    def register(self, cls: type, func: Callable[..., R]) -> Callable[..., R]:
        """
        Register a new implementation for the given class.

        This method allows registering new implementations for specific types.
        When the single dispatch function is called with an instance of the registered
        class as its first argument, the corresponding implementation will be used.

        Args:
            cls (type): The class for which to register the implementation.
            func (Callable[..., R]): The function to be used as the implementation
                for the given class.

        Returns:
            Callable[..., R]: The registered function, allowing for decorator-style usage.

        Example:
            ```python
            @process.register(int)
            def _(arg: int):
                return f"Integer implementation: {arg}"
            ```
        """
        ...

    def dispatch(self, cls: type) -> Callable[..., R]:
        """
        Return the implementation for the given class.

        This method is used internally by the single dispatch mechanism to retrieve
        the appropriate implementation for a given type.

        Args:
            cls (type): The class for which to retrieve the implementation.

        Returns:
            Callable[..., R]: The implementation function registered for the given class.

        Note:
            This method is typically used internally by the dispatch mechanism and
            not called directly by users of the single dispatch function.
        """
        ...
__call__(*args, **kwargs)

Call the function with the given arguments.

This method represents the main functionality of the single dispatch function. It will be called when the function is invoked and will dispatch to the appropriate implementation based on the type of the first argument.

Parameters:

Name Type Description Default
*args Any

Positional arguments passed to the function.

 ()
**kwargs Any

Keyword arguments passed to the function.

 {}

Returns:

Name Type Description
R R

The result of calling the appropriate implementation of the function.
Source code in framework3/container/overload.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def __call__(self, *args: Any, **kwargs: Any) -> R:
    """
    Call the function with the given arguments.

    This method represents the main functionality of the single dispatch function.
    It will be called when the function is invoked and will dispatch to the
    appropriate implementation based on the type of the first argument.

    Args:
        *args (Any): Positional arguments passed to the function.
        **kwargs (Any): Keyword arguments passed to the function.

    Returns:
        R: The result of calling the appropriate implementation of the function.
    """
    ...
dispatch(cls)

Return the implementation for the given class.

This method is used internally by the single dispatch mechanism to retrieve the appropriate implementation for a given type.

Parameters:

Name Type Description Default
cls type

The class for which to retrieve the implementation.

 required

Returns:

Type Description
Callable[..., R]

Callable[..., R]: The implementation function registered for the given class.
Note

This method is typically used internally by the dispatch mechanism and not called directly by users of the single dispatch function.

Source code in framework3/container/overload.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def dispatch(self, cls: type) -> Callable[..., R]:
    """
    Return the implementation for the given class.

    This method is used internally by the single dispatch mechanism to retrieve
    the appropriate implementation for a given type.

    Args:
        cls (type): The class for which to retrieve the implementation.

    Returns:
        Callable[..., R]: The implementation function registered for the given class.

    Note:
        This method is typically used internally by the dispatch mechanism and
        not called directly by users of the single dispatch function.
    """
    ...
register(cls, func)

Register a new implementation for the given class.

This method allows registering new implementations for specific types. When the single dispatch function is called with an instance of the registered class as its first argument, the corresponding implementation will be used.

Parameters:

Name Type Description Default
cls type

The class for which to register the implementation.

 required
func Callable[..., R]

The function to be used as the implementation for the given class.

 required

Returns:

Type Description
Callable[..., R]

Callable[..., R]: The registered function, allowing for decorator-style usage.
Example 
@process.register(int)
def _(arg: int):
    return f"Integer implementation: {arg}"
Source code in framework3/container/overload.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def register(self, cls: type, func: Callable[..., R]) -> Callable[..., R]:
    """
    Register a new implementation for the given class.

    This method allows registering new implementations for specific types.
    When the single dispatch function is called with an instance of the registered
    class as its first argument, the corresponding implementation will be used.

    Args:
        cls (type): The class for which to register the implementation.
        func (Callable[..., R]): The function to be used as the implementation
            for the given class.

    Returns:
        Callable[..., R]: The registered function, allowing for decorator-style usage.

    Example:
        ```python
        @process.register(int)
        def _(arg: int):
            return f"Integer implementation: {arg}"
        ```
    """
    ...

fundispatch(func)

Decorator for creating a function dispatch.

This decorator creates a wrapper around the given function that dispatches based on the type of the first argument.

Key Features
  • Creates a dispatchable function
  • Dispatches based on the type of the first argument
  • Allows registration of new implementations
Usage

Use this decorator on functions that need to dispatch based on the type of their first argument.

@fundispatch
def process(arg):
    return "Default implementation"

@process.register(int)
def _(arg: int):
    return f"Integer implementation: {arg}"

@process.register(str)
def _(arg: str):
    return f"String implementation: {arg}"

Parameters:

Name Type Description Default
func SingleDispatch[R]

The function to be wrapped.

 required

Returns:

Type Description
SingleDispatch[R]

SingleDispatch[R]: A wrapper function with dispatch capabilities.
Note

The wrapped function will dispatch based on the type of the first argument. If the first argument is a type object, it will dispatch on that type directly. Otherwise, it will dispatch on the type of the first argument.

Source code in framework3/container/overload.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def fundispatch(func: SingleDispatch[R]) -> SingleDispatch[R]:
    """
    Decorator for creating a function dispatch.

    This decorator creates a wrapper around the given function that dispatches
    based on the type of the first argument.

    Key Features:
        - Creates a dispatchable function
        - Dispatches based on the type of the first argument
        - Allows registration of new implementations

    Usage:
        Use this decorator on functions that need to dispatch based on the type
        of their first argument.

        ```python
        @fundispatch
        def process(arg):
            return "Default implementation"

        @process.register(int)
        def _(arg: int):
            return f"Integer implementation: {arg}"

        @process.register(str)
        def _(arg: str):
            return f"String implementation: {arg}"
        ```

    Args:
        func (SingleDispatch[R]): The function to be wrapped.

    Returns:
        SingleDispatch[R]: A wrapper function with dispatch capabilities.

    Note:
        The wrapped function will dispatch based on the type of the first argument.
        If the first argument is a type object, it will dispatch on that type directly.
        Otherwise, it will dispatch on the type of the first argument.
    """
    dispatcher = singledispatch(func)

    def wrapper(*args: Any, **kwargs: Any) -> R:
        arg_type = args[0] if isinstance(args[0], type) else type(args[0])
        return dispatcher.dispatch(arg_type)(*args, **kwargs)

    wrapper = cast(SingleDispatch[R], wrapper)
    setattr(wrapper, "register", dispatcher.register)
    setattr(wrapper, "dispatch", dispatcher.dispatch)
    update_wrapper(wrapper, func)
    return wrapper

methdispatch(func)

Decorator for creating a method dispatch.

This decorator creates a wrapper around the given function that dispatches based on the type of the second argument (typically 'self' in method calls).

Key Features
  • Creates a dispatchable method
  • Dispatches based on the type of the second argument
  • Allows registration of new implementations
Usage

Use this decorator on methods that need to dispatch based on the type of their second argument (typically the first argument after 'self').

class MyClass:
    @methdispatch
    def my_method(self, arg):
        return "Default implementation"

    @my_method.register(int)
    def _(self, arg: int):
        return f"Integer implementation: {arg}"

Parameters:

Name Type Description Default
func Callable[..., R]

The function to be wrapped.

 required

Returns:

Type Description
DispatchableMethod[R]

DispatchableMethod[R]: A wrapper function with dispatch capabilities.
Note

The wrapped method will dispatch based on the type of the second argument, which is typically the first argument after 'self' in method calls.

Source code in framework3/container/overload.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def methdispatch(func: Callable[..., R]) -> DispatchableMethod[R]:
    """
    Decorator for creating a method dispatch.

    This decorator creates a wrapper around the given function that dispatches
    based on the type of the second argument (typically 'self' in method calls).

    Key Features:
        - Creates a dispatchable method
        - Dispatches based on the type of the second argument
        - Allows registration of new implementations

    Usage:
        Use this decorator on methods that need to dispatch based on the type
        of their second argument (typically the first argument after 'self').

        ```python
        class MyClass:
            @methdispatch
            def my_method(self, arg):
                return "Default implementation"

            @my_method.register(int)
            def _(self, arg: int):
                return f"Integer implementation: {arg}"
        ```

    Args:
        func (Callable[..., R]): The function to be wrapped.

    Returns:
        DispatchableMethod[R]: A wrapper function with dispatch capabilities.

    Note:
        The wrapped method will dispatch based on the type of the second argument,
        which is typically the first argument after 'self' in method calls.
    """
    dispatcher = singledispatch(func)

    def wrapper(*args, **kw):
        return dispatcher.dispatch(args[1].__class__)(*args, **kw)

    wrapper = cast(DispatchableMethod[R], wrapper)
    setattr(wrapper, "register", dispatcher.register)
    update_wrapper(wrapper, func)
    return wrapper