Add coding style recommendations for variable annotations (#548)

pep-0008.txt

@@ -1397,6 +1397,39 @@ annotations are changing.
   can be added in the form of comments.  See the relevant section of
   PEP 484 [6]_.
 
+Variable annotations
+--------------------
+
+PEP 526 introduced variable annotations. The style recommendations for them are
+similar to those on function annotations described above:
+
+- Annotations for module level variables, class and instance variables,
+  and local variables should have a single space after the colon.
+
+- There should be no space before the colon.
+
+- If an assignment has a right hand side, then the equality sign should have
+  exactly one space on both sides.
+
+- Yes::
+
+    code: int
+
+    class Point:
+        coords: Tuple[int, int]
+        label: str = '<unknown>'
+
+- No::
+
+    code:int  # No space after colon
+    code : int  # Space before colon
+
+    class Test:
+        result: int=0  # No spaces around equality sign
+
+- Although the PEP 526 is accepted for Python 3.6, the variable annotation
+  syntax is the preferred syntax for stub files on all versions of Python
+  (see PEP 484 for details).
 
 .. rubric:: Footnotes
 

pep-0484.txt

@@ -1484,14 +1484,16 @@ Examples of type comments on ``with`` and ``for`` statements::
       ...
 
 In stubs it may be useful to declare the existence of a variable
-without giving it an initial value.  This can be done using a literal
+without giving it an initial value.  This can be done using PEP 526
-ellipsis::
+variable annotation syntax::
 
   from typing import IO
 
-  stream = ...  # type: IO[str]
+  stream: IO[str]
 
-In non-stub code, there is a similar special case::
+The above syntax is acceptable in stubs for all versions of Python.
+However, in non-stub code for versions of Python 3.5 and earlier
+there is a special case::
 
   from typing import IO
 

pep-0526.txt

@@ -341,6 +341,46 @@ unpacking::
   with myfunc() as f:
       ...
 
+Variable annotations in stub files
+**********************************
+
+As variable annotations are more readable than type comments, they are
+preferred in stub files for all versions of Python, including Python 2.7.
+Note that stub files are not executed by Python interpreters, and therefore
+using variable annotations will not lead to errors. Type checkers should
+support variable annotations in stubs for all versions of Python. For example::
+
+  # file lib.pyi
+
+  ADDRESS: unicode = ...
+
+  class Error:
+      cause: Union[str, unicode]
+
+Preferred coding style for variable annotations
+***********************************************
+
+Annotations for module level variables, class and instance variables,
+and local variables should have a single space after corresponding colon.
+There should be no space before the colon. If an assignment has right hand
+side, then the equality sign should have exactly one space on both sides.
+Examples:
+* Yes::
+
+    code: int
+
+    class Point:
+        coords: Tuple[int, int]
+        label: str = '<unknown>'
+
+* No::
+
+    code:int  # No space after colon
+    code : int  # Space before colon
+
+    class Test:
+        result: int=0  # No spaces around equality sign
+
 
 Changes to Standard Library and Documentation
 =============================================