ovld: Overloading Python Functions

Warnings

• gotcha 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.
  Fix: Replace direct recursive calls (e.g., `my_func(a, b)`) with `recurse(a, b)` inside `@ovld` decorated functions.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: If intermediate results need processing, wrap the `recurse()` calls explicitly or define custom dispatch logic instead of relying solely on `postprocess`.

Install

• pip install ovld Install stable version

Imports

• ovld

  from ovld import ovld

• recurse

  from ovld import ovld, recurse

  Used for variant-aware recursive calls within overloaded functions.
• Dependent

  from ovld.dependent import Dependent

  For creating value-dependent types for dispatching.
• Literal

  from typing import Literal

  Commonly used with ovld for dispatching on specific values.

Quickstart

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.

from ovld import ovld, recurse
from typing import Literal

@ovld
def process(x: str): 
    return f"Processing string: {x!r}"

@ovld
def process(x: int):
    return f"Processing integer: {x}"

@ovld
def process(x: int, y: int):
    return f"Processing two integers: {x}, {y}"

@ovld
def process(x: Literal[0]):
    return "Special case: zero"

# Example of recursive overload
@ovld
def add_nested(x: list, y: list):
    return [recurse(a, b) for a, b in zip(x, y)]

@ovld
def add_nested(x: int, y: int):
    return x + y

assert process("hello") == "Processing string: 'hello'"
assert process(10) == "Processing integer: 10"
assert process(1, 2) == "Processing two integers: 1, 2"
assert process(0) == "Special case: zero"

assert add_nested([1, 2], [3, 4]) == [4, 6]
assert add_nested([1, [2]], [3, [4]]) == [4, [6]]