Merge pull request #221 from jaraco/feature/inline-types

Inline some types

docs/conf.py

@@ -33,6 +33,21 @@
 # Be strict about any broken references
 nitpicky = True
 
+
+nitpick_ignore = [
+    ('py:class', '_io.BufferedRandom'),
+    ('py:class', '_io.BufferedReader'),
+    ('py:class', '_io.BufferedWriter'),
+    ('py:class', '_io.FileIO'),
+    ('py:class', '_io.TextIOWrapper'),
+    ('py:class', 'Literal[-1, 1]'),
+    ('py:class', 'OpenBinaryMode'),
+    ('py:class', 'OpenBinaryModeReading'),
+    ('py:class', 'OpenBinaryModeUpdating'),
+    ('py:class', 'OpenBinaryModeWriting'),
+    ('py:class', 'OpenTextMode'),
+]
+
 # Include Python intersphinx mapping to prevent failures
 # jaraco/skeleton#51
 extensions += ['sphinx.ext.intersphinx']

newsfragments/215.feature.rst

@@ -0,0 +1 @@
+Inlined some types.

path/__init__.py

@@ -22,6 +22,9 @@
     foo_txt = Path("bar") / "foo.txt"
 """
 
+from __future__ import annotations
+
+import builtins
 import sys
 import warnings
 import os
@@ -49,6 +52,35 @@
 with contextlib.suppress(ImportError):
     import grp
 
+from io import (
+    BufferedRandom,
+    BufferedReader,
+    BufferedWriter,
+    FileIO,
+    TextIOWrapper,
+)
+from typing import (
+    Any,
+    BinaryIO,
+    Callable,
+    IO,
+    Iterator,
+    Optional,
+    overload,
+)
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from _typeshed import (
+        OpenBinaryMode,
+        OpenBinaryModeUpdating,
+        OpenBinaryModeReading,
+        OpenBinaryModeWriting,
+        OpenTextMode,
+    )
+    from typing_extensions import Literal
+
 from . import matchers
 from . import masks
 from . import classes
@@ -652,6 +684,90 @@ def iglob(self, pattern):
     #
     # --- Reading or writing an entire file at once.
 
+    @overload
+    def open(
+        self,
+        mode: OpenTextMode = ...,
+        buffering: int = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Optional[Callable[[str, int], int]] = ...,
+    ) -> TextIOWrapper: ...
+
+    @overload
+    def open(
+        self,
+        mode: OpenBinaryMode,
+        buffering: Literal[0],
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> FileIO: ...
+
+    @overload
+    def open(
+        self,
+        mode: OpenBinaryModeUpdating,
+        buffering: Literal[-1, 1] = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> BufferedRandom: ...
+
+    @overload
+    def open(
+        self,
+        mode: OpenBinaryModeReading,
+        buffering: Literal[-1, 1] = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> BufferedReader: ...
+
+    @overload
+    def open(
+        self,
+        mode: OpenBinaryModeWriting,
+        buffering: Literal[-1, 1] = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> BufferedWriter: ...
+
+    @overload
+    def open(
+        self,
+        mode: OpenBinaryMode,
+        buffering: int,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> BinaryIO: ...
+
+    @overload
+    def open(
+        self,
+        mode: str,
+        buffering: int = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Callable[[str, int], int] = ...,
+    ) -> IO[Any]: ...
+
     def open(self, *args, **kwargs):
         """Open this file and return a corresponding file object.
 
@@ -665,6 +781,45 @@ def bytes(self):
         with self.open('rb') as f:
             return f.read()
 
+    @overload
+    def chunks(
+        self,
+        size: int,
+        mode: OpenTextMode = ...,
+        buffering: int = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Optional[Callable[[str, int], int]] = ...,
+    ) -> Iterator[str]: ...
+
+    @overload
+    def chunks(
+        self,
+        size: int,
+        mode: OpenBinaryMode,
+        buffering: int = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Optional[Callable[[str, int], int]] = ...,
+    ) -> Iterator[builtins.bytes]: ...
+
+    @overload
+    def chunks(
+        self,
+        size: int,
+        mode: str,
+        buffering: int = ...,
+        encoding: Optional[str] = ...,
+        errors: Optional[str] = ...,
+        newline: Optional[str] = ...,
+        closefd: bool = ...,
+        opener: Optional[Callable[[str, int], int]] = ...,
+    ) -> Iterator[Union[str, builtins.bytes]]: ...
+
     def chunks(self, size, *args, **kwargs):
         """Returns a generator yielding chunks of the file, so it can
          be read piece by piece with a simple for loop.
@@ -718,6 +873,26 @@ def text(self, encoding=None, errors='strict'):
         )
         return U_NEWLINE.sub('\n', self.read_text(encoding, errors))
 
+    @overload
+    def write_text(
+        self,
+        text: str,
+        encoding: Optional[str] = ...,
+        errors: str = ...,
+        linesep: Optional[str] = ...,
+        append: bool = ...,
+    ) -> None: ...
+
+    @overload
+    def write_text(
+        self,
+        text: builtins.bytes,
+        encoding: None = ...,
+        errors: str = ...,
+        linesep: Optional[str] = ...,
+        append: bool = ...,
+    ) -> None: ...
+
     def write_text(
         self, text, encoding=None, errors='strict', linesep=os.linesep, append=False
     ):