bpo-32227: functools.singledispatch supports registering via type annotations

[ambv]

With the patch attached to this issue, @singledispatch gains support for passing the type in @register via annotations.

This looks more natural and enables more thorough type checking without repeating yourself:

@singledispatch
def generic(arg): ...

@generic.register
def _(arg: str): ...

@generic.register
def _(arg: int): ...

The previous API is still available for backwards compatibility, as well as stacking, and use with classes (sic, I was surprised to learn it's used that way, too).

The patch should be uncontroversial, maybe except for the fact that it's importing the typing module if annotations are used. This is necessary because of forward references, usage of None as a type, and so on. More importantly, with PEP 563 it's mandatory.

https://bugs.python.org/issue32227

[bitdancer]

I would put these examples in the opposite order. Show the traditional way first, and then say, "if you are using type annotations in your code, you don't need to repeat the type information in the @register call:"

[ambv]

Why?

[ncoghlan]

I think the current order is OK, but the lead in sentence for the different examples need to be changed. Something like:

... If using type annotations in your code, just apply the decorator, and it will infer the appropriate overload based on the first parameter's annotation::

And then:

For code which doesn't use type annotations, the appropriate type parameter can instead be passed explicitly to the decorator itself:

[merwok]

Why: because type hinting is still new and not known or used by most people on most projects.

[ambv]

I like Nick's suggestion and applied it in the latest commit.

[bitdancer]

I would still prefer for the default (that is the first presented) to be no-type-hints, but I'm not going to block this, The reason is stronger than Merwok's "type hinting is still new". I don't want type hinting in my code (having it in external stubs is fine with me), and I would prefer that python's default remain no type hinting. That is the stance we have taken for the standard library and the documentation, and this is part of our documentation ;)

[ambv]

This is not quite right.

Historically the syntactic feature of annotations didn't have a standardized meaning, so the standard library couldn't use it internally and we couldn't document any APIs that would use it. Otherwise we'd be creating a "de facto" standard.

The situation changed with PEP 484. Since this was a very large feature, we have taken the stance that we won't be covering the standard library with type hints, at least not until typing graduates from provisional status and further discussion on python-dev (or maybe even a PEP about this).

However, at this point we never said we wouldn't allow for the standard library to implement features that allow the users of the library to utilize annotations. The typing module itself is an obvious example: it presents users with a feature that requires using the syntactic construct of annotations.
Data classes for Python 3.7 also utilize annotations to define fields. And in this pull request, singledispatch uses annotations for a similar purpose: to inform runtime type decisions.

And by the way, since the entire point of PEP 557 was to bring an "attrs" implementation to the standard library in order for the standard library to be able to use it itself, I think with Python 3.7 effectively type annotations are going to start appearing in the standard library by means of data classes alone. At least with singledispatch I'm leaving the classic syntax alone so users with a visceral reaction to annotations can keep using it.

[bedevere-bot]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[ambv]

I have made the requested changes; please review again.

[bedevere-bot]

Thanks for making the requested changes!

@bitdancer: please review the changes made to this pull request.

[merwok]

Maybe add a glossary link for function annotations?

[merwok]

@ambv