Add auto-formatting via isort and black

.travis.yml

@@ -4,6 +4,13 @@ python: 3.7
 
 matrix:
   include:
+    - name: "autoformatters"
+      python: 3.6
+      env:
+        - INSTALL="test"
+      script:
+        - isort --check-only --recursive .
+        - black --check stdlib tests third_party
     - name: "pytype"
       python: 3.6
       env:

CONTRIBUTING.md

@@ -15,7 +15,7 @@ are important to the project's success.
       but [contact us](#discussion) before starting significant work.
     * IMPORTANT: For new libraries, [get permission from the library owner first](#adding-a-new-library).
     * Create your stubs [conforming to the coding style](#stub-file-coding-style).
-    * Make sure your tests pass cleanly on `mypy`, `pytype`, and `flake8`.
+    * Make sure you first run the autoformmaters `isort` and `black`, then that the tests pass cleanly on `mypy`, `pytype`, and `flake8`.
 4. [Submit your changes](#submitting-changes):
     * Open a pull request
     * For new libraries, [include a reference to where you got permission](#adding-a-new-library)
@@ -223,23 +223,24 @@ as regular Python files.  However, there are a few important differences
 you should know about.
 
 Style conventions for stub files are different from PEP 8. The general
-rule is that they should be as concise as possible.  Specifically:
+rule is that they should be as concise as possible.
+
+We use the code formatter [Black](https://github.com/python/black) to automatically use the below conventions:
 * lines can be up to 130 characters long;
 * functions and methods that don't fit in one line should be split up
   with one argument per line;
-* all function bodies should be empty;
-* prefer ``...`` over ``pass``;
 * prefer ``...`` on the same line as the class/function signature;
 * avoid vertical whitespace between consecutive module-level functions,
   names, or methods and fields within a single class;
-* use a single blank line between top-level class definitions, or none
-  if the classes are very small;
+* use a single blank line between top-level class definitions;
+* for arguments with a type and a default, use spaces around the `=`.
+
+Stub files should also use these style conventions, which Black cannot automatically fix:
+* all function bodies should be empty;
+* prefer ``...`` over ``pass``;
 * do not use docstrings;
 * use variable annotations instead of type comments, even for stubs
   that target older versions of Python;
-* for arguments with a type and a default, use spaces around the `=`.
-The code formatter [black](https://github.com/python/black) will format
-stubs according to this standard.
 
 Stub files should only contain information necessary for the type
 checker, and leave out unnecessary detail:
@@ -258,7 +259,7 @@ Some further tips for good type hints:
 * use platform checks like `if sys.platform == 'win32'` to denote
   platform-dependent APIs.
 
-Imports in stubs are considered private (not part of the exported API)
+Imports in stubs are considered private (not part of the exported API),
 unless:
 * they use the form ``from library import name as name`` (sic, using
   explicit ``as`` even if the name stays the same); or

README.md

@@ -86,7 +86,7 @@ https://github.com/python/typeshed/blob/master/CONTRIBUTING.md#stub-versioning).
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull
 requests. If you have questions related to contributing, drop by the [typing Gitter](https://gitter.im/python/typing).
 
-## Running the tests
+## Running the tests and autoformatters
 
 The tests are automatically run by Travis CI on every PR and push to
 the repo.  There are several sets of tests: `tests/mypy_test.py`
@@ -114,19 +114,26 @@ $ python3.6 -m venv .venv3
 $ source .venv3/bin/activate
 (.venv3)$ pip3 install -r requirements-tests-py3.txt
 ```
-This will install mypy (you need the latest master branch from GitHub),
-typed-ast, flake8, and pytype. You can then run mypy, flake8, and pytype tests
-by invoking:
+This will install mypy (we use the latest master branch from GitHub),
+typed-ast, flake8, pytype, isort, and black. You can then run the tests
+ and autoformatters by invoking:
 ```
-(.venv3)$ python3 tests/mypy_test.py
+(.venv3)$ isort --recursive .
 ...
-(.venv3)$ python3 tests/mypy_selftest.py
+(.venv3)$ black stdlib tests third_party
 ...
 (.venv3)$ flake8
 ...
+(.venv3)$ python3 tests/mypy_test.py
+...
+(.venv3)$ python3 tests/mypy_selftest.py
+...
 (.venv3)$ python3 tests/pytype_test.py
 ...
 ```
+
+If `black` or `isort` made any changes, be sure to commit them before making a pull request.
+
 Note that flake8 only works with Python 3.6 or higher, and that to run the
 pytype tests, you will need Python 2.7 and Python 3.6 interpreters. Pytype will
 find these automatically if they're in `PATH`, but otherwise you must point to

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.black]
+line_length = 130
+
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+combine_as_imports = true
+line_length = 130

requirements-tests-py3.txt

@@ -1,6 +1,8 @@
 git+https://github.com/python/mypy.git@master
 typed-ast>=1.0.4
+black==19.3b0
 flake8==3.6.0
 flake8-bugbear==18.8.0
 flake8-pyi==18.3.1
+isort==4.3.20
 pytype>=2019.5.15

stdlib/2/BaseHTTPServer.pyi

@@ -1,14 +1,13 @@
 # Stubs for BaseHTTPServer (Python 2.7)
 
-from typing import Any, BinaryIO, Mapping, Optional, Tuple, Union
-import SocketServer
 import mimetools
+import SocketServer
+from typing import Any, BinaryIO, Mapping, Optional, Tuple, Union
 
 class HTTPServer(SocketServer.TCPServer):
     server_name: str
     server_port: int
-    def __init__(self, server_address: Tuple[str, int],
-                 RequestHandlerClass: type) -> None: ...
+    def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type) -> None: ...
 
 class BaseHTTPRequestHandler:
     client_address: Tuple[str, int]
@@ -27,18 +26,15 @@ class BaseHTTPRequestHandler:
     protocol_version: str
     MessageClass: type
     responses: Mapping[int, Tuple[str, str]]
-    def __init__(self, request: bytes, client_address: Tuple[str, int],
-                 server: SocketServer.BaseServer) -> None: ...
+    def __init__(self, request: bytes, client_address: Tuple[str, int], server: SocketServer.BaseServer) -> None: ...
     def handle(self) -> None: ...
     def handle_one_request(self) -> None: ...
     def send_error(self, code: int, message: Optional[str] = ...) -> None: ...
-    def send_response(self, code: int,
-                      message: Optional[str] = ...) -> None: ...
+    def send_response(self, code: int, message: Optional[str] = ...) -> None: ...
     def send_header(self, keyword: str, value: str) -> None: ...
     def end_headers(self) -> None: ...
     def flush_headers(self) -> None: ...
-    def log_request(self, code: Union[int, str] = ...,
-                    size: Union[int, str] = ...) -> None: ...
+    def log_request(self, code: Union[int, str] = ..., size: Union[int, str] = ...) -> None: ...
     def log_error(self, format: str, *args: Any) -> None: ...
     def log_message(self, format: str, *args: Any) -> None: ...
     def version_string(self) -> str: ...

stdlib/2/ConfigParser.pyi

@@ -1,4 +1,4 @@
-from typing import Any, IO, Sequence, Tuple, Union, List, Dict, Protocol, Optional
+from typing import IO, Any, Dict, List, Optional, Protocol, Sequence, Tuple, Union
 
 DEFAULTSECT: str
 MAX_INTERPOLATION_DEPTH: int

stdlib/2/HTMLParser.pyi

@@ -1,16 +1,15 @@
-from typing import List, Tuple, AnyStr
+from typing import AnyStr, List, Tuple
+
 from markupbase import ParserBase
 
 class HTMLParser(ParserBase):
     def __init__(self) -> None: ...
     def feed(self, feed: AnyStr) -> None: ...
     def close(self) -> None: ...
     def reset(self) -> None: ...
-
     def get_starttag_text(self) -> AnyStr: ...
     def set_cdata_mode(self, AnyStr) -> None: ...
     def clear_cdata_mode(self) -> None: ...
-
     def handle_startendtag(self, tag: AnyStr, attrs: List[Tuple[AnyStr, AnyStr]]): ...
     def handle_starttag(self, tag: AnyStr, attrs: List[Tuple[AnyStr, AnyStr]]): ...
     def handle_endtag(self, tag: AnyStr): ...
@@ -20,9 +19,7 @@ class HTMLParser(ParserBase):
     def handle_comment(self, data: AnyStr): ...
     def handle_decl(self, decl: AnyStr): ...
     def handle_pi(self, data: AnyStr): ...
-
     def unknown_decl(self, data: AnyStr): ...
-
     def unescape(self, s: AnyStr) -> AnyStr: ...
 
 class HTMLParseError(Exception):

stdlib/2/Queue.pyi

@@ -1,9 +1,9 @@
 # Stubs for Queue (Python 2)
 
 from collections import deque
-from typing import Any, TypeVar, Generic, Optional
+from typing import Any, Generic, Optional, TypeVar
 
-_T = TypeVar('_T')
+_T = TypeVar("_T")
 
 class Empty(Exception): ...
 class Full(Exception): ...

stdlib/2/SimpleHTTPServer.pyi

@@ -1,8 +1,8 @@
 # Stubs for SimpleHTTPServer (Python 2)
 
-from typing import Any, AnyStr, IO, Mapping, Optional, Union
 import BaseHTTPServer
 from StringIO import StringIO
+from typing import IO, Any, AnyStr, Mapping, Optional, Union
 
 class SimpleHTTPRequestHandler(BaseHTTPServer.BaseHTTPRequestHandler):
     server_version: str

stdlib/2/SocketServer.pyi

@@ -1,10 +1,10 @@
 # NB: SocketServer.pyi and socketserver.pyi must remain consistent!
 # Stubs for socketserver
 
-from typing import Any, BinaryIO, Optional, Tuple, Type
-from socket import SocketType
 import sys
 import types
+from socket import SocketType
+from typing import Any, BinaryIO, Optional, Tuple, Type
 
 class BaseServer:
     address_family: int
@@ -15,66 +15,51 @@ class BaseServer:
     request_queue_size: int
     socket_type: int
     timeout: Optional[float]
-    def __init__(self, server_address: Tuple[str, int],
-                 RequestHandlerClass: type) -> None: ...
+    def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type) -> None: ...
     def fileno(self) -> int: ...
     def handle_request(self) -> None: ...
     def serve_forever(self, poll_interval: float = ...) -> None: ...
     def shutdown(self) -> None: ...
     def server_close(self) -> None: ...
-    def finish_request(self, request: bytes,
-                       client_address: Tuple[str, int]) -> None: ...
+    def finish_request(self, request: bytes, client_address: Tuple[str, int]) -> None: ...
     def get_request(self) -> None: ...
-    def handle_error(self, request: bytes,
-                     client_address: Tuple[str, int]) -> None: ...
+    def handle_error(self, request: bytes, client_address: Tuple[str, int]) -> None: ...
     def handle_timeout(self) -> None: ...
-    def process_request(self, request: bytes,
-                        client_address: Tuple[str, int]) -> None: ...
+    def process_request(self, request: bytes, client_address: Tuple[str, int]) -> None: ...
     def server_activate(self) -> None: ...
     def server_bind(self) -> None: ...
-    def verify_request(self, request: bytes,
-                       client_address: Tuple[str, int]) -> bool: ...
+    def verify_request(self, request: bytes, client_address: Tuple[str, int]) -> bool: ...
     if sys.version_info >= (3, 6):
         def __enter__(self) -> BaseServer: ...
-        def __exit__(self, exc_type: Optional[Type[BaseException]],
-                     exc_val: Optional[BaseException],
-                     exc_tb: Optional[types.TracebackType]) -> bool: ...
+        def __exit__(
+            self, exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[types.TracebackType]
+        ) -> bool: ...
     if sys.version_info >= (3, 3):
         def service_actions(self) -> None: ...
 
 class TCPServer(BaseServer):
-    def __init__(self, server_address: Tuple[str, int],
-                 RequestHandlerClass: type,
-                 bind_and_activate: bool = ...) -> None: ...
+    def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type, bind_and_activate: bool = ...) -> None: ...
 
 class UDPServer(BaseServer):
-    def __init__(self, server_address: Tuple[str, int],
-                 RequestHandlerClass: type,
-                 bind_and_activate: bool = ...) -> None: ...
+    def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type, bind_and_activate: bool = ...) -> None: ...
 
-if sys.platform != 'win32':
+if sys.platform != "win32":
     class UnixStreamServer(BaseServer):
-        def __init__(self, server_address: Tuple[str, int],
-                     RequestHandlerClass: type,
-                     bind_and_activate: bool = ...) -> None: ...
-
+        def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type, bind_and_activate: bool = ...) -> None: ...
     class UnixDatagramServer(BaseServer):
-        def __init__(self, server_address: Tuple[str, int],
-                     RequestHandlerClass: type,
-                     bind_and_activate: bool = ...) -> None: ...
+        def __init__(self, server_address: Tuple[str, int], RequestHandlerClass: type, bind_and_activate: bool = ...) -> None: ...
 
 class ForkingMixIn: ...
 class ThreadingMixIn: ...
-
 class ForkingTCPServer(ForkingMixIn, TCPServer): ...
 class ForkingUDPServer(ForkingMixIn, UDPServer): ...
 class ThreadingTCPServer(ThreadingMixIn, TCPServer): ...
 class ThreadingUDPServer(ThreadingMixIn, UDPServer): ...
-if sys.platform != 'win32':
+
+if sys.platform != "win32":
     class ThreadingUnixStreamServer(ThreadingMixIn, UnixStreamServer): ...
     class ThreadingUnixDatagramServer(ThreadingMixIn, UnixDatagramServer): ...
 
-
 class BaseRequestHandler:
     # Those are technically of types, respectively:
     # * Union[SocketType, Tuple[bytes, SocketType]]

stdlib/2/StringIO.pyi

@@ -1,6 +1,6 @@
 # Stubs for StringIO (Python 2)
 
-from typing import Any, IO, AnyStr, Iterator, Iterable, Generic, List, Optional
+from typing import IO, Any, AnyStr, Generic, Iterable, Iterator, List, Optional
 
 class StringIO(IO[AnyStr], Generic[AnyStr]):
     closed: bool

stdlib/2/UserDict.pyi

@@ -1,25 +1,35 @@
-from typing import (Any, Container, Dict, Generic, Iterable, Iterator, List,
-                    Mapping, Optional, Sized, Tuple, TypeVar, Union, overload)
-
-_KT = TypeVar('_KT')
-_VT = TypeVar('_VT')
-_T = TypeVar('_T')
+from typing import (
+    Any,
+    Container,
+    Dict,
+    Generic,
+    Iterable,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Sized,
+    Tuple,
+    TypeVar,
+    Union,
+    overload,
+)
+
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+_T = TypeVar("_T")
 
 class UserDict(Dict[_KT, _VT], Generic[_KT, _VT]):
     data: Mapping[_KT, _VT]
-
     def __init__(self, initialdata: Mapping[_KT, _VT] = ...) -> None: ...
-
     # TODO: __iter__ is not available for UserDict
 
-class IterableUserDict(UserDict[_KT, _VT], Generic[_KT, _VT]):
-    ...
+class IterableUserDict(UserDict[_KT, _VT], Generic[_KT, _VT]): ...
 
 class DictMixin(Iterable[_KT], Container[_KT], Sized, Generic[_KT, _VT]):
     def has_key(self, key: _KT) -> bool: ...
     def __len__(self) -> int: ...
     def __iter__(self) -> Iterator[_KT]: ...
-
     # From  typing.Mapping[_KT, _VT]
     # (can't inherit because of keys())
     @overload
@@ -32,7 +42,6 @@ class DictMixin(Iterable[_KT], Container[_KT], Sized, Generic[_KT, _VT]):
     def itervalues(self) -> Iterator[_VT]: ...
     def iteritems(self) -> Iterator[Tuple[_KT, _VT]]: ...
     def __contains__(self, o: Any) -> bool: ...
-
     # From typing.MutableMapping[_KT, _VT]
     def clear(self) -> None: ...
     def pop(self, k: _KT, default: _VT = ...) -> _VT: ...

stdlib/2/UserString.pyi

@@ -1,5 +1,5 @@
 import collections
-from typing import Any, Iterable, List, MutableSequence, Sequence, Optional, overload, Text, TypeVar, Tuple, Union
+from typing import Any, Iterable, List, MutableSequence, Optional, Sequence, Text, Tuple, TypeVar, Union, overload
 
 _UST = TypeVar("_UST", bound=UserString)
 _MST = TypeVar("_MST", bound=MutableString)