Does that mean that there is no way to specify that two non union types must/will be the same? In the above example, I would have expected that the first filter function is guaranteed to return a file object if called with a file object, but the second definition could return a sequence instead.

That would be indeed unexpected and should be documented. It also seems inconsistent:

X = TypeVar("X")
def copy(original: X) -> X

Y  = TypeVar("Y", Iterable[X])
def copy_it(original: Y) -> Y

Both declarations look identical, but while the first one will guarantee that isinstance(original, copy) is true, the second one doesn't; copy_it((1,2,3,4,5)) could return a list, for example.

Yes, generic types and type variables need to be explained better. I think you did get the distinction between constrained and unconstrained type variables right (though your words are a bit confusing).

The best example of constrained type variables is AnyStr. See the explanation of this in http://mypy.readthedocs.org/en/latest/generics.html .

I would also like to point out that requiring a function to return an object of the exact same type as an argument is usually unreasonable, since being able to extract the type (e.g. x.__class__) is not sufficient to be able to create an instance. (How would you know the constructor signature?) There is some discussion of this in python/mypy#539 (search for "Eugene").

Usually the only case where returning an object of the exactly same type as an argument is reasonable when the returned object is one of the arguments (or contained within an argument). So this is okay because we just pass through an object:

T = TypeVar('T')
def first(x: Sequence[T]) -> T: return x[0]

See also #1.

Rewrote the example.