All right. I don't think I have the capacity currently to merge the os/__init__.pyi stubs, but I'd be interested in the second part, as I ran into that when passing a pathlib.Path object to os.path.relpath.

To formulate that into a question: Should I replace signatures in the form def x(a: AnyStr) -> AnyStr: ... with def x(a: _PathType) -> AnyStr: ..., which loses the generic property of returning the same string type as passed but gains support for PathLike objects? That is, until python/mypy#3644 is fixed.

Maybe you could do something like what was done for readlink()?

if sys.version_info >= (3, 6):
    def readlink(path: Union[AnyStr, PathLike[AnyStr]], *, dir_fd: Optional[int] = ...) -> AnyStr: ...

Isn't that exactly what triggers python/mypy#3644? Or would that only apply to _PathType[AnyStr]? In that case, I could as well just change _PathType = Union[AnyStr, _PathLike[AnyStr]]. Or, if that is undesireable, add a different alias for that.

That's an interesting option. I'm too tired tonight to consider it, sorry. Maybe @JukkaL has an opinion. At the very least you should check everything that currently uses _PathType and see if/whether it would (or should!) change.

One option is to use an overloaded function, which mypy seems to handle already:

@overload
def readlink(path: AnyStr, *, dir_fd: Optional[int] = 0) -> AnyStr: ...
@overload
def readlink(path: PathLike[AnyStr], *, dir_fd: Optional[int] = 0) -> AnyStr: ...

Or we could prioritize fixing python/mypy#3644 -- it doesn't feel to me like it would be a tricky one, but I could be mistaken.

For starters, I tried replacing all current usages of AnyStr in parameters with _GenPathType (short for generic) and the following:

if sys.version_info >= (3, 6):
    from builtins import _PathLike
    _PathType = Union[bytes, Text, _PathLike]
    _GenPathType = Union[AnyStr, _PathLike[AnyStr]]
else:
    _PathType = Union[bytes, Text]
    _GenPathType = AnyStr

However, running mypy_test.py, all Python 3 versions <3.6 complain about

stdlib/3/os/path.pyi:20: error: Type variable "typing.AnyStr" is invalid as target for type alias
stdlib/3/os/path.pyi:35: error: Invalid type "os.path._GenPathType"
…

Looks like you can't have an alias for a type variable (like AnyStr).

Another option to look into might be to define _PathLike and _PathType unconditionally, and only do the export of _PathType as PathType conditionally.

Do the export where?

The parts about PathType are covered in the more focused #1997, and the question about merging has been answered, so closing this issue.