Merge branch 'python/master'

* python/master: (269 commits)
  allow Optional[float] for asyncio.wait() timeout arg (python#1860)
  Clean up the pytype blacklist. (python#1851)
  filter function: make the callable of the first overload non-optional so that mypy is able to select the second overload for the  case. (python#1855)
  Accept Text in distutils *Version classes (python#1854)
  Add attrs library (python#1838)
  Add type stub for the lzma module (python#1844)
  Add ImportError attributes name, path for Python 3.3+ (python#1849)
  Add 'message' to click.decorators.version_option (python#1845)
  PEP 553 and PEP 564 (python#1846)
  Adding py36 additions to datetime module (python#1848)
  Remove incomplete thrift stubs that cause false positives. (python#1827)
  adding curses.ascii, curses.panel and curses.textpad modules (python#1792)
  Fix requests session hooks type (python#1794)
  Add StringIO.name and BytesIO.name (python#1802)
  Fix werkzeug environ type (python#1831)
  Change the return type of unittest.TestCase.fail() to NoReturn (python#1843)
  _curses.tparm works on bytes, not str (python#1828)
  Refine types for distutils.version (python#1835)
  Add stub for stat.filemode (python#1837)
  modify pytype_test to run from within pytype too, and support python3 (python#1817)
  ...

Author: rhysparry

.flake8

@@ -14,7 +14,7 @@
 #    34 E127 continuation line over-indented for visual indent
 
 [flake8]
-ignore = F401, F811, E127, E128, E301, E302, E305, E501, E701, E704, B303
+ignore = F401, F403, F405, F811, E127, E128, E301, E302, E305, E501, E701, E704, B303
 # We are checking with Python 3 but many of the stubs are Python 2 stubs.
 # A nice future improvement would be to provide separate .flake8
 # configurations for Python 2 and Python 3 files.

.travis.yml

@@ -11,12 +11,13 @@ matrix:
       env: TEST_CMD="./tests/mypy_test.py --no-implicit-optional"
     - python: "2.7"
       env: TEST_CMD="./tests/pytype_test.py --num-parallel=4"
+      sudo: true
 
 install:
   # pytype needs py-2.7, mypy needs py-3.3+. Additional logic in runtests.py
   - if [[ $TRAVIS_PYTHON_VERSION == '3.6-dev' ]]; then pip install -U flake8==3.3.0 flake8-bugbear>=17.3.0 flake8-pyi>=17.1.0; fi
   - if [[ $TRAVIS_PYTHON_VERSION == '3.5' ]]; then pip install -U git+git://github.com/python/mypy git+git://github.com/python/typed_ast; fi
-  - if [[ $TRAVIS_PYTHON_VERSION == '2.7' ]]; then pip install -U git+git://github.com/google/pytype; fi
+  - if [[ $TRAVIS_PYTHON_VERSION == '2.7' ]]; then pip install -U git+git://github.com/google/pytype; wget https://s3.amazonaws.com/travis-python-archives/binaries/ubuntu/14.04/x86_64/python-3.6.tar.bz2; sudo tar xjf python-3.6.tar.bz2 --directory /; fi
 
 script:
   - $TEST_CMD

CONTRIBUTING.md

@@ -69,6 +69,15 @@ For every pull request, we aim to promptly either merge it or say why
 it's not yet ready; if you go a few days without a reply, please feel
 free to ping the thread by adding a new comment.
 
+To get your pull request merged sooner, you should explain why you are
+making the change. For example, you can point to a code sample that is
+processed incorrectly by a type checker. It is also helpful to add
+links to online documentation or to the implementation of the code
+you are changing.
+
+Also, do not squash your commits after you have submitted a pull request, as this
+erases context during review. We will squash commits when the pull request is merged.
+
 At present the core developers are (alphabetically):
 * David Fisher (@ddfisher)
 * Łukasz Langa (@ambv)
@@ -106,19 +115,59 @@ message where you received permission**.
 Make sure your changes pass the tests (the [README](README.md#running-the-tests)
 has more information).
 
+### What to include
+
+Stubs should include all public objects (classes, functions, constants,
+etc.) in the module they cover. Omitting objects can confuse users,
+because users who see an error like "module X has no attribute Y" will
+not know whether the error appeared because their code had a bug or
+because the stub is wrong. If you are submitting stubs to typeshed and
+you are unable to provide fully typed stubs for some of the objects in
+the library, you can use stubgen (see below) to generate untyped stubs.
+Although we prefer having exact types for all stubs, such stubs are
+better than nothing.
+
+What counts as a "public object" is not always clear. Use your judgment,
+but objects that are listed in the module's documentation, that are
+included in ``__all__`` (if present), and whose names do not start with an
+underscore are more likely to merit inclusion in a stub. If in doubt, err
+on the side of including more objects.
+
 ### Using stubgen
 
 Mypy includes a tool called [stubgen](https://github.com/python/mypy/blob/master/mypy/stubgen.py)
 that you can use as a starting point for your stubs.  Note that this
 generator is currently unable to determine most argument and return
 types and omits them or uses ``Any`` in their place.  Fill out the types
-that you know.  Leave out modules that you are not using at all.  It's
-strictly better to provide partial stubs that have detailed type
-information than to submit unmodified ``stubgen`` output for an entire
-library.
+that you know.
 
 ### Stub file coding style
 
+#### Syntax example
+
+The below is an excerpt from the types for the `datetime` module.
+
+```python
+MAXYEAR: int
+MINYEAR: int
+
+class date:
+    def __init__(self, year: int, month: int, day: int) -> None: ...
+    @classmethod
+    def fromtimestamp(cls, timestamp: float) -> date: ...
+    @classmethod
+    def today(cls) -> date: ...
+    @classmethod
+    def fromordinal(cls, ordinal: int) -> date: ...
+    @property
+    def year(self) -> int: ...
+    def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ...
+    def ctime(self) -> str: ...
+    def weekday(self) -> int: ...
+```
+
+#### Conventions
+
 Stub files are *like* Python files and you should generally expect them
 to look the same.  Your tools should be able to successfully treat them
 as regular Python files.  However, there are a few important differences
@@ -136,8 +185,25 @@ rule is that they should be as concise as possible.  Specifically:
 * use a single blank line between top-level class definitions, or none
   if the classes are very small;
 * 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 `=`.
 
+Stub files should only contain information necessary for the type
+checker, and leave out unnecessary detail:
+* for arguments with a default, use `...` instead of the actual
+  default;
+* for arguments that default to `None`, use `Optional[]` explicitly
+  (see below for details);
+* use `float` instead of `Union[int, float]`.
+
+Some further tips for good type hints:
+* avoid invariant collection types (`List`, `Dict`) in argument
+  positions, in favor of covariant types like `Mapping` or `Sequence`;
+* avoid Union return types: https://github.com/python/mypy/issues/1693;
+* in Python 2, whenever possible, use `unicode` if that's the only
+  possible type, and `Text` if it can be either `unicode` or `bytes`.
+
 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
@@ -231,7 +297,7 @@ project's tracker to fix their documentation.
 ## Issue-tracker conventions
 
 We aim to reply to all new issues promptly.  We'll assign one or more
-labels to to indicate we've triaged an issue, but most typeshed issues
+labels to indicate we've triaged an issue, but most typeshed issues
 are relatively simple (stubs for a given module or package are
 missing, incomplete or incorrect) and we won't add noise to the
 tracker by labeling all of them.  Here's what our labels mean.  (We

README.md

@@ -1,5 +1,6 @@
 # typeshed
 
+[![Build Status](https://travis-ci.org/python/typeshed.svg?branch=master)](https://travis-ci.org/python/typeshed)
 [![Chat at https://gitter.im/python/typing](https://badges.gitter.im/python/typing.svg)](https://gitter.im/python/typing?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ## About
@@ -48,30 +49,9 @@ file (i.e., it can be interpreted by Python 3), except all the methods are empty
 Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/))
 are used to describe the types the function has.
 
-See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax
-of the stub files.
-
-## Syntax example
-
-The below is an excerpt from the types for the `datetime` module.
-
-```python
-from typing import Union
-
-MAXYEAR = ...  # type: int
-MINYEAR = ...  # type: int
-
-class date(object):
-    def __init__(self, year: int, month: int, day: int) -> None: ...
-    @classmethod
-    def fromtimestamp(cls, timestamp: Union[int, float]) -> date: ...
-    @classmethod
-    def fromordinal(cls, ordinal: int) -> date: ...
-    @classmethod
-    def today(self) -> date: ...
-    def ctime(self) -> str: ...
-    def weekday(self) -> int: ...
-```
+See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact
+syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the
+coding style used in typeshed.
 
 ## Directory structure
 
@@ -147,7 +127,7 @@ invoking:
 (Note that flake8 only works with Python 3.6 or higher.)
 
 To run the pytype tests, you need a separate virtual environment with
-Python 2.7. Run:
+Python 2.7, and a Python 3.6 interpreter somewhere you can point to. Run:
 ```
 $ virtualenv --python=python2.7 .venv2
 $ source .venv2/bin/activate
@@ -156,7 +136,7 @@ $ source .venv2/bin/activate
 This will install pytype from its GitHub repo. You can then run pytype
 tests by running:
 ```
-(.venv2)$ python tests/pytype_test.py
+(.venv2)$ python tests/pytype_test.py --python36-exe=/path/to/python3.6
 ```
 
 For mypy, if you are in the typeshed repo that is submodule of the

stdlib/2/ConfigParser.pyi

@@ -78,10 +78,10 @@ class RawConfigParser:
     def optionxform(self, optionstr: str) -> str: ...
     def has_option(self, section: str, option: str) -> bool: ...
     def set(self, section: str, option: str, value: Any = ...) -> None: ...
-    def write(self, fp: file) -> None: ...
+    def write(self, fp: IO[str]) -> None: ...
     def remove_option(self, section: str, option: Any) -> bool: ...
     def remove_section(self, section: str) -> bool: ...
-    def _read(self, fp: file, fpname: str) -> None: ...
+    def _read(self, fp: IO[str], fpname: str) -> None: ...
 
 class ConfigParser(RawConfigParser):
     _KEYCRE = ...  # type: Any