Require black and isort for contributions (#3329)

* Add explanation to CONTRIBUTNG.md
* Add sample pre-commit script
* Check for correctly formatted files in CI

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

.travis.yml

@@ -27,5 +27,12 @@ jobs:
     - name: "check file consistency"
       script: ./tests/check_consistent.py
     - name: "flake8"
-      install: pip install -r requirements-tests-py3.txt
+      install: pip install $(grep flake8 requirements-tests-py3.txt)
       script: flake8
+    - name: "black"
+      install: pip install $(grep black requirements-tests-py3.txt)
+      script: black --check --diff stdlib third_party
+  allow_failures:
+    - name: "isort"
+      install: pip install $(grep isort requirements-tests-py3.txt)
+      script: isort --check-only --diff --recursive stdlib third_party

CONTRIBUTING.md

@@ -15,6 +15,7 @@ are important to the project's success.
       but [contact us](#discussion) before starting significant work.
     * Create your stubs [conforming to the coding style](#stub-file-coding-style).
     * Make sure your tests pass cleanly on `mypy`, `pytype`, and `flake8`.
+    * Reformat your stubs with `black` and `isort`.
 4. [Submit your changes](#submitting-changes) by opening a pull request.
 5. You can expect a reply within a few days:
     * Diffs are merged when considered ready by the core team.
@@ -222,8 +223,14 @@ rule is that they should be as concise as possible.  Specifically:
 * 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/psf/black) will format
-stubs according to this standard.
+
+Stubs should be reformatted with the formatters
+[black](https://github.com/psf/black) and
+[isort](https://github.com/timothycrosley/isort) before submission.
+These formatters are included in typeshed's `requirements-tests-py3.txt` file.
+A sample `pre-commit` file is included in the typeshed repository.  Copy it
+to `.git/hooks` and adjust the path to your virtual environment's `bin`
+directory to automatically reformat stubs before commit.
 
 Stub files should only contain information necessary for the type
 checker, and leave out unnecessary detail:

pre-commit

@@ -0,0 +1,28 @@
+#!/bin/sh
+#
+# An example hook script that will run flake8, black, and isort
+# prior to committing and will stop the commit if there are any
+# warnings. Adjust BIN_DIR to the virtual environment where flake8,
+# black, and isort are installed.
+#
+# To enable this hook, copy this file to ".git/hooks".
+
+BIN_DIR=./.venv/bin
+
+CHANGED_FILES=$(git diff --cached --name-only --diff-filter=AM | grep .pyi || true)
+
+if test -n "${CHANGED_FILES}" -a -d "${BIN_DIR}"; then
+    ${BIN_DIR}/flake8 ${CHANGED_FILES}
+    ${BIN_DIR}/black --check ${CHANGED_FILES}
+    ${BIN_DIR}/isort --check-only ${CHANGED_FILES}
+
+    # Replace the last two lines with the following lines
+    # if you want to reformat changed files automatically
+    # before committing. Please note that partial commits
+    # (git add -p) will not work and will commit the whole
+    # file!
+    #
+    # ${BIN_DIR}/black ${CHANGED_FILES} || true
+    # ${BIN_DIR}/isort -y ${CHANGED_FILES} || true
+    # git add ${CHANGED_FILES}
+fi

requirements-tests-py3.txt

@@ -4,5 +4,5 @@ black==19.10b0
 flake8==3.8.2
 flake8-bugbear==20.1.4
 flake8-pyi==20.5.0
-isort==4.3.21
+isort[pyproject]==4.3.21
 pytype>=2020.06.26

stdlib/2and3/difflib.pyi

@@ -57,10 +57,7 @@ class SequenceMatcher(Generic[_T]):
 # mypy thinks the signatures of the overloads overlap, but the types still work fine
 @overload
 def get_close_matches(  # type: ignore
-    word: AnyStr,
-    possibilities: Iterable[AnyStr],
-    n: int = ...,
-    cutoff: float = ...,
+    word: AnyStr, possibilities: Iterable[AnyStr], n: int = ..., cutoff: float = ...,
 ) -> List[AnyStr]: ...
 @overload
 def get_close_matches(

stdlib/3/asyncio/base_events.pyi

@@ -73,10 +73,7 @@ class BaseEventLoop(AbstractEventLoop, metaclass=ABCMeta):
     # run_in_executor is defined as a coroutine in AbstractEventLoop but returns a Future in concrete implementation.
     # Need to ignore mypy Return type error as a result.
     def run_in_executor(  # type: ignore
-        self,
-        executor: Any,
-        func: Callable[..., _T],
-        *args: Any,
+        self, executor: Any, func: Callable[..., _T], *args: Any,
     ) -> Future[_T]: ...
     def set_default_executor(self, executor: Any) -> None: ...
     # Network I/O methods returning Futures.