Metadata-Version: 2.4
Name: multiarg-dispatch
Version: 0.1.0
Summary: A replacement function for single dispatch that allows dispatching based on type hints for all arguments.
Project-URL: Homepage, https://github.com/gblokker/multiarg-dispatch
Project-URL: Repository, https://github.com/gblokker/multiarg-dispatch
Project-URL: Issues, https://github.com/gblokker/multiarg-dispatch/issues
Author-email: Goof Blokker <goofb@live.nl>
License: MIT
License-File: LICENSE
Keywords: dispatch,functools,generic functions,multidispatch,type hints
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# multiarg-dispatch

`multiarg-dispatch` is a Python package that extends the functionality of `functools.singledispatch` to allow dispatching based on **type hints for all arguments**, not just the first one. It provides a simple decorator to define generic functions with multiple implementations depending on argument types.

## Features

- Dispatch functions based on the types of **all arguments**, including keyword arguments.
- Supports **union types** in type hints.
- Raises a warning if arguments have default values (since defaults are not considered during dispatch).
- Type checking enforced at registration: all parameters must have type hints.
- Fully compatible with Python >3.11.
- **Note** that the registry uses strong references, so for garbage collection do not forget to delete the function that uses multidispatch.
- **Note** that local classes cannot be used as type hints, since these are accessible globally to retrieve as type hint.

## Installation

Install from PyPI:

```bash
pip install multiarg-dispatch
```

Or with uv:

```bash
uv add multiarg-dispatch
```

## Usage

```python
from multiarg_dispatch import multidispatch, DispatchWarning

@multidispatch
def test_func(a, b=None):
    return "default"

@test_func.register
def _(a: int, b: str = "default") -> str:
    return f"int:{a},str:{b}"

@test_func.register
def _(a: str, b: list = []) -> str:
    if b is None:
        b = []
    return f"str:{a},list:{b}"

@test_func.register
def _(a: float, b: str | list = "default") -> str:
    return f"float:{a},union:{b}"

print(test_func(10))            # int:10,str:default
print(test_func("hello", []))   # str:hello,list:[]
print(test_func(3.14, "extra")) # float:3.14,union:extra
```

## API

### `multidispatch(func)`

Decorator to make a function multi-dispatch capable.

* `register(func)`: Register a new implementation based on type hints.
* `dispatch(cls)`: Retrieve the implementation for given types.
* `registry`: Read-only view of all registered implementations.

### `DispatchWarning`

Warning raised when dispatching might be affected by defaults.

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository.
2. Create a feature branch (`git checkout -b feature/my-feature`).
3. Make your changes.
4. Ensure all tests pass (`pytest` recommended).
5. Open a Pull Request with a clear description of your changes.

Please follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines and include type hints where appropriate.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.