gh-84644: Fix singledispatch annotation parsing

[johnslavik]

A very practical but more general approach than GH-140255 to fixing annotation parsing in functools.singledispatch and functools.singledispatchmethod.

Fixes issues GH-84644, GH-130827, and GH-143886.

It can be broken if one uses a user-defined alternative implementation of staticmethod or something analogous.
Will break incorrect but working registrees. I haven't investigated stripping Annotated typeforms yet.

Consulting a test which fails with this fix at https://github.com/python/cpython/pull/130309/changes#r2663516538 -- I think that the test is wrong.

[johnslavik]

@picnixz, could you please re-review? :)

(The force-push was intentional; I know this is discouraged but I want to save noise, you can still follow what happened.)

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33748676 | 📁 Comparing b0ae4d1 against main (1f649fe)

  🔍 Preview build  

20 files changed · ± 20 modified

± Modified

• c-api/type.html
• deprecations/index.html
• deprecations/pending-removal-in-3.18.html
• library/annotationlib.html
• library/asyncio-subprocess.html
• library/csv.html
• library/ctypes.html
• library/exceptions.html
• library/functools.html
• library/logging.handlers.html
• and 10 more...

[JelleZijlstra]

I'm not sure it's valuable to specifically disallow return annotations if we still allow dispatching by annotations on wrong parameters.

[johnslavik]

I'm not sure it's valuable to specifically disallow return annotations if we still allow dispatching by annotations on wrong parameters.

We could deprecate cases when the chosen parameter isn't the same as in my new formula. @picnixz prefers to just document the limitation. And when the deprecation ends, we break custom descriptors that emulate static method behavior (which nowadays seems less of a risk than I originally thought, case looks extremely rare and it's a trivial fix).

[encukou]

I'm not sure it's valuable to specifically disallow return annotations if we still allow dispatching by annotations on wrong parameters.

Yeah, it's not very valuable. But in other cases we can't really be sure something is wrong, and the check is cheap. +0; I'd merge it.

[encukou]

New deprecations should not get backported. The docs improvements will need manual backports.

I was too quick :/