Add typehints to pathlib.types

Author: ap--

Lib/pathlib/types.py

@@ -14,7 +14,15 @@
 from glob import _PathGlobber
 from pathlib._os import magic_open, ensure_distinct_paths, ensure_different_files, copyfileobj
 from pathlib import PurePath, Path
-from typing import Optional, Protocol, runtime_checkable
+from typing import (
+    Any, BinaryIO, Callable, Generator, Optional, Protocol, Sequence, TypeVar, Union,
+    runtime_checkable,
+)
+
+
+_JP = TypeVar("_JP", bound="_JoinablePath")
+_RP = TypeVar("_RP", bound="_ReadablePath")
+_WP = TypeVar("_WP", bound="_WritablePath")
 
 
 def _explode_path(path):
@@ -72,38 +80,38 @@ class _JoinablePath(ABC):
 
     @property
     @abstractmethod
-    def parser(self):
+    def parser(self) -> _PathParser:
         """Implementation of pathlib._types.Parser used for low-level path
         parsing and manipulation.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def with_segments(self, *pathsegments):
+    def with_segments(self: _JP, *pathsegments: Union[_JP, str]) -> _JP:
         """Construct a new path object from any number of path-like objects.
         Subclasses may override this method to customize how new path objects
         are created from methods like `iterdir()`.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def __str__(self):
+    def __str__(self) -> str:
         """Return the string representation of the path, suitable for
         passing to system calls."""
         raise NotImplementedError
 
     @property
-    def anchor(self):
+    def anchor(self) -> str:
         """The concatenation of the drive and root, or ''."""
         return _explode_path(self)[0]
 
     @property
-    def name(self):
+    def name(self) -> str:
         """The final path component, if any."""
         return self.parser.split(str(self))[1]
 
     @property
-    def suffix(self):
+    def suffix(self) -> str:
         """
         The final component's last suffix, if any.
 
@@ -112,7 +120,7 @@ def suffix(self):
         return self.parser.splitext(self.name)[1]
 
     @property
-    def suffixes(self):
+    def suffixes(self) -> Sequence[str]:
         """
         A list of the final component's suffixes, if any.
 
@@ -127,11 +135,11 @@ def suffixes(self):
         return suffixes[::-1]
 
     @property
-    def stem(self):
+    def stem(self) -> str:
         """The final path component, minus its last suffix."""
         return self.parser.splitext(self.name)[0]
 
-    def with_name(self, name):
+    def with_name(self: _JP, name: str) -> _JP:
         """Return a new path with the file name changed."""
         split = self.parser.split
         if split(name)[0]:
@@ -140,7 +148,7 @@ def with_name(self, name):
         path = path.removesuffix(split(path)[1]) + name
         return self.with_segments(path)
 
-    def with_stem(self, stem):
+    def with_stem(self: _JP, stem: str) -> _JP:
         """Return a new path with the stem changed."""
         suffix = self.suffix
         if not suffix:
@@ -151,7 +159,7 @@ def with_stem(self, stem):
         else:
             return self.with_name(stem + suffix)
 
-    def with_suffix(self, suffix):
+    def with_suffix(self: _JP, suffix: str) -> _JP:
         """Return a new path with the file suffix changed.  If the path
         has no suffix, add given suffix.  If the given suffix is an empty
         string, remove the suffix from the path.
@@ -166,36 +174,36 @@ def with_suffix(self, suffix):
             return self.with_name(stem + suffix)
 
     @property
-    def parts(self):
+    def parts(self) -> Sequence[str]:
         """An object providing sequence-like access to the
         components in the filesystem path."""
         anchor, parts = _explode_path(self)
         if anchor:
             parts.append(anchor)
         return tuple(reversed(parts))
 
-    def joinpath(self, *pathsegments):
+    def joinpath(self: _JP, *pathsegments: Union[_JP, str]) -> _JP:
         """Combine this path with one or several arguments, and return a
         new path representing either a subpath (if all arguments are relative
         paths) or a totally different path (if one of the arguments is
         anchored).
         """
         return self.with_segments(str(self), *pathsegments)
 
-    def __truediv__(self, key):
+    def __truediv__(self: _JP, key: Union[_JP, str]) -> _JP:
         try:
             return self.with_segments(str(self), key)
         except TypeError:
             return NotImplemented
 
-    def __rtruediv__(self, key):
+    def __rtruediv__(self: _JP, key: Union[_JP, str]) -> _JP:
         try:
             return self.with_segments(key, str(self))
         except TypeError:
             return NotImplemented
 
     @property
-    def parent(self):
+    def parent(self: _JP) -> _JP:
         """The logical parent of the path."""
         path = str(self)
         parent = self.parser.split(path)[0]
@@ -204,7 +212,7 @@ def parent(self):
         return self
 
     @property
-    def parents(self):
+    def parents(self: _JP) -> Sequence[_JP]:
         """A sequence of this path's logical parents."""
         split = self.parser.split
         path = str(self)
@@ -216,7 +224,7 @@ def parents(self):
             parent = split(path)[0]
         return tuple(parents)
 
-    def full_match(self, pattern):
+    def full_match(self: _JP, pattern: Union[_JP, str]) -> bool:
         """
         Return True if this path matches the given glob-style pattern. The
         pattern is matched against the entire path.
@@ -240,45 +248,50 @@ class _ReadablePath(_JoinablePath):
 
     @property
     @abstractmethod
-    def info(self):
+    def info(self) -> PathInfo:
         """
         A PathInfo object that exposes the file type and other file attributes
         of this path.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def __open_rb__(self, buffering=-1):
+    def __open_rb__(self, buffering: int = -1) -> BinaryIO:
         """
         Open the file pointed to by this path for reading in binary mode and
         return a file object, like open(mode='rb').
         """
         raise NotImplementedError
 
-    def read_bytes(self):
+    def read_bytes(self) -> bytes:
         """
         Open the file in bytes mode, read it, and close the file.
         """
         with magic_open(self, mode='rb', buffering=0) as f:
             return f.read()
 
-    def read_text(self, encoding=None, errors=None, newline=None):
+    def read_text(
+        self,
+        encoding: Optional[str] = None,
+        errors: Optional[str] = None,
+        newline: Optional[str] = None,
+    ) -> str:
         """
         Open the file in text mode, read it, and close the file.
         """
         with magic_open(self, mode='r', encoding=encoding, errors=errors, newline=newline) as f:
             return f.read()
 
     @abstractmethod
-    def iterdir(self):
+    def iterdir(self: _RP) -> Generator[_RP, None, None]:
         """Yield path objects of the directory contents.
 
         The children are yielded in arbitrary order, and the
         special entries '.' and '..' are not included.
         """
         raise NotImplementedError
 
-    def glob(self, pattern, *, recurse_symlinks=True):
+    def glob(self: _RP, pattern: Union[_RP, str], *, recurse_symlinks: bool = True) -> Generator[_RP, None, None]:
         """Iterate over this subtree and yield all existing files (of any
         kind, including directories) matching the given relative pattern.
         """
@@ -294,7 +307,12 @@ def glob(self, pattern, *, recurse_symlinks=True):
         select = globber.selector(parts)
         return select(self.joinpath(''))
 
-    def walk(self, top_down=True, on_error=None, follow_symlinks=False):
+    def walk(
+        self: _RP,
+        top_down: bool = True,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        follow_symlinks: bool = False,
+    ) -> Generator[tuple[_RP, list[str], list[str]], None, None]:
         """Walk the directory tree from this directory, similar to os.walk()."""
         paths = [self]
         while paths:
@@ -326,13 +344,13 @@ def walk(self, top_down=True, on_error=None, follow_symlinks=False):
                 paths += [path.joinpath(d) for d in reversed(dirnames)]
 
     @abstractmethod
-    def readlink(self):
+    def readlink(self: _RP) -> _RP:
         """
         Return the path to which the symbolic link points.
         """
         raise NotImplementedError
 
-    def copy(self, target, **kwargs):
+    def copy(self, target: _WP, **kwargs: Any) -> _WP:
         """
         Recursively copy this file or directory tree to the given destination.
         """
@@ -346,7 +364,7 @@ def copy(self, target, **kwargs):
         copy_to_target(self, **kwargs)
         return target.joinpath()  # Empty join to ensure fresh metadata.
 
-    def copy_into(self, target_dir, **kwargs):
+    def copy_into(self, target_dir: _WP, **kwargs: Any) -> _WP:
         """
         Copy this file or directory tree into the given existing directory.
         """
@@ -370,29 +388,29 @@ class _WritablePath(_JoinablePath):
     __slots__ = ()
 
     @abstractmethod
-    def symlink_to(self, target, target_is_directory=False):
+    def symlink_to(self: _WP, target: _WP, target_is_directory: bool = False) -> None:
         """
         Make this path a symlink pointing to the target path.
         Note the order of arguments (link, target) is the reverse of os.symlink.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def mkdir(self):
+    def mkdir(self) -> None:
         """
         Create a new directory at this given path.
         """
         raise NotImplementedError
 
     @abstractmethod
-    def __open_wb__(self, buffering=-1):
+    def __open_wb__(self, buffering: int = -1) -> BinaryIO:
         """
         Open the file pointed to by this path for writing in binary mode and
         return a file object, like open(mode='wb').
         """
         raise NotImplementedError
 
-    def write_bytes(self, data):
+    def write_bytes(self, data: bytes) -> int:
         """
         Open the file in bytes mode, write to it, and close the file.
         """
@@ -401,7 +419,13 @@ def write_bytes(self, data):
         with magic_open(self, mode='wb') as f:
             return f.write(view)
 
-    def write_text(self, data, encoding=None, errors=None, newline=None):
+    def write_text(
+        self,
+        data: str,
+        encoding: Optional[str] = None,
+        errors: Optional[str] = None,
+        newline: Optional[str] = None,
+    ) -> int:
         """
         Open the file in text mode, write to it, and close the file.
         """
@@ -411,7 +435,7 @@ def write_text(self, data, encoding=None, errors=None, newline=None):
         with magic_open(self, mode='w', encoding=encoding, errors=errors, newline=newline) as f:
             return f.write(data)
 
-    def _copy_from(self, source, follow_symlinks=True):
+    def _copy_from(self, source: _ReadablePath, follow_symlinks: bool = True) -> None:
         """
         Recursively copy the given path to this path.
         """