Improve correctness of pathlib stubs (#483)

I went through each method in the source and verified the inputs it accepts and outputs it gives. I also redefined a few methods on the `Path` class so that MyPy knows they return `Path` instead of `PurePath`. This is really just a temporary workaround until https://github.com/python/mypy/issues/1212 is fixed, but greatly improves the process of working with the `pathlib` module and is therefore likely worth the duplication.

stdlib/3.5/pathlib.pyi

@@ -1,12 +1,12 @@
-# Stubs for pathlib (Python 3.4)
+# Stubs for pathlib (Python 3.5)
 
 from typing import Any, Generator, IO, Optional, Sequence, Tuple, Union
 import os
 
 class PurePath:
     parts = ...  # type: Tuple[str, ...]
-    drive = ... # type: str
-    root = ... # type: str
+    drive = ...  # type: str
+    root = ...  # type: str
     anchor = ...  # type: str
     parents = ...  # type: Sequence[PurePath]
     parent = ...  # type: PurePath
@@ -14,20 +14,20 @@ class PurePath:
     suffix = ...  # type: str
     suffixes = ...  # type: List[str]
     stem = ...  # type: str
-    def __init__(self, *pathsegments: str) -> None: ...
-    def __hash__(self) -> int: ...
+    def __new__(cls, *args: Union[str, PurePath]) -> PurePath: ...
     def __lt__(self, other: PurePath) -> bool: ...
     def __le__(self, other: PurePath) -> bool: ...
     def __gt__(self, other: PurePath) -> bool: ...
     def __ge__(self, other: PurePath) -> bool: ...
     def __truediv__(self, key: Union[str, PurePath]) -> PurePath: ...
+    def __rtruediv__(self, key: Union[str, PurePath]) -> PurePath: ...
     def __bytes__(self) -> bytes: ...
     def as_posix(self) -> str: ...
     def as_uri(self) -> str: ...
     def is_absolute(self) -> bool: ...
     def is_reserved(self) -> bool: ...
     def match(self, path_pattern: str) -> bool: ...
-    def relative_to(self, *other: str) -> PurePath: ...
+    def relative_to(self, *other: Union[str, PurePath]) -> PurePath: ...
     def with_name(self, name: str) -> PurePath: ...
     def with_suffix(self, suffix: str) -> PurePath: ...
     def joinpath(self, *other: Union[str, PurePath]) -> PurePath: ...
@@ -40,6 +40,8 @@ class Path(PurePath):
     def cwd(cls) -> Path: ...
     @classmethod
     def home(cls) -> Path: ...
+    def __new__(cls, *args: Union[str, PurePath], **kwargs: Any) -> Path: ...
+    def absolute(self) -> Path: ...
     def stat(self) -> os.stat_result: ...
     def chmod(self, mode: int) -> None: ...
     def exists(self) -> bool: ...
@@ -64,14 +66,14 @@ class Path(PurePath):
     def owner(self) -> str: ...
     def read_bytes(self) -> bytes: ...
     def read_text(self, encoding: Optional[str] = ...,
-                  errors: Optional[str] = ...) -> bytes: ...
-    def rename(self, target: Union[str, Path]) -> None: ...
-    def replace(self, target: Union[str, Path]) -> None: ...
+                  errors: Optional[str] = ...) -> str: ...
+    def rename(self, target: Union[str, PurePath]) -> None: ...
+    def replace(self, target: Union[str, PurePath]) -> None: ...
     def resolve(self) -> Path: ...
     def rglob(self, pattern: str) -> Generator[Path, None, None]: ...
     def rmdir(self) -> None: ...
-    def samefile(self, other_path: Union[str, Path]) -> bool: ...
-    def symlink_to(self, target: Union[str, Path],
+    def samefile(self, other_path: Union[str, bytes, int, Path]) -> bool: ...
+    def symlink_to(self, target: Union[str, PurePath],
                    target_is_directory: bool = ...) -> None: ...
     def touch(self, mode: int = ..., exist_ok: bool = ...) -> None: ...
     def unlink(self) -> None: ...
@@ -79,5 +81,17 @@ class Path(PurePath):
     def write_text(self, data: str, encoding: Optional[str] = ...,
                    errors: Optional[str] = ...) -> int: ...
 
+    # The following methods are re-stubbed here even though they only actually exist in the base
+    # class so that they return Path when called on a Path, rather than returning PurePath.
+    parents = ...  # type: Sequence[Path]
+    parent = ...  # type: Path
+    def __truediv__(self, key: Union[str, PurePath]) -> Path: ...
+    def __rtruediv__(self, key: Union[str, PurePath]) -> Path: ...
+    def relative_to(self, *other: Union[str, PurePath]) -> Path: ...
+    def with_name(self, name: str) -> Path: ...
+    def with_suffix(self, suffix: str) -> Path: ...
+    def joinpath(self, *args: Union[str, PurePath]) -> Path: ...
+
+
 class PosixPath(Path, PurePosixPath): ...
 class WindowsPath(Path, PureWindowsPath): ...