{"id":5357,"library":"ovld","title":"ovld: Overloading Python Functions","description":"Ovld is a Python library that provides fast and feature-rich multiple dispatch for functions using type annotations. Unlike Python's built-in `functools.singledispatch`, `ovld` supports dispatching on multiple arguments, custom predicates, and value-based dispatch. It aims to simplify code that would otherwise rely on complex `if-elif` chains or `isinstance` checks for different argument types. The library is actively maintained, with the current version being 0.5.15, and offers performance superior to other multiple dispatch libraries.","status":"active","version":"0.5.15","language":"python","source_language":"en","source_url":"https://github.com/breuleux/ovld","tags":["overloading","multiple dispatch","type hinting","decorators","recursion","performance"],"install":[{"cmd":"pip install ovld","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ovld","correct":"from ovld import ovld"},{"note":"Used for variant-aware recursive calls within overloaded functions.","symbol":"recurse","correct":"from ovld import ovld, recurse"},{"note":"For creating value-dependent types for dispatching.","symbol":"Dependent","correct":"from ovld.dependent import Dependent"},{"note":"Commonly used with ovld for dispatching on specific values.","symbol":"Literal","correct":"from typing import Literal"}],"quickstart":{"code":"from ovld import ovld, recurse\nfrom typing import Literal\n\n@ovld\ndef process(x: str): \n    return f\"Processing string: {x!r}\"\n\n@ovld\ndef process(x: int):\n    return f\"Processing integer: {x}\"\n\n@ovld\ndef process(x: int, y: int):\n    return f\"Processing two integers: {x}, {y}\"\n\n@ovld\ndef process(x: Literal[0]):\n    return \"Special case: zero\"\n\n# Example of recursive overload\n@ovld\ndef add_nested(x: list, y: list):\n    return [recurse(a, b) for a, b in zip(x, y)]\n\n@ovld\ndef add_nested(x: int, y: int):\n    return x + y\n\nassert process(\"hello\") == \"Processing string: 'hello'\"\nassert process(10) == \"Processing integer: 10\"\nassert process(1, 2) == \"Processing two integers: 1, 2\"\nassert process(0) == \"Special case: zero\"\n\nassert add_nested([1, 2], [3, 4]) == [4, 6]\nassert add_nested([1, [2]], [3, [4]]) == [4, [6]]\n","lang":"python","description":"This quickstart demonstrates basic function overloading for different types and argument counts. It also includes an example of recursive dispatch using `recurse`, which is essential for ensuring that nested calls respect `ovld`'s dispatch mechanism and any defined variants."},"warnings":[{"fix":"Replace direct recursive calls (e.g., `my_func(a, b)`) with `recurse(a, b)` inside `@ovld` decorated functions.","message":"When defining recursive `ovld` functions, always use `recurse(...)` instead of directly calling the function by its name (e.g., `my_func(...)`). `recurse` is specially designed to work with `ovld`'s variant system, ensuring that recursive calls correctly dispatch to the appropriate variant of the current `ovld` object. Direct calls will bypass this mechanism.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the first argument to `Dependent` is a valid Python type that acts as a bound, and the second argument is a callable predicate that operates on the argument's value.","message":"Dependent types created with `ovld.dependent.Dependent` require a type bound as their first argument (e.g., `Dependent[int, lambda n: n > 0]`). The provided check function is applied to the *value* of the argument at runtime, not its static type. Incorrectly specifying the type bound or the check predicate can lead to unexpected dispatch behavior or runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of this limitation and implement additional runtime checks if strict validation of all elements in generic collections is required, or define more specific overloads.","message":"When using `ovld` to dispatch on generic collection types (e.g., `list[str]`), `ovld` currently only checks the type of the *first element* of the collection. It does not perform a full validation of all elements within the collection against the generic type parameter. This can lead to a dispatch if the first element matches, even if subsequent elements do not.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If intermediate results need processing, wrap the `recurse()` calls explicitly or define custom dispatch logic instead of relying solely on `postprocess`.","message":"The `postprocess` argument in the `@ovld` decorator (or `ovld.dispatch`) only applies to the *top-level* call of the overloaded function. Intermediate recursive calls made via `recurse()` will *not* have their results processed by the `postprocess` function.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.5.15':76 'activ':69 'aim':45 'annot':23 'argument':36,64 'base':42 'built':28 'built-in':27 'chain':58 'check':61 'code':48 'complex':54 'current':73 'custom':37 'decor':91 'differ':63 'dispatch':18,33,43,84,88 'elif':57 'fast':12 'featur':15 'feature-rich':14 'function':4,20 'functools.singledispatch':30 'hint':90 'if-elif':55 'isinst':60 'librari':9,67,85 'maintain':70 'multipl':17,35,83,87 'offer':78 'otherwis':51 'overload':2,86 'ovld':1,5,31 'perform':79,93 'predic':38 'provid':11 'python':3,8,25 'recurs':92 'reli':52 'rich':16 'simplifi':47 'superior':80 'support':32 'type':22,65,89 'unlik':24 'use':21 'valu':41 'value-bas':40 'version':74 'would':50","created_at":"2026-04-14T01:30:22.038166+00:00","updated_at":"2026-04-16T17:50:25.090367+00:00","problems":[{"fix":"To resolve this, define a more specific `@ovld` overload that exactly matches the ambiguous call's argument types, or refine existing overloads to ensure a clear hierarchy and specificity.","cause":"This error occurs when multiple `@ovld` decorated functions have signatures that equally match the arguments provided, making it impossible for `ovld` to determine the most specific or appropriate function to call.","error":"TypeError: Ambiguous call to 'function_name'"},{"fix":"Verify the spelling of `ovld` and other components you are trying to import (e.g., `OvldMC`). The main decorator is typically `ovld` and the metaclass is `OvldMC`.","cause":"This usually indicates a typo in the import statement or an attempt to import a specific component (like 'ovld' or 'OvldMC') that might be misspelled or not directly available under that name from the top-level `ovld` package.","error":"ImportError: cannot import name 'ovld' from 'ovld'"},{"fix":"Inspect the arguments being passed and the `@ovld` definitions. Either adjust the arguments to conform to an existing overload's signature, or define a new `@ovld` overload with a signature (type annotations and/or predicates) that correctly matches the argument types being provided.","cause":"This error signifies that the arguments passed to an `@ovld` decorated function do not match the type annotations or predicates of any of the defined overloads for that particular function.","error":"RuntimeError: No matching overloads found for 'function_name'"},{"fix":"Instead of `isinstance(obj, list[int])`, use `typing.get_origin()` and `typing.get_args()` to inspect generic types at runtime if you need to check both the base type and its parameters. Alternatively, leverage `ovld`'s built-in support for generic collections which handles checks like `list[str]` by inspecting the first element or overall type.","cause":"This Python runtime error occurs when `isinstance()` or `issubclass()` is used with a parameterized generic type (e.g., `list[int]`, `Iterable[str]`). While `ovld` uses type annotations for dispatch, direct runtime checks with parameterized generics in custom predicates or other logic are not supported by Python's built-in `isinstance`.","error":"TypeError: isinstance() argument 2 cannot be a parameterized generic."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.17","cli_name":"","cli_version":null,"type":"library","homepage":"https://ovld.readthedocs.io/en/latest/","github":"https://github.com/breuleux/ovld","docs":"https://ovld.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/ovld/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}