Make use of the `@overload` decorator

[Joseph-Edwards]

At the moment, many of our functions accept "words" as arguments, which means either objects of type str or list[int]. When there is only a single word in the parameter this is fine; however, if there are more, then there is some ambiguity. If a function has signature foo(x : str | list[int], y: str | list[int]), we presently have no way of showing that x and y should have the same type. The concept of overloads would fix this in the following way:

from typing import overload

@overload
def foo(x: str, y: str):
    pass

@overload
def foo(x: list[int], y: list[int]):
    pass

def foo(x: str | list[int], y: str | list[int]):
    """Do something with x and y.

    :param x: A string or list of ints.
    :param y: A string or list of ints — must match the type of x.
    """
    print(f"{x=}, {y=}")

Then, in the documentation, we would see something like:

If it is possible to integrate this nicely with the stuff generated by pybind11, potentially through the use of stub files, then we should do so.