Clarify generic function documentation

[elias6]

This explains that a variable of a generic type must be able to be resolved to a non-generic type, hopefully preventing the confusion that made me (and possibly others) think #4590 is a bug.

@gvanrossum, I used some of the wording in your explanation almost verbatim. I'm guessing you don't mind.

[gvanrossum]

There's no need to repeat the two "good" examples -- this example should be only concerned with what doesn't work.

[gvanrossum]

Please break the long line. Also, maybe drop the leading "Note that" -- the previous section also starts like that and it's a bit repetitive.

[gvanrossum]

Hm, sadly I just realized this is not quite correct, since this is possible:

T = TypeVar('T')
S = TypeVar('S')

def repeat(n: int) -> Callable[[Callable[[T], T]], Callable[[T], T]]:
    def outer(func: Callable[[S], S]) -> Callable[[S], S]:
        def inner(x: S) -> S:
            for i in range(n):
                x = func(x)
            return x
        return inner
    return outer

fff = repeat(3)
reveal_type(fff)  # 'def [T] (def (T`-1) -> T`-1) -> def (T`-1) -> T`-1'

But I don't want to include such an example here -- I just wish to find a way to write it that doesn't exclude it.

Also this much simpler example should be invalid but isn't:

def foo() -> T:
    pass

a = foo()

So I'm not sure what to do. Maybe @ilevkivskyi has an idea?

[kamahen]

def foo() -> T: pass

seems to be an unidiomatic way of writing

def foo() -> Any: pass

[gvanrossum]

They don't mean the same thing in mypy. The former returns a type containing <nothing> (meaning it has no values).

[elias6]

@gvanrossum it seems like you don't need your strange nested example to contradict the wording in your explanation. I ran reveal_type on the first example in the "Generic functions" section of the documentation, and it told me Revealed type is 'def [T] (seq: typing.Sequence[T`-1]) -> T`-1'. I don't know exactly what that means, but isn't that an example of a type with a type variable, even though that type variable is not bound in a containing generic class or function?

I kind of have an idea of where and how type variables can and can't be used, based on the existing documentation and my own tinkering. But I can't imagine how to explain it precisely and rigorously, in a way that most mypy users will be able to understand. I think someone will have to help me with this.

[gvanrossum]

Yeah, I went overboard with the complicated example. You'll note that all the examples where a type variable legitimately appears are types that are (or contain) generic functions. So maybe we should use that?

[gvanrossum]

I propose to drop the example and just keep the sentence explaining the constraint. I'll just edit this myself so we can finish this up.

[gvanrossum]

And, belatedly, thanks!