It's not currently possible to use singledispatch with a function annotated with a Union type, although the desired behaviour is clear.

Example:

    from functools import singledispatch
    from typing import Union

    @singledispatch
    def test(arg):
        raise ValueError(arg)

    @test.register
    def _(arg: Union[int, float]):
        print(f"{arg} is a number")

    test(1)

This dies with:

TypeError: Invalid annotation for 'arg'. typing.Union[int, float] is not a class.

I've implemented a workaround which digs the types out of the union and registers them one-by-one:

    from functools import singledispatch
    from typing import Union, get_type_hints

    def register_for_union_type(target_fn):
        def decorator(fn):
            arg_type = list(get_type_hints(fn).values())[0]
            assert arg_type.__origin__ is Union
            for type_ in arg_type.__args__:
                fn = target_fn.register(type_)(fn)
            return fn

        return decorator

    @singledispatch
    def test(arg):
        raise ValueError(arg)

    @register_for_union_type(test)
    def _(arg: Union[int, float]):
        print(f"{arg} is a number")

    test(1)

Looking at the source for singledispatch is doesn't look like it would too difficult to add support for something like this, though of course there may be subtleties I've missed. Would you be open to a patch?

The only other mentions I've found of this online are:
https://mail.python.org/archives/list/python-ideas@python.org/thread/HF5HDXQ2SXZHO3TWODIRQATTE4TCAWPL/
https://stackoverflow.com/questions/61721761/type-hints-and-singledispatch-how-do-i-include-union-in-an-extensible-w

New changeset 3cb357a by Yurii Karabas in branch 'main':
bpo-46014: Add ability to use typing.Union with singledispatch (GH-30017)
3cb357a

Support added as an enhancement in Python 3.11. Thanks, Yurii! ✨ 🍰 ✨

This is awesome! Should a note be added to the functools documentation mentioning the new feature? (Genuine question — I'm not sure whether it's necessary myself.)

Will it support Optional as well?

According to PEP-604, these two shall be equivalent (using Python 3.10 below)?

type(int | None)
types.UnionType

type(tp.Optional[int])
typing._UnionGenericAlias

Also, IMHO, the documentation of singledispatch should be improved. It needs to state that only Python types are supported with few exceptions (union type now), but other annotation types are not supported, i.e. generics like list[int].

>>> from typing import Optional, get_origin
>>> get_origin(Optional[int])
typing.Union

^Because of that, it will work with typing.Optional as well as typing.Union and types.UnionType, yes.

I am planning on submitting a docs PR at some point in the next few days (probably linked to a new BPO issue).

Reopening as per #32282 (comment)

>>> from typing import Optional, get_origin
>>> get_origin(Optional[int])
typing.Union

^Because of that, it will work with typing.Optional as well as typing.Union and types.UnionType, yes.

It does indeed work (continuing from the OP's example):

>>> @test.register
... def _(arg: str  | None):
...     print(f"{arg} may be a string")
... 
>>> test(None)
None may be a string
>>> test("x")
x may be a string

But it's not obvious that it should, because None isn't a type. It apparently works because None gets turned into type(None) somewhere along the way in typing.py, but this seems worth testing explicitly in test_functools.

So anyone up for adding a test case that uses an Optional type?

Thanks @Thaddeus1499 for contributing more tests.