[](https://pypi.org/project/multimethod/)
[](https://pepy.tech/project/multimethod)
[](https://github.com/coady/multimethod/actions/workflows/build.yml)
[](https://codecov.io/gh/coady/multimethod/)
[](https://github.com/coady/multimethod/actions/workflows/github-code-scanning/codeql)
[](https://codspeed.io/coady/multimethod)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
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](#multimethod) | faster | cached lookup | positional only
[multidispatch](#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
```python
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.
```python
@multimethod
def func(x: float, y: int):
...
```
Alternatively, functions can be explicitly registered in the same style as [functools.singledispatch](https://docs.python.org/3/library/functools.html#functools.singledispatch). This syntax is also compatible with [mypy](https://mypy-lang.org), which by default checks that [each name is defined once](https://mypy.readthedocs.io/en/stable/error_code_list.html#check-that-each-name-is-defined-once-no-redef).
```python
@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.
```python
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.
```python
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.
```python
from multimethod import parametric
Coroutine = parametric(Callable, asyncio.iscoroutinefunction)
IntArray = parametric(array, typecode='i')
```
`overload` used to dispatch on annotated predicate functions. It is deprecated because a custom instance check - including using `parametric` - offers the same functionality. Any predicate function can be wrapped with the closest matching base class, including `object` if necessary.
```python
Cls = parametric(object, predicate)
Digits = parametric(str, str.isdigit)
assert isinstance('0', Digits)
assert not isinstance('a', Digits)
@meth.register
def _(arg: Digits): ...
```
### 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.
```python
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.
```python
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.
```python
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.
```python
class Cls(metaclass=multimeta):
... # all methods are multimethods
```
## Installation
```console
% pip install multimethod
```
## Tests
100% branch coverage.
```console
% pytest [--cov]
```
Raw data
{
"_id": null,
"home_page": null,
"name": "multimethod",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "multiple, dispatch, multidispatch, generic, functions, methods, overload",
"author": null,
"author_email": "Aric Coady <aric.coady@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ed/f3/930a6dc1d35b2ab65faffa2a75bbcc67f12d8227857188273783df4e5134/multimethod-1.12.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/multimethod/)\n\n[](https://pepy.tech/project/multimethod)\n\n[](https://github.com/coady/multimethod/actions/workflows/build.yml)\n[](https://codecov.io/gh/coady/multimethod/)\n[](https://github.com/coady/multimethod/actions/workflows/github-code-scanning/codeql)\n[](https://codspeed.io/coady/multimethod)\n[](https://github.com/astral-sh/ruff)\n[](https://mypy-lang.org/)\n\nMultimethod 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.\n\nThere 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.\n\n## Usage\nThere are a couple options which trade-off dispatch speed for flexibility.\n\nDecorator | Speed | Dispatch | Arguments\n--------- | ----- | -------- | ---------\n[multimethod](#multimethod) | faster | cached lookup | positional only\n[multidispatch](#multidispatch) | slower | binds to first signature + cached lookup | positional + keywords\n\nDispatching on simple types which use `issubclass` is cached. Advanced types which use `isinstance` require a linear scan.\n\n### multimethod\n```python\nfrom multimethod import multimethod\n\n@multimethod\ndef func(x: int, y: float):\n ...\n```\n\n`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.\n\n```python\n@multimethod\ndef func(x: float, y: int):\n ...\n```\n\nAlternatively, functions can be explicitly registered in the same style as [functools.singledispatch](https://docs.python.org/3/library/functools.html#functools.singledispatch). This syntax is also compatible with [mypy](https://mypy-lang.org), which by default checks that [each name is defined once](https://mypy.readthedocs.io/en/stable/error_code_list.html#check-that-each-name-is-defined-once-no-redef).\n\n```python\n@func.register\ndef _(x: bool, y: bool):\n ...\n\n\n@func.register(object, bool)\n@func.register(bool, object)\ndef _(x, y): # stackable without annotations\n ...\n```\n\nMultimethods are implemented as mappings from signatures to functions, and can be introspected as such.\n\n```python\nmethod[type, ...] # get registered function\nmethod[type, ...] = func # register function by explicit types\n```\n\nMultimethods 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:\n* `Union[...]` or `... | ...`\n* `Mapping[...]` - the first key-value pair is checked\n* `tuple[...]` - all args are checked\n* `Iterable[...]` - the first arg is checked\n* `Type[...]`\n* `Literal[...]`\n* `Callable[[...], ...]` - parameter types are contravariant, return type is covariant\n\nNaturally 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.\n\nDispatch resolution details:\n* If an exact match isn't registered, the next closest method is called (and cached).\n* If there are ambiguous methods - or none - a custom `TypeError` is raised.\n* Keyword-only parameters may be annotated, but won't affect dispatching.\n* A skipped annotation is equivalent to `: object`.\n* If no types are specified, it will inherently match all arguments.\n\n### multidispatch\n`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.\n\n### instance checks\n`subtype` provisionally provides `isinstance` and `issubclass` checks for generic types. When called on a non-generic, it will return the origin type.\n\n```python\nfrom multimethod import subtype\n\ncls = subtype(int | list[int])\n\nfor obj in (0, False, [0], [False], []):\n assert isinstance(obj, cls)\nfor obj in (0.0, [0.0], (0,)):\n assert not isinstance(obj, cls)\n\nfor subclass in (int, bool, list[int], list[bool]):\n assert issubclass(subclass, cls)\nfor subclass in (float, list, list[float], tuple[int]):\n assert not issubclass(subclass, cls)\n```\n\nIf 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.\n\n```python\nfrom multimethod import parametric\n\nCoroutine = parametric(Callable, asyncio.iscoroutinefunction)\nIntArray = parametric(array, typecode='i')\n```\n\n`overload` used to dispatch on annotated predicate functions. It is deprecated because a custom instance check - including using `parametric` - offers the same functionality. Any predicate function can be wrapped with the closest matching base class, including `object` if necessary.\n\n```python\nCls = parametric(object, predicate)\nDigits = parametric(str, str.isdigit)\nassert isinstance('0', Digits)\nassert not isinstance('a', Digits)\n\n@meth.register\ndef _(arg: Digits): ...\n```\n\n### classes\n`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.\n\n```python\nclass Cls:\n # @classmethod: only works here if there are no more functions\n @multimethod\n def meth(cls, arg: str): ...\n\n # @classmethod: can not be used with `register` because `_` is not the multimethod\n @meth.register\n def _(cls, arg: int): ...\n\n meth = classmethod(meth) # done with registering\n```\n\nIf a method spans multiple classes, then the namespace lookup can not work. The `register` method can be used instead.\n\n```python\nclass Base:\n @multimethod\n def meth(self, arg: str): ...\n\nclass Subclass(Base):\n @Base.meth.register\n def _(self, arg: int): ...\n```\n\nIf the base class can not be modified, the decorator - like any - can be called explicitly.\n\n```python\nclass Subclass(Base):\n meth = multimethod(Base.meth)\n ...\n```\n\n`multimeta` creates a class with a special namespace which converts callables to multimethods, and registers duplicate callables with the original.\n\n```python\nclass Cls(metaclass=multimeta):\n ... # all methods are multimethods\n```\n\n## Installation\n```console\n% pip install multimethod\n```\n\n## Tests\n100% branch coverage.\n\n```console\n% pytest [--cov]\n```\n",
"bugtrack_url": null,
"license": "Copyright 2022 Aric Coady Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "Multiple argument dispatching.",
"version": "1.12",
"project_urls": {
"Changelog": "https://github.com/coady/multimethod/blob/main/CHANGELOG.md",
"Documentation": "https://coady.github.io/multimethod",
"Homepage": "https://github.com/coady/multimethod",
"Issues": "https://github.com/coady/multimethod/issues"
},
"split_keywords": [
"multiple",
" dispatch",
" multidispatch",
" generic",
" functions",
" methods",
" overload"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af98cff14d53a2f2f67d7fe8a4e235a383ee71aba6a1da12aeea24b325d0c72a",
"md5": "df8e4b18f6e635a6e500174e8225d573",
"sha256": "fd0c473c43558908d97cc06e4d68e8f69202f167db46f7b4e4058893e7dbdf60"
},
"downloads": -1,
"filename": "multimethod-1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "df8e4b18f6e635a6e500174e8225d573",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10646,
"upload_time": "2024-07-04T16:10:06",
"upload_time_iso_8601": "2024-07-04T16:10:06.482639Z",
"url": "https://files.pythonhosted.org/packages/af/98/cff14d53a2f2f67d7fe8a4e235a383ee71aba6a1da12aeea24b325d0c72a/multimethod-1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "edf3930a6dc1d35b2ab65faffa2a75bbcc67f12d8227857188273783df4e5134",
"md5": "0741e56a9257d5679bc4d33681ae1520",
"sha256": "8db8ef2a8d2a247e3570cc23317680892fdf903d84c8c1053667c8e8f7671a67"
},
"downloads": -1,
"filename": "multimethod-1.12.tar.gz",
"has_sig": false,
"md5_digest": "0741e56a9257d5679bc4d33681ae1520",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17423,
"upload_time": "2024-07-04T16:10:08",
"upload_time_iso_8601": "2024-07-04T16:10:08.179022Z",
"url": "https://files.pythonhosted.org/packages/ed/f3/930a6dc1d35b2ab65faffa2a75bbcc67f12d8227857188273783df4e5134/multimethod-1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-04 16:10:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coady",
"github_project": "multimethod",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "multimethod"
}
JSON
