Add several Python 3.8 annotations (#3347)

Author: srittau

stdlib/2and3/ctypes/__init__.pyi

@@ -24,8 +24,15 @@ class CDLL(object):
     _name: str = ...
     _handle: int = ...
     _FuncPtr: Type[_FuncPointer] = ...
-    def __init__(self, name: str, mode: int = ..., handle: Optional[int] = ...,
-                 use_errno: bool = ..., use_last_error: bool = ...) -> None: ...
+    def __init__(
+        self,
+        name: str,
+        mode: int = ...,
+        handle: Optional[int] = ...,
+        use_errno: bool = ...,
+        use_last_error: bool = ...,
+        winmode: Optional[int] = ...,
+    ) -> None: ...
     def __getattr__(self, name: str) -> _FuncPointer: ...
     def __getitem__(self, name: str) -> _FuncPointer: ...
 if sys.platform == 'win32':

stdlib/2and3/datetime.pyi

@@ -37,14 +37,17 @@ class date:
     def __init__(self, year: int, month: int, day: int) -> None: ...
 
     @classmethod
-    def fromtimestamp(cls, t: float) -> date: ...
+    def fromtimestamp(cls: Type[_S], t: float) -> _S: ...
     @classmethod
-    def today(cls) -> date: ...
+    def today(cls: Type[_S]) -> _S: ...
     @classmethod
-    def fromordinal(cls, n: int) -> date: ...
+    def fromordinal(cls: Type[_S], n: int) -> _S: ...
     if sys.version_info >= (3, 7):
         @classmethod
-        def fromisoformat(cls, date_string: str) -> date: ...
+        def fromisoformat(cls: Type[_S], date_string: str) -> _S: ...
+    if sys.version_info >= (3, 8):
+        @classmethod
+        def fromisocalendar(cls: Type[_S], year: int, week: int, day: int) -> _S: ...
 
     @property
     def year(self) -> int: ...
@@ -114,7 +117,7 @@ class time:
     def isoformat(self) -> str: ...
     if sys.version_info >= (3, 7):
         @classmethod
-        def fromisoformat(cls, time_string: str) -> time: ...
+        def fromisoformat(cls: Type[_S], time_string: str) -> _S: ...
     def strftime(self, fmt: _Text) -> str: ...
     if sys.version_info >= (3,):
         def __format__(self, fmt: str) -> str: ...
@@ -222,13 +225,13 @@ class datetime(date):
         def fold(self) -> int: ...
 
     @classmethod
-    def fromtimestamp(cls, t: float, tz: Optional[_tzinfo] = ...) -> datetime: ...
+    def fromtimestamp(cls: Type[_S], t: float, tz: Optional[_tzinfo] = ...) -> _S: ...
     @classmethod
-    def utcfromtimestamp(cls, t: float) -> datetime: ...
+    def utcfromtimestamp(cls: Type[_S], t: float) -> _S: ...
     @classmethod
-    def today(cls) -> datetime: ...
+    def today(cls: Type[_S]) -> _S: ...
     @classmethod
-    def fromordinal(cls, n: int) -> datetime: ...
+    def fromordinal(cls: Type[_S], n: int) -> _S: ...
     if sys.version_info >= (3, 8):
         @classmethod
         def now(cls: Type[_S], tz: Optional[_tzinfo] = ...) -> _S: ...
@@ -240,7 +243,7 @@ class datetime(date):
         @classmethod
         def now(cls, tz: _tzinfo) -> datetime: ...
     @classmethod
-    def utcnow(cls) -> datetime: ...
+    def utcnow(cls: Type[_S]) -> _S: ...
     if sys.version_info >= (3, 6):
         @classmethod
         def combine(cls, date: _date, time: _time, tzinfo: Optional[_tzinfo] = ...) -> datetime: ...
@@ -249,7 +252,7 @@ class datetime(date):
         def combine(cls, date: _date, time: _time) -> datetime: ...
     if sys.version_info >= (3, 7):
         @classmethod
-        def fromisoformat(cls, date_string: str) -> datetime: ...
+        def fromisoformat(cls: Type[_S], date_string: str) -> _S: ...
     def strftime(self, fmt: _Text) -> str: ...
     if sys.version_info >= (3,):
         def __format__(self, fmt: str) -> str: ...

stdlib/2and3/math.pyi

@@ -1,7 +1,7 @@
 # Stubs for math
 # See: http://docs.python.org/2/library/math.html
 
-from typing import Tuple, Iterable, SupportsFloat, SupportsInt
+from typing import Tuple, Iterable, SupportsFloat, SupportsInt, overload
 
 import sys
 
@@ -28,6 +28,8 @@ def copysign(x: SupportsFloat, y: SupportsFloat) -> float: ...
 def cos(x: SupportsFloat) -> float: ...
 def cosh(x: SupportsFloat) -> float: ...
 def degrees(x: SupportsFloat) -> float: ...
+if sys.version_info >= (3, 8):
+    def dist(__p: Iterable[SupportsFloat], __q: Iterable[SupportsFloat]) -> float: ...
 def erf(x: SupportsFloat) -> float: ...
 def erfc(x: SupportsFloat) -> float: ...
 def exp(x: SupportsFloat) -> float: ...
@@ -44,13 +46,18 @@ def fsum(iterable: Iterable[float]) -> float: ...
 def gamma(x: SupportsFloat) -> float: ...
 if sys.version_info >= (3, 5):
     def gcd(a: int, b: int) -> int: ...
-def hypot(x: SupportsFloat, y: SupportsFloat) -> float: ...
+if sys.version_info >= (3, 8):
+    def hypot(*coordinates: SupportsFloat) -> float: ...
+else:
+    def hypot(__x: SupportsFloat, __y: SupportsFloat) -> float: ...
 if sys.version_info >= (3, 5):
     def isclose(a: SupportsFloat, b: SupportsFloat, rel_tol: SupportsFloat = ..., abs_tol: SupportsFloat = ...) -> bool: ...
 def isinf(x: SupportsFloat) -> bool: ...
 if sys.version_info >= (3,):
     def isfinite(x: SupportsFloat) -> bool: ...
 def isnan(x: SupportsFloat) -> bool: ...
+if sys.version_info >= (3, 8):
+    def isqrt(__n: int) -> int: ...
 def ldexp(x: SupportsFloat, i: int) -> float: ...
 def lgamma(x: SupportsFloat) -> float: ...
 def log(x: SupportsFloat, base: SupportsFloat = ...) -> float: ...
@@ -60,6 +67,11 @@ if sys.version_info >= (3, 3):
     def log2(x: SupportsFloat) -> float: ...
 def modf(x: SupportsFloat) -> Tuple[float, float]: ...
 def pow(x: SupportsFloat, y: SupportsFloat) -> float: ...
+if sys.version_info >= (3, 8):
+    @overload
+    def prod(__iterable: Iterable[int], *, start: int = ...) -> int: ...  # type: ignore
+    @overload
+    def prod(__iterable: Iterable[SupportsFloat], *, start: SupportsFloat = ...) -> float: ...
 def radians(x: SupportsFloat) -> float: ...
 if sys.version_info >= (3, 7):
     def remainder(x: SupportsFloat, y: SupportsFloat) -> float: ...

stdlib/2and3/mmap.pyi

@@ -51,6 +51,8 @@ class _mmap(Generic[AnyStr]):
 if sys.version_info >= (3,):
     class mmap(_mmap[bytes], ContextManager[mmap], Iterable[bytes], Sized):
         closed: bool
+        if sys.version_info >= (3, 8):
+            def madvise(self, option: int, start: int = ..., length: int = ...) -> None: ...
         def rfind(self, sub: bytes, start: int = ..., stop: int = ...) -> int: ...
         @overload
         def __getitem__(self, index: int) -> int: ...
@@ -71,3 +73,27 @@ else:
         def __getslice__(self, i: Optional[int], j: Optional[int]) -> bytes: ...
         def __delitem__(self, index: Union[int, slice]) -> None: ...
         def __setitem__(self, index: Union[int, slice], object: bytes) -> None: ...
+
+if sys.version_info >= (3, 8):
+    MADV_NORMAL: int
+    MADV_RANDOM: int
+    MADV_SEQUENTIAL: int
+    MADV_WILLNEED: int
+    MADV_DONTNEED: int
+    MADV_REMOVE: int
+    MADV_DONTFORK: int
+    MADV_DOFORK: int
+    MADV_HWPOISON: int
+    MADV_MERGEABLE: int
+    MADV_UNMERGEABLE: int
+    MADV_SOFT_OFFLINE: int
+    MADV_HUGEPAGE: int
+    MADV_NOHUGEPAGE: int
+    MADV_DONTDUMP: int
+    MADV_DODUMP: int
+    MADV_FREE: int
+    MADV_NOSYNC: int
+    MADV_AUTOSYNC: int
+    MADV_NOCORE: int
+    MADV_CORE: int
+    MADV_PROTECT: int

stdlib/3/_ast.pyi

@@ -3,6 +3,9 @@ import typing
 from typing import Any, Optional, ClassVar
 
 PyCF_ONLY_AST: int
+if sys.version_info >= (3, 8):
+    PyCF_TYPE_COMMENTS: int
+    PyCF_ALLOW_TOP_LEVEL_AWAIT: int
 
 _identifier = str
 

stdlib/3/ast.pyi

@@ -3,7 +3,7 @@ import sys
 # from _ast below when loaded in an unorthodox way by the Dropbox
 # internal Bazel integration.
 import typing as _typing
-from typing import overload, Any, Iterator, Optional, Union, TypeVar
+from typing import Any, Iterator, Optional, Tuple, TypeVar, Union, overload
 
 # The same unorthodox Bazel integration causes issues with sys, which
 # is imported in both modules. unfortunately we can't just rename sys,
@@ -16,27 +16,36 @@ if sys.version_info >= (3, 8):
 else:
     from typing_extensions import Literal
 
-class NodeVisitor():
+class NodeVisitor:
     def visit(self, node: AST) -> Any: ...
     def generic_visit(self, node: AST) -> Any: ...
 
 class NodeTransformer(NodeVisitor):
     def generic_visit(self, node: AST) -> Optional[AST]: ...
 
-_T = TypeVar('_T', bound=AST)
+_T = TypeVar("_T", bound=AST)
 
 if sys.version_info >= (3, 8):
     @overload
-    def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: Literal["exec"] = ...,
-              type_comments: bool = ..., feature_version: int = ...) -> Module: ...
-
+    def parse(
+        source: Union[str, bytes],
+        filename: Union[str, bytes] = ...,
+        mode: Literal["exec"] = ...,
+        type_comments: bool = ...,
+        feature_version: Union[None, int, Tuple[int, int]] = ...,
+    ) -> Module: ...
     @overload
-    def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: str = ...,
-              type_comments: bool = ..., feature_version: int = ...) -> AST: ...
+    def parse(
+        source: Union[str, bytes],
+        filename: Union[str, bytes] = ...,
+        mode: str = ...,
+        type_comments: bool = ...,
+        feature_version: Union[None, int, Tuple[int, int]] = ...,
+    ) -> AST: ...
+
 else:
     @overload
     def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: Literal["exec"] = ...) -> Module: ...
-
     @overload
     def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: str = ...) -> AST: ...
 
@@ -48,4 +57,5 @@ def increment_lineno(node: _T, n: int = ...) -> _T: ...
 def iter_child_nodes(node: AST) -> Iterator[AST]: ...
 def iter_fields(node: AST) -> Iterator[_typing.Tuple[str, Any]]: ...
 def literal_eval(node_or_string: Union[str, AST]) -> Any: ...
+def get_source_segment(source: str, node: AST, *, padded: bool = ...) -> Optional[str]: ...
 def walk(node: AST) -> Iterator[AST]: ...

stdlib/3/functools.pyi

@@ -1,9 +1,11 @@
+import sys
 from typing import Any, Callable, Generic, Dict, Iterable, Mapping, Optional, Sequence, Tuple, Type, TypeVar, NamedTuple, Union, overload
 
 _AnyCallable = Callable[..., Any]
 
 _T = TypeVar("_T")
 _S = TypeVar("_S")
+
 @overload
 def reduce(function: Callable[[_T, _S], _T],
            sequence: Iterable[_S], initial: _T) -> _T: ...
@@ -25,10 +27,13 @@ class _lru_cache_wrapper(Generic[_T]):
     def cache_info(self) -> _CacheInfo: ...
     def cache_clear(self) -> None: ...
 
-class lru_cache():
-    def __init__(self, maxsize: Optional[int] = ..., typed: bool = ...) -> None: ...
-    def __call__(self, f: Callable[..., _T]) -> _lru_cache_wrapper[_T]: ...
-
+if sys.version_info >= (3, 8):
+    @overload
+    def lru_cache(maxsize: Optional[int] = ..., typed: bool = ...) -> Callable[[Callable[..., _T]], _lru_cache_wrapper[_T]]: ...
+    @overload
+    def lru_cache(maxsize: Callable[..., _T], typed: bool = ...) -> _lru_cache_wrapper[_T]: ...
+else:
+    def lru_cache(maxsize: Optional[int] = ..., typed: bool = ...) -> Callable[[Callable[..., _T]], _lru_cache_wrapper[_T]]: ...
 
 WRAPPER_ASSIGNMENTS: Sequence[str]
 WRAPPER_UPDATES: Sequence[str]

stdlib/3/gc.pyi

@@ -1,6 +1,7 @@
 # Stubs for gc
 
-from typing import Any, Dict, List, Tuple
+import sys
+from typing import Any, Dict, List, Optional, Tuple
 
 
 DEBUG_COLLECTABLE: int
@@ -16,7 +17,10 @@ def disable() -> None: ...
 def enable() -> None: ...
 def get_count() -> Tuple[int, int, int]: ...
 def get_debug() -> int: ...
-def get_objects() -> List[Any]: ...
+if sys.version_info >= (3, 8):
+    def get_objects(generation: Optional[int] = ...) -> List[Any]: ...
+else:
+    def get_objects() -> List[Any]: ...
 def get_referents(*objs: Any) -> List[Any]: ...
 def get_referrers(*objs: Any) -> List[Any]: ...
 def get_stats() -> List[Dict[str, Any]]: ...

stdlib/3/gettext.pyi

@@ -14,6 +14,8 @@ class NullTranslations:
     def lgettext(self, message: str) -> str: ...
     def ngettext(self, singular: str, plural: str, n: int) -> str: ...
     def lngettext(self, singular: str, plural: str, n: int) -> str: ...
+    def pgettext(self, context: str, message: str) -> str: ...
+    def npgettext(self, context: str, msgid1: str, msgid2: str, n: int) -> str: ...
     def info(self) -> Any: ...
     def charset(self) -> Any: ...
     def output_charset(self) -> Any: ...
@@ -52,5 +54,9 @@ def gettext(message: str) -> str: ...
 def lgettext(message: str) -> str: ...
 def ngettext(singular: str, plural: str, n: int) -> str: ...
 def lngettext(singular: str, plural: str, n: int) -> str: ...
+def pgettext(context: str, message: str) -> str: ...
+def dpgettext(domain: str, context: str, message: str) -> str: ...
+def npgettext(context: str, msgid1: str, msgid2: str, n: int) -> str: ...
+def dnpgettext(domain: str, context: str, msgid1: str, msgid2: str, n: int) -> str: ...
 
 Catalog = translation

stdlib/3/gzip.pyi

@@ -1,6 +1,7 @@
 from typing import Any, IO, Optional
 from os.path import _PathType
 import _compression
+import sys
 import zlib
 
 def open(filename, mode: str = ..., compresslevel: int = ..., encoding: Optional[str] = ..., errors: Optional[str] = ..., newline: Optional[str] = ...) -> IO[Any]: ...
@@ -45,5 +46,8 @@ class _GzipReader(_compression.DecompressReader):
     def __init__(self, fp: IO[bytes]) -> None: ...
     def read(self, size: int = ...) -> bytes: ...
 
-def compress(data, compresslevel: int = ...) -> bytes: ...
+if sys.version_info >= (3, 8):
+    def compress(data, compresslevel: int = ..., *, mtime: Optional[float] = ...) -> bytes: ...
+else:
+    def compress(data, compresslevel: int = ...) -> bytes: ...
 def decompress(data: bytes) -> bytes: ...