Replaced overload with AnyStr or Union type in os/path module

[spkersten]

Resolves #436

[spkersten]

I wasn't sure what to do with these. Currently, everything is either bytes or str; replacing with Union would make combinations possible as well.

[yczhu]

I think AnyStr can be used here?

[JukkaL]

Yeah, union types can't always be used here. AnyStr is the way to go. For example, consider abspath:

@overload
def abspath(path: str) -> str: pass
@overload
def abspath(path: bytes) -> bytes: pass

This can be written equivalent like this:

def abspath(path: AnyStr) -> AnyStr: pass

Note that this also gets the return type right. AnyStr can be substituted with str and bytes, but all instances of AnyStr within a signature are replaced together so combinations such as str -> bytes are not possible. When using union types, you can't encode the fact that the return type depends on the argument type(s), since each union type is independent of every other union type.

Sorry that this is not properly documented yet. I need to update the documentation to include all the new cool features.

@spkersten Did the the above explanation make sense?

[spkersten]

Ok, it's clear what needs to be done.

For my understanding: How does AnyStr allow both str -> str and bytes -> bytes, but not combinations?

[JukkaL]

@spkersten AnyStr is not a union type, it's a kind of type variable. abspath is generic function. Consider this generic function:

from typing import typevar

T = typevar('T')

def id(x: T) -> T:
    return x 

The function is generic since there is a reference to a (free) type variable in the signature. The function is valid for an arbitrary type T. This is similar to this Java method:

static <T> T id(T x) {
    return x;
}

Now, let's get back to AnyStr. It is defined like this:

AnyStr = typevar('AnyStr', values=(str, values))

This means that AnyStr is a type variable, conceptually similar to T above, but the only valid values are str and bytes, unlike T, which can take an arbitrary type as the value. This is related to bounded quantification, in case you are familiar with it, but this is slightly different, as subtypes of str or bytes are not valid (if a subtype of str would be inferred as the value, it would be promoted to str).

[spkersten]

Clear explanation. Thanks.

[spkersten]

It looks to me like the Travis is failing now due to #360. I'll see if I can fix that first.

[JukkaL]

Now that #360 is fixed, this PR now seems good. Thanks for refactoring this!