Add warnings.catch_warning type hints with Literal.

[mslapek]

Fixes#3463

[srittau]

Thanks!

[bluetech]

This is a nice change, thanks.

However, I wonder if there is a better way to fix the issue. This PR changes catch_warning from a class to a function which returns typing.ContextManager. This has two downsides:

1. It breaks the usual rule of "accept abstract, return concrete". Returning an abstract interface is strictly weaker than returning a concrete type which implements this interface. It does make sense if the implementation wants to keep its options open, but that's not the case here.

2. The docs document catch_warnings as a class. Changing it to a function means (I think) that the type checker will no longer allow to subclass it, or check isinstance of it, return it from wrapper functions, etc.

Maybe @srittau knows how to keep it a class? Maybe it's possible to @overload__init__ and inject a generic param to self in some way? Dunno.

[srittau]

I agree that keeping it as a class would be preferable. From what I understand overloaded init method that allow to narrow the type of a typevar is something that is currently being worked on in mypy. So we can probably improve these hints soon.

[blueyed]

As pointed out already this fails now:

importwarningsclassWarningsRecorder(warnings.catch_warnings):
pass

t.py:4: error: Function "warnings.catch_warnings" is not valid as a type
t.py:4: note: Perhaps you need "Callable[...]" or a callback protocol?
t.py:4: error: Invalid base class "warnings.catch_warnings"
Found 2 errors in 1 file (checked 1 source file)

Are there plans to fix / allow this still?

[JelleZijlstra]

It looks like we should revert to an implementation that uses a class and overloads __new__. Contributions would be welcome.

[mslapek]

I've performed modification in #3499 to "eat the cake and have it too".

@JelleZijlstra Thanks for tip with __new__ overloading.