Overloading

Common errors

• TypeError: 'staticmethod' object is not callable

  cause Incorrect decorator order where `@staticmethod` or `@classmethod` is placed before `@overload`.
  fix Due to a breaking change in v0.5, place `@staticmethod` or `@classmethod` *after* the `@overload` decorator. ```python @overload @staticmethod def my_method(arg: str): return f'Static method with {arg}' ```

• overloading.errors.NoApplicableOverload: No applicable overload found for my_function(<class 'float'>)

  cause An overloaded function was called with argument types for which no matching `@overload` implementation has been defined.
  fix Define an `@overload` for the specific argument types being passed, or provide a more general overload (e.g., using `object`) that can act as a fallback. Ensure type hints accurately reflect expected inputs.

• overloading.errors.AmbiguityError: Ambiguous overloads for process_data(<class 'int'>, <class 'int'>)

  cause The dispatcher found multiple `@overload` implementations that could equally match the given runtime arguments, leading to an ambiguous choice.
  fix Refine the type hints in your `@overload` definitions to be more specific, ensuring that for any given set of arguments, only one overload provides the 'most accurate match'. This often means adding more specific type hints to resolve overlaps.

Warnings

• breaking Between v0.4 and v0.5, the treatment of `classmethod` and `staticmethod` was harmonized. These decorators must now appear *after* the `@overload` directive.
  Fix: Ensure `@classmethod` or `@staticmethod` is placed below `@overload`: ```python @overload @classmethod def my_method(cls, arg: int): ... ```
• gotcha Python does not have native function overloading; the `overloading` library provides runtime dispatch based on argument types. Do not confuse it with `typing.overload`, which is solely for static type checkers and does not affect runtime behavior.
  Fix: Always import `overload` from the `overloading` library (`from overloading import overload`) for runtime dispatch. If you only need type-checker hints without runtime behavior modification, use `from typing import overload` (Python 3.5+).
• gotcha The library's last release was in 2016, indicating it is no longer actively maintained. While functional, it might not fully leverage newer Python features or integrate seamlessly with modern type-hinting patterns as well as alternatives like `functools.singledispatch` (for single-argument dispatch) or `multimethod` for more active maintenance.
  Fix: Consider `functools.singledispatch` for single-argument type-based dispatch (standard library, Python 3.4+) or `multimethod` for a more actively maintained third-party multiple-dispatch solution if long-term support and modern features are critical.

Install

• pip install overloading Install core library
• pip install typing Install typing module for Python < 3.5 (optional)

Imports

• overload
  wrong:

  from typing import overload

  correct:

  from overloading import overload

  The `typing.overload` decorator is for static type checking only and does not provide runtime dispatch like this library.

Quickstart

This example demonstrates how to define multiple implementations of a function `biggest` using the `@overload` decorator. The library automatically dispatches to the correct implementation based on the runtime type of the `items` argument.

from collections.abc import Iterable
from overloading import overload

@overload
def biggest(items: Iterable[int]):
    return max(items)

@overload
def biggest(items: Iterable[str]):
    return max(items, key=len)

print(biggest([2, 0, 15, 8, 7]))
print(biggest(['a', 'abc', 'bc']))