add __fspath__ support to os.path

[JelleZijlstra]

Fixes #1997, #2068.

This is tricky because we need to get the return values right (see #1960 for
prior attempts) and we often run into python/mypy#3644. I found that I
could express most signatures correctly using a series of overloads.

A few other changes in here:

• Added splitunc, which according to https://docs.python.org/3/library/os.path.html
  should exist in both Unix and Windows.
• Made the second argument to os.path.curdir Optional to match the implementation.
• Fixed os.path.split, whose previous Path-aware signature triggered TypeVar in generic union member gets restricted to first constraint mypy#3644.

I couldn't come up with a correct signature for os.path.commonpath, so I am falling back to using Any as its return type.

I used the following test program to make sure mypy accepted the signatures used here:

import os
from os.path import abspath, commonpath, relpath, split, join
from typing import Generic, AnyStr, Any

class PL(os.PathLike[AnyStr]):
    def __init__(self, path: AnyStr) -> None:
        self.path: AnyStr = path
    def __fspath__(self) -> AnyStr:
        return self.path

bad_path: PL[Any] = PL('')

reveal_type(abspath('hello'))  # str
reveal_type(abspath(b'hello'))  # bytes
reveal_type(abspath(PL('hello')))  # str
reveal_type(abspath(PL(b'hello')))  # bytes

reveal_type(commonpath(['hello', PL('hello')]))  # Any (couldn't get it work correctly)
reveal_type(commonpath([b'hello', PL(b'hello')]))  # Any

reveal_type(relpath('hello'))  # str
reveal_type(relpath('hello', PL('hello')))  # str
reveal_type(relpath(b'hello', b'hello'))  # bytes
reveal_type(relpath(PL('hello')))  # str
reveal_type(relpath(PL(b'hello'), b'hello'))  # bytes
reveal_type(relpath(bad_path, 'hello'))  # str
reveal_type(relpath(bad_path, bad_path))  # Any

reveal_type(split('hello'))  # (str, str)
reveal_type(split(b'hello'))  # (bytes, bytes)
reveal_type(split(PL('hello')))  # (str, str)
reveal_type(split(PL(b'hello')))  # (bytes, bytes)

reveal_type(join('hello', PL('hello')))  # str
reveal_type(join(PL('hello'), 'hello'))  # str
reveal_type(join(b'hello', PL(b'hello')))  # bytes
reveal_type(join(b'hello', PL('hello')))  # error

I made the same changes to the Python 2 stub in order to keep the two consistent.

[FichteFoll]

relpath isn't guarded by a 3.6 version check and there is no AnyStr fallback.

Also, the bytes variant is missing Optional.

(Applies to the 2 version as well.)

[JelleZijlstra]

That is intentional. _StrPath is just Text below 3.6, so this implementation is correct there.

If start is None, the code uses os.curdir, which is Text, so the path also has to be Text. Although come to think of it, we may need something more complicated in Python 2, where you can mix bytes and Text paths.

[JelleZijlstra]

Actually, the current code already works in Python 2 (modulo a mypy bug where some overloads silently fall back to Any).

[gvanrossum]

LGTM, merge whenever you want to.

[JelleZijlstra]

Thanks for the review!