# Dispatchery 🧙‍♂️✨
> **Dispatch your functions based on complex types.**
`dispatchery` is a lightweight Python package inspired by the standard `singledispatch` decorator, but with support for complex, nested, parameterized types. With `dispatchery`, you can dispatch based on annotations such as `tuple[int, str, dict[str, int]]` or `list[dict[str, list[int]]]`.
Unlike `singledispatch`, `dispatchery` can also dispatch based on multiple arguments and keyword arguments, rather than only the first one. It also supports nested types and union types such as `Union[int, str]` or `int | str`, making it a powerful tool for writing clean, type-specific code.
## Features
- **Advanced Type Dispatching**: Supports complex generic types.
- **Recursive Type Matching**: Handles nested types like `tuple[int, str, dict[str, int]]`.
- **Union Types**: Dispatch based on union types like `Union[int, str]`.
- **Multi Argument Dispatch**: Dispatch based on multiple arguments types, not just the first.
- **Method Overloading**: Works with object methods just the same.
- **Simple Integration**: Works just like `functools.singledispatch` with added power.
## Installation
Install `dispatchery` from PyPI:
```bash
pip install dispatchery
```
## Usage
If you know how to use `functools.singledispatch` then you already know how to use `dispatchery`. Decorate your main function with `@dispatchery` and register specific types as needed.
### Examples
Suppose we want a function, `process`, that behaves differently based on complex types like `tuple[int, str]`, `list[str]`, or `str | int`, we can use `dispatchery` to achieve this:
```python
from dispatchery import dispatchery
@dispatchery
def process(value):
return "Standard stuff."
@process.register
def _(value: list[str]):
return "Nice, a parameterized type."
@process.register
def _(value: list[int]):
return "That's different? Cool."
@process.register
def _(value: list[tuple[int, str]]):
return "Nested, too? Alright."
@process.register
def _(value: bool | str | int):
return "Union types? No problem."
@process.register
def _(value: list[tuple[int | list[float], dict[str, tuple[list[bool], dict[str, float | str]]]]]):
return "Now this is just getting silly."
print(process(1.111)) # "Standard stuff."
print(process(["hello", "world"])) # "Nice, a parameterized type."
print(process([1, 2, 3])) # "That's different? Cool."
print(process([(1, "hello"), (2, "world")])) # "Nested, too? Alright."
print(process(True)) # "Union types? No problem."
print(process([(1, {"a": ([True, False], {"x": 3.14})})])) # "Now this is just getting silly."
```
### Multi Argument Dispatch
`dispatchery` also supports dispatching based on multiple arguments:
```python
@dispatchery
def process(a, b):
pass
@process.register
def _(a: int, b: str):
return "Beep boop."
@process.register
def _(a: str, b: int):
return "Boppity bop."
print(process(42, "hello")) # "Beep boop."
print(process("hello", 42)) # "Boppity bop."
```
### Keyword Arguments
You can also dispatch with kwargs:
```python
@dispatchery
def process(a, key="hello"):
pass
@process.register
def _(a: str, key: int = 42):
return "Round number."
@process.register
def _(a: str, key: float = 3.14):
return "Decimals."
print(process("hello", key=1987)) # "Round number."
print(process("hello", key=1.618)) # "Decimals."
```
### Method Overloading
Working with classes is just as easy:
```python
from dispatchery import dispatchery
class MyClass:
@dispatchery
def my_method(self, value1):
return "default"
@my_method.register
def _(self, value1: list):
return "list"
@my_method.register
def _(self, value1: list[int]):
return "list[int]"
@my_method.register
def _(self, value1: list[str]):
return "list[str]"
obj = MyClass()
print(obj.my_method(42)) # "default"
print(obj.my_method([1, "a", 2, "b", 3, "c"])) # "list"
print(obj.my_method([1, 2, 3])) # "list[int]"
print(obj.my_method(["a", "b", "c"])) # "list[str]"
```
### Types as Decorator Parameters
You can also pass types as arguments to the decorator instead of using type hints:
```python
@dispatchery
def process(a, b):
pass
@process.register(int, str)
def _(a, b):
pass
@process.register(str, int)
def _(a, b):
pass
```
## Why Use Dispatchery?
- **Better Readability**: Your code is clean and type-specific without bulky type-checking clutter.
- **Enhanced Maintainability**: Add new types easily without modifying existing code.
- **More Flexible**: Embrace the power of Python’s dynamic typing with elegant dispatching.
## Optimizing Performance
By default `dispatchery` runs in `strict mode`. This means that it will check every value in lists and dictionaries for type matching. If you are planning to process lists of millions of items, this can be quite computationally expensive, so you may want to disable it:
```python
from dispatchery import dispatchery
dispatchery.strict_mode = False
```
This will massively speedup execution for long values, but only the first item in the list will be used for type matching.
Moreover `dispatchery` has a built-in cache that stores the type matching results. This cache is disabled by default, but you can enable it by setting the `cached_mode` attribute to `True`:
```python
from dispatchery import dispatchery
dispatchery.cached_mode = True
```
For most use cases the overhead from the cache is larger than the gains, so it's generally not worth it. But if you need to do a lot of dispatching per second with recurring complex types, it can potentially speedup `dispatchery` significantly.
## Dependencies
None, but you might want `typing-extensions>=3.7` if you need backward compatibility for typing features.
## Integration
To integrate dispatchery in an existing codebase, you can import it as a drop-in replacement for `singledispatch`:
```python
from dispatchery import dispatchery as singledispatch
```
## License
`dispatchery` is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/bolaft/dispatchery",
"name": "dispatchery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "dispatch, type-safety, singledispatch, functools, typing, types",
"author": "Soufian Salim",
"author_email": "soufian.salim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d9/7c/50ff70147f00be68fc4f7fabe09ced3bf7347138d8ae5664b176642ac07c/dispatchery-0.3.2.tar.gz",
"platform": null,
"description": "# Dispatchery \ud83e\uddd9\u200d\u2642\ufe0f\u2728 \n> **Dispatch your functions based on complex types.**\n\n`dispatchery` is a lightweight Python package inspired by the standard `singledispatch` decorator, but with support for complex, nested, parameterized types. With `dispatchery`, you can dispatch based on annotations such as `tuple[int, str, dict[str, int]]` or `list[dict[str, list[int]]]`.\n\nUnlike `singledispatch`, `dispatchery` can also dispatch based on multiple arguments and keyword arguments, rather than only the first one. It also supports nested types and union types such as `Union[int, str]` or `int | str`, making it a powerful tool for writing clean, type-specific code.\n\n## Features\n\n- **Advanced Type Dispatching**: Supports complex generic types.\n- **Recursive Type Matching**: Handles nested types like `tuple[int, str, dict[str, int]]`.\n- **Union Types**: Dispatch based on union types like `Union[int, str]`.\n- **Multi Argument Dispatch**: Dispatch based on multiple arguments types, not just the first.\n- **Method Overloading**: Works with object methods just the same.\n- **Simple Integration**: Works just like `functools.singledispatch` with added power.\n\n## Installation\n\nInstall `dispatchery` from PyPI:\n\n```bash\npip install dispatchery\n```\n\n## Usage\n\nIf you know how to use `functools.singledispatch` then you already know how to use `dispatchery`. Decorate your main function with `@dispatchery` and register specific types as needed.\n\n### Examples\n\nSuppose we want a function, `process`, that behaves differently based on complex types like `tuple[int, str]`, `list[str]`, or `str | int`, we can use `dispatchery` to achieve this:\n\n```python\nfrom dispatchery import dispatchery\n\n@dispatchery\ndef process(value):\n return \"Standard stuff.\"\n\n@process.register\ndef _(value: list[str]):\n return \"Nice, a parameterized type.\"\n\n@process.register\ndef _(value: list[int]):\n return \"That's different? Cool.\"\n\n@process.register\ndef _(value: list[tuple[int, str]]):\n return \"Nested, too? Alright.\"\n\n@process.register\ndef _(value: bool | str | int):\n return \"Union types? No problem.\"\n\n@process.register\ndef _(value: list[tuple[int | list[float], dict[str, tuple[list[bool], dict[str, float | str]]]]]):\n return \"Now this is just getting silly.\"\n\nprint(process(1.111)) # \"Standard stuff.\"\nprint(process([\"hello\", \"world\"])) # \"Nice, a parameterized type.\"\nprint(process([1, 2, 3])) # \"That's different? Cool.\"\nprint(process([(1, \"hello\"), (2, \"world\")])) # \"Nested, too? Alright.\"\nprint(process(True)) # \"Union types? No problem.\"\nprint(process([(1, {\"a\": ([True, False], {\"x\": 3.14})})])) # \"Now this is just getting silly.\"\n```\n\n### Multi Argument Dispatch\n\n`dispatchery` also supports dispatching based on multiple arguments:\n\n```python\n@dispatchery\ndef process(a, b):\n pass\n\n@process.register\ndef _(a: int, b: str):\n return \"Beep boop.\"\n\n@process.register\ndef _(a: str, b: int):\n return \"Boppity bop.\"\n\nprint(process(42, \"hello\")) # \"Beep boop.\"\nprint(process(\"hello\", 42)) # \"Boppity bop.\"\n```\n\n### Keyword Arguments\n\nYou can also dispatch with kwargs:\n\n```python\n@dispatchery\ndef process(a, key=\"hello\"):\n pass\n\n@process.register\ndef _(a: str, key: int = 42):\n return \"Round number.\"\n\n@process.register\ndef _(a: str, key: float = 3.14):\n return \"Decimals.\"\n\nprint(process(\"hello\", key=1987)) # \"Round number.\"\nprint(process(\"hello\", key=1.618)) # \"Decimals.\"\n```\n\n### Method Overloading\n\nWorking with classes is just as easy:\n\n```python\nfrom dispatchery import dispatchery\n\n\nclass MyClass:\n @dispatchery\n def my_method(self, value1):\n return \"default\"\n\n @my_method.register\n def _(self, value1: list):\n return \"list\"\n\n @my_method.register\n def _(self, value1: list[int]):\n return \"list[int]\"\n\n @my_method.register\n def _(self, value1: list[str]):\n return \"list[str]\"\n\n\nobj = MyClass()\n\nprint(obj.my_method(42)) # \"default\"\nprint(obj.my_method([1, \"a\", 2, \"b\", 3, \"c\"])) # \"list\"\nprint(obj.my_method([1, 2, 3])) # \"list[int]\"\nprint(obj.my_method([\"a\", \"b\", \"c\"])) # \"list[str]\"\n```\n\n### Types as\u00a0Decorator Parameters\n\nYou can also pass types as arguments to the decorator instead of using type hints:\n\n```python\n@dispatchery\ndef process(a, b):\n pass\n\n@process.register(int, str)\ndef _(a, b):\n pass\n\n@process.register(str, int)\ndef _(a, b):\n pass\n```\n\n## Why Use Dispatchery?\n\n- **Better Readability**: Your code is clean and type-specific without bulky type-checking clutter.\n- **Enhanced Maintainability**: Add new types easily without modifying existing code.\n- **More Flexible**: Embrace the power of Python\u2019s dynamic typing with elegant dispatching.\n\n## Optimizing Performance\n\nBy default `dispatchery` runs in `strict mode`. This means that it will check every value in lists and dictionaries for type matching. If you are planning to process lists of millions of items, this can be quite computationally expensive, so you may want to disable it:\n\n```python\nfrom dispatchery import dispatchery\n\ndispatchery.strict_mode = False\n```\n\nThis will massively speedup execution for long values, but only the first item in the list will be used for type matching.\n\nMoreover `dispatchery` has a built-in cache that stores the type matching results. This cache is disabled by default, but you can enable it by setting the `cached_mode` attribute to `True`:\n\n```python\nfrom dispatchery import dispatchery\n\ndispatchery.cached_mode = True\n```\n\nFor most use cases the overhead from the cache is larger than the gains, so it's generally not worth it. But if you need to do a lot of dispatching per second with recurring complex types, it can potentially speedup `dispatchery` significantly.\n\n## Dependencies\n\nNone, but you might want `typing-extensions>=3.7` if you need backward compatibility for typing features.\n\n## Integration\n\nTo integrate dispatchery in an existing codebase, you can import it as a drop-in replacement for `singledispatch`:\n\n```python\nfrom dispatchery import dispatchery as singledispatch\n```\n\n## License\n\n`dispatchery` is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for advanced function dispatching based on complex, nested, and parameterized types. Inspired by singledispatch.",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/bolaft/dispatchery"
},
"split_keywords": [
"dispatch",
" type-safety",
" singledispatch",
" functools",
" typing",
" types"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "805afeff46a98ac8ac9dcec688d3b0fbb3022a6fe8afe197723cc463500e7238",
"md5": "7270c90a77af185f2eec9cf0405e81b9",
"sha256": "b068e59de9dfb7fa9c431fef56a6f4322c6ee345fe55a18c108fd01fb83dde87"
},
"downloads": -1,
"filename": "dispatchery-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7270c90a77af185f2eec9cf0405e81b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9944,
"upload_time": "2024-11-20T17:17:35",
"upload_time_iso_8601": "2024-11-20T17:17:35.451879Z",
"url": "https://files.pythonhosted.org/packages/80/5a/feff46a98ac8ac9dcec688d3b0fbb3022a6fe8afe197723cc463500e7238/dispatchery-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d97c50ff70147f00be68fc4f7fabe09ced3bf7347138d8ae5664b176642ac07c",
"md5": "2c641b02427a2dd46e79433ade45992c",
"sha256": "4b8c9a0204a2fc571b313df2fd012bc8dab4606bf435ebedfdc63c0b6435051a"
},
"downloads": -1,
"filename": "dispatchery-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "2c641b02427a2dd46e79433ade45992c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 13497,
"upload_time": "2024-11-20T17:17:36",
"upload_time_iso_8601": "2024-11-20T17:17:36.405903Z",
"url": "https://files.pythonhosted.org/packages/d9/7c/50ff70147f00be68fc4f7fabe09ced3bf7347138d8ae5664b176642ac07c/dispatchery-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 17:17:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bolaft",
"github_project": "dispatchery",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dispatchery"
}
JSON
