refactor: Replace ad-hoc dispatch with custom @singledispatch

[dangotbanned]

Description

Adds a slimmed-down version of @functools.singledispatch, with the initial use replacing _supertyping._same_supertype in #3396.

I can see a few other places (particularly DType-related) that could later benefit.
So, I went ahead and added more tests + docs than I would normally do for an internal tool.

Why not @functools.singledispatch?

Most of the stdlib code is dedicated to two features I don't want to use.

mro-based dispatch

That allows you to register ABCs (like Mapping, Iterable, etc) or any regular class and have it's subclasses match.

Definitely pretty clever stuff, but I'd prefer to have a simpler version that needs every class to be added explicitly

• https://github.com/python/cpython/blob/cf71e34940e2314ee7ca00961d86a7172286eeea/Lib/functools.py#L756-L894
• https://github.com/python/cpython/blob/cf71e34940e2314ee7ca00961d86a7172286eeea/Lib/functools.py#L921-L926

Registration via annotation

Forward references are resolved eagerly¹ and only classes and unions of classes are supported.

IMO, that's just a complicated way of accepting *types: type[Any] in the decorator - so I did that instead 😅

• https://github.com/python/cpython/blob/cf71e34940e2314ee7ca00961d86a7172286eeea/Lib/functools.py#L937-L941
• https://github.com/python/cpython/blob/cf71e34940e2314ee7ca00961d86a7172286eeea/Lib/functools.py#L959-L991

Related issues

• Child of feat(DRAFT): Add get_supertype #3396

Footnotes

1. ibis has @lazy_singledispatch that appears to solve this issue ↩

[dangotbanned]

All of these comments are were an attempt at a literate style 🙂

Initially I wanted to have some examples in the docstrings (in _dispatch.py), but:

• Anything non-trivial requires a very large docstring
• I couldn't think of anything simple that captures the strengths of the concept

[dangotbanned]

I've left out validating the types for now.

• 3.9: @functools.singledispatch supports type[Any]
• 3.10: Same support, but that's the version which introduces types.UnionType
• 3.11: @functools.singledispatch supports typing.Union | types.UnionType | type[Any]

Since #3204 is not resolved, I'd rather leave this runtime check until then

[dangotbanned]

@FBruzzesi
I'm not sure if (#3396 (comment)) got lost, but I thought I'd give convincing you one last try 🙂

#3410 is a beautiful solution, but, at the same time, quite intense to maintain.
It requires it's dedicated test suite

I think this was a documentation issue on my part.
I tried out (literate-style tests), but as you can see from (revert: Keep only what is required) - removing all of that left only 2 lines uncovered.

Do you still have the opinion that (https://github.com/narwhals-dev/narwhals/blob/308f389f2e68079053e9c659394cdd0d4207410d/narwhals/_dispatch.py) is intense to maintain?

---

and it serves a single purpose in the codebase, which makes me feel a bit uneasy on it.

I thought replacing lots of other non-supertyping stuff wouldn't be a good idea in this PR, since it was based on dtypes/supertyping.

Here's three unrelated use-cases (dtypes/supertyping-dispatch...@just_dispatch-use-cases).
Only one was what I had planned in the PR description:

I can see a few other places (particularly DType-related) that could later benefit.

I do feel the need to stress that these are not the only places that can use it! 😅
Just didn't wanna go replacing too much if it is a hard no