os: merge the top and bottom of os/__init__.pyi (#1458)

* os: merge the top and bottom of os/__init__.pyi

Part of #1427. In preparation for merging the two stubs, I'm making the files
identical as much as possible. This PR merges the top of the file, down to
but not including the definition of statvfs_result, and the bottom up to
and including os.utime.

This PR mostly adds more "if sys.version_info" block. Until the merger
completes, we'll have some Python 2 blocks in the Python 3 stub and vice versa.
I also add a few missing constants and arguments.

In followup PRs I'll merge the rest of the file. I'll put the trickiest part
(the return values of functions like os.stat) in its own PR.

* back out DirEntry from py2

It relies on stat_result which we don't have yet in py2.

stdlib/2/os/__init__.pyi

@@ -1,6 +1,8 @@
-# created from https://docs.python.org/2/library/os.html
+# Stubs for os
+# Ron Murawski <ron@horizonchess.com>
 
 from builtins import OSError as error
+from io import TextIOWrapper as _TextIOWrapper
 import sys
 from typing import (
     Mapping, MutableMapping, Dict, List, Any, Tuple, Iterator, overload, Union, AnyStr,
@@ -11,11 +13,21 @@ from mypy_extensions import NoReturn
 
 _T = TypeVar('_T')
 
+# ----- os variables -----
+
+if sys.version_info >= (3, 2):
+    supports_bytes_environ: bool
+
+if sys.version_info >= (3, 3):
+    supports_dir_fd: Set[Callable[..., Any]]
+    supports_fd: Set[Callable[..., Any]]
+    supports_effective_ids: Set[Callable[..., Any]]
+    supports_follow_symlinks: Set[Callable[..., Any]]
+
 SEEK_SET: int
 SEEK_CUR: int
 SEEK_END: int
 
-# More constants, copied from stdlib/3/os/__init__.pyi
 O_RDONLY: int
 O_WRONLY: int
 O_RDWR: int
@@ -65,6 +77,8 @@ class _Environ(MutableMapping[AnyStr, AnyStr], Generic[AnyStr]):
     def copy(self) -> Dict[AnyStr, AnyStr]: ...
 
 environ: _Environ[str]
+if sys.version_info >= (3, 2):
+    environb: _Environ[bytes]
 
 confstr_names: Dict[str, int]  # Unix only
 pathconf_names: Dict[str, int]  # Unix only
@@ -86,6 +100,8 @@ EX_TEMPFAIL: int  # Unix only
 EX_PROTOCOL: int  # Unix only
 EX_NOPERM: int    # Unix only
 EX_CONFIG: int    # Unix only
+EX_NOTFOUND: int  # Unix only
+
 P_NOWAIT: int
 P_NOWAITO: int
 P_WAIT: int
@@ -99,7 +115,13 @@ WCONTINUED: int  # some Unix systems
 WUNTRACED: int  # Unix only
 
 TMP_MAX: int  # Undocumented, but used by tempfile
-_PathType = Union[bytes, Text]
+
+# ----- os classes (structures) -----
+if sys.version_info >= (3, 6):
+    from builtins import _PathLike as PathLike  # See comment in builtins
+
+_PathType = path._PathType
+
 _StatVFS = NamedTuple('_StatVFS', [('f_bsize', int), ('f_frsize', int), ('f_blocks', int),
                                    ('f_bfree', int), ('f_bavail', int), ('f_files', int),
                                    ('f_ffree', int), ('f_favail', int), ('f_flag', int),
@@ -202,12 +224,21 @@ def stat_float_times() -> bool: ...
 def statvfs(path: _PathType) -> _StatVFS: ...  # Unix only
 def symlink(source: _PathType, link_name: _PathType) -> None: ...
 def unlink(path: _PathType) -> None: ...
-def utime(path: _PathType, times: Optional[Tuple[float, float]]) -> None: ...
+# TODO: add ns, dir_fd, follow_symlinks argument
+if sys.version_info >= (3, 0):
+    def utime(path: _PathType, times: Optional[Tuple[float, float]] = ...) -> None: ...
+else:
+    def utime(path: _PathType, times: Optional[Tuple[float, float]]) -> None: ...
 
-# TODO onerror: function from OSError to void
-def walk(top: AnyStr, topdown: bool = ..., onerror: Any = ...,
-         followlinks: bool = ...) -> Iterator[Tuple[AnyStr, List[AnyStr],
-                                                    List[AnyStr]]]: ...
+if sys.version_info >= (3, 6):
+    def walk(top: Union[AnyStr, PathLike[AnyStr]], topdown: bool = ...,
+             onerror: Optional[Callable[[OSError], Any]] = ...,
+             followlinks: bool = ...) -> Iterator[Tuple[AnyStr, List[AnyStr],
+                                                        List[AnyStr]]]: ...
+else:
+    def walk(top: AnyStr, topdown: bool = ..., onerror: Optional[Callable[[OSError], Any]] = ...,
+             followlinks: bool = ...) -> Iterator[Tuple[AnyStr, List[AnyStr],
+                                                        List[AnyStr]]]: ...
 
 def abort() -> NoReturn: ...
 # These are defined as execl(file, *args) but the first *arg is mandatory.
@@ -232,11 +263,19 @@ def forkpty() -> Tuple[int, int]: ...  # some flavors of Unix
 def kill(pid: int, sig: int) -> None: ...
 def killpg(pgid: int, sig: int) -> None: ...  # Unix only
 def nice(increment: int) -> int: ...  # Unix only
-# TODO: plock, popen*, P_*
-def popen(command: str, *args, **kwargs) -> Optional[IO[Any]]: ...
-def popen2(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
-def popen3(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any], IO[Any]]: ...
-def popen4(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
+def plock(op: int) -> None: ...  # Unix only ???op is int?
+
+if sys.version_info >= (3, 0):
+    class popen(_TextIOWrapper):
+        # TODO 'b' modes or bytes command not accepted?
+        def __init__(self, command: str, mode: str = ...,
+                     bufsize: int = ...) -> None: ...
+        def close(self) -> Any: ...  # may return int
+else:
+    def popen(command: str, *args, **kwargs) -> Optional[IO[Any]]: ...
+    def popen2(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
+    def popen3(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any], IO[Any]]: ...
+    def popen4(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
 
 def spawnl(mode: int, path: _PathType, arg0: Union[bytes, Text], *args: Union[bytes, Text]) -> int: ...
 def spawnle(mode: int, path: _PathType, arg0: Union[bytes, Text],
@@ -272,10 +311,34 @@ def getloadavg() -> Tuple[float, float, float]: ...  # Unix only
 def sysconf(name: Union[str, int]) -> int: ...  # Unix only
 def urandom(n: int) -> bytes: ...
 
-def tmpfile() -> IO[Any]: ...
-def tmpnam() -> str: ...
-def tempnam(dir: str = ..., prefix: str = ...) -> str: ...
+if sys.version_info >= (3, 0):
+    def sched_getaffinity(id: int) -> Set[int]: ...
+if sys.version_info >= (3, 3):
+    class waitresult:
+        si_pid: int
+    def waitid(idtype: int, id: int, options: int) -> waitresult: ...
+
+if sys.version_info < (3, 0):
+    def tmpfile() -> IO[Any]: ...
+    def tmpnam() -> str: ...
+    def tempnam(dir: str = ..., prefix: str = ...) -> str: ...
 
 P_ALL: int
 WEXITED: int
 WNOWAIT: int
+
+if sys.version_info >= (3, 3):
+    def sync() -> None: ...  # Unix only
+
+    def truncate(path: Union[_PathType, int], length: int) -> None: ...  # Unix only up to version 3.4
+
+    def fwalk(top: AnyStr = ..., topdown: bool = ...,
+              onerror: Callable = ..., *, follow_symlinks: bool = ...,
+              dir_fd: int = ...) -> Iterator[Tuple[AnyStr, List[AnyStr],
+                                             List[AnyStr], int]]: ...  # Unix only
+
+    terminal_size = NamedTuple('terminal_size', [('columns', int), ('lines', int)])
+    def get_terminal_size(fd: int = ...) -> terminal_size: ...
+
+if sys.version_info >= (3, 4):
+    def cpu_count() -> Optional[int]: ...

stdlib/3/os/__init__.pyi

@@ -1,14 +1,12 @@
 # Stubs for os
 # Ron Murawski <ron@horizonchess.com>
 
-# based on http: //docs.python.org/3.2/library/os.html
-
 from builtins import OSError as error
 from io import TextIOWrapper as _TextIOWrapper
 import sys
 from typing import (
     Mapping, MutableMapping, Dict, List, Any, Tuple, Iterator, overload, Union, AnyStr,
-    Optional, Generic, Set, Callable, Text, Sequence, NamedTuple, TypeVar
+    Optional, Generic, Set, Callable, Text, Sequence, IO, NamedTuple, TypeVar
 )
 from . import path as path
 from mypy_extensions import NoReturn
@@ -17,7 +15,8 @@ _T = TypeVar('_T')
 
 # ----- os variables -----
 
-supports_bytes_environ: bool
+if sys.version_info >= (3, 2):
+    supports_bytes_environ: bool
 
 if sys.version_info >= (3, 3):
     supports_dir_fd: Set[Callable[..., Any]]
@@ -56,6 +55,7 @@ O_DIRECT: int     # Gnu extension if in C library
 O_DIRECTORY: int  # Gnu extension if in C library
 O_NOFOLLOW: int   # Gnu extension if in C library
 O_NOATIME: int    # Gnu extension if in C library
+O_LARGEFILE: int  # Gnu extension if in C library
 
 curdir: str
 pardir: str
@@ -77,7 +77,8 @@ class _Environ(MutableMapping[AnyStr, AnyStr], Generic[AnyStr]):
     def copy(self) -> Dict[AnyStr, AnyStr]: ...
 
 environ: _Environ[str]
-environb: _Environ[bytes]
+if sys.version_info >= (3, 2):
+    environb: _Environ[bytes]
 
 confstr_names: Dict[str, int]  # Unix only
 pathconf_names: Dict[str, int]  # Unix only
@@ -346,7 +347,11 @@ def symlink(source: _PathType, link_name: _PathType,
             target_is_directory: bool = ...) -> None:
     ...  # final argument in Windows only
 def unlink(path: _PathType) -> None: ...
-def utime(path: _PathType, times: Optional[Tuple[float, float]] = ...) -> None: ...
+# TODO: add ns, dir_fd, follow_symlinks argument
+if sys.version_info >= (3, 0):
+    def utime(path: _PathType, times: Optional[Tuple[float, float]] = ...) -> None: ...
+else:
+    def utime(path: _PathType, times: Optional[Tuple[float, float]]) -> None: ...
 
 if sys.version_info >= (3, 6):
     def walk(top: Union[AnyStr, PathLike[AnyStr]], topdown: bool = ...,
@@ -383,11 +388,17 @@ def killpg(pgid: int, sig: int) -> None: ...  # Unix only
 def nice(increment: int) -> int: ...  # Unix only
 def plock(op: int) -> None: ...  # Unix only ???op is int?
 
-class popen(_TextIOWrapper):
-    # TODO 'b' modes or bytes command not accepted?
-    def __init__(self, command: str, mode: str = ...,
-                 bufsize: int = ...) -> None: ...
-    def close(self) -> Any: ...  # may return int
+if sys.version_info >= (3, 0):
+    class popen(_TextIOWrapper):
+        # TODO 'b' modes or bytes command not accepted?
+        def __init__(self, command: str, mode: str = ...,
+                     bufsize: int = ...) -> None: ...
+        def close(self) -> Any: ...  # may return int
+else:
+    def popen(command: str, *args, **kwargs) -> Optional[IO[Any]]: ...
+    def popen2(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
+    def popen3(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any], IO[Any]]: ...
+    def popen4(cmd: str, *args, **kwargs) -> Tuple[IO[Any], IO[Any]]: ...
 
 def spawnl(mode: int, path: _PathType, arg0: Union[bytes, Text], *args: Union[bytes, Text]) -> int: ...
 def spawnle(mode: int, path: _PathType, arg0: Union[bytes, Text],
@@ -423,10 +434,18 @@ def getloadavg() -> Tuple[float, float, float]: ...  # Unix only
 def sysconf(name: Union[str, int]) -> int: ...  # Unix only
 def urandom(n: int) -> bytes: ...
 
-def sched_getaffinity(id: int) -> Set[int]: ...
-class waitresult:
-    si_pid: int
-def waitid(idtype: int, id: int, options: int) -> waitresult: ...
+if sys.version_info >= (3, 0):
+    def sched_getaffinity(id: int) -> Set[int]: ...
+if sys.version_info >= (3, 3):
+    class waitresult:
+        si_pid: int
+    def waitid(idtype: int, id: int, options: int) -> waitresult: ...
+
+if sys.version_info < (3, 0):
+    def tmpfile() -> IO[Any]: ...
+    def tmpnam() -> str: ...
+    def tempnam(dir: str = ..., prefix: str = ...) -> str: ...
+
 P_ALL: int
 WEXITED: int
 WNOWAIT: int