Allow fancy self-types

[ilevkivskyi]

Fixes #3625
Fixes #5305
Fixes #5320
Fixes #5868
Fixes #7191
Fixes #7778
Fixes python/typing#680

So, lately I was noticing many issues that would be fixed by (partially) moving the check for self-type from definition site to call site.

This morning I found that we actually have such function check_self_arg() that is applied at call site, but it is almost not used. After more reading of the code I found that all the patterns for self-types that I wanted to support should either already work, or work with minimal modifications. Finally, I discovered that the root cause of many of the problems is the fact that bind_self() uses wrong direction for type inference! All these years it expected actual argument type to be supertype of the formal one.

After fixing this bug, it turned out it was easy to support following patterns for explicit self-types:

• Structured match on generic self-types
• Restricted methods in generic classes (methods that one is allowed to call only for some values or type arguments)
• Methods overloaded on self-type
• (Important case of the above) overloaded __init__ for generic classes
• Mixin classes (using protocols)
• Private class-level decorators (a bit hacky)
• Precise types for alternative constructors (mostly already worked)

This PR cuts few corners, but it is ready for review (I left some TODOs). Note I also add some docs, I am not sure this is really needed, but probably good to have.

[ilevkivskyi]

Few extra comments:

• I just updated the PR description with a list of issues this will close, I didn't do a thorough search however.
• Potentially this PR can be split in few parts, if needed (I would prefer to keep it single however).
• I am going to push couple more tests that mimic tricky examples in one issue (just to be sure they are fixed). If you think it is too much I can remove them.

[ilevkivskyi]

(Also note that we can count #3625 as fixed only if remove all checks at the definition site).

[Michael0x2a]

Maybe you'll want to get a second opinion from Jukka/Sully, but FWIW these changes all look fine to me: the overall approach seems sound and nicely minimal, and my comments were mostly nits and smaller suggestions.

[ilevkivskyi]

(Also note that we can count #3625 as fixed only if remove all checks at the definition site).

I changed my mind about this. With a tiny extra fix this issue will be now also closed by this PR.

[msullivan]

This is a really exciting improvement. I love when so much falls out of one fix.

[msullivan]

Is it worth documenting the use in __init__?

[ilevkivskyi]

I noticed it is mostly useful for typeshed stubs, but didn't find this patter in user code, I will add a short sentence at the end, where I discuss overloads.

[msullivan]

__new__ can use explicit returns in subclasses, but kind of as a technicality, since it only works using bound type vars, I think.

[ilevkivskyi]

Yes, I will make the comment more clear.

[msullivan]

This doesn't seem to check that there is an instance upper bound? Should there be?

Also my inclination would be to throw parens around the and clause.

[ilevkivskyi]

This doesn't seem to check that there is an instance upper bound? Should there be?

I would say it is safe to keep it as is. We can restrict this later if we will find problems.

Also my inclination would be to throw parens around the and clause.

OK.