Add informative notes to invariant function arguments

mypy/messages.py

@@ -533,6 +533,7 @@ def incompatible_argument(self, n: int, m: int, callee: CallableType, arg_type:
             target = 'to {} '.format(name)
 
         msg = ''
+        notes = []  # type: List[str]
         if callee.name == '<list>':
             name = callee.name[1:-1]
             n -= 1
@@ -571,7 +572,11 @@ def incompatible_argument(self, n: int, m: int, callee: CallableType, arg_type:
                 arg_type_str = '**' + arg_type_str
             msg = 'Argument {} {}has incompatible type {}; expected {}'.format(
                 n, target, arg_type_str, expected_type_str)
+            notes = invariance_notes(notes, arg_type, expected_type)
         self.fail(msg, context)
+        if notes:
+            for note_msg in notes:
+                self.note(note_msg, context)
 
     def invalid_index_type(self, index_type: Type, expected_type: Type, base_str: str,
                            context: Context) -> None:
@@ -992,6 +997,28 @@ def pretty_or(args: List[str]) -> str:
     return ", ".join(quoted[:-1]) + ", or " + quoted[-1]
 
 
+def invariance_notes(notes: List[str], arg_type: Type, expected_type: Type) -> List[str]:
+    """Explain that the type is invariant and give notes for how to solve the issue."""
+    if isinstance(arg_type, Instance) and isinstance(expected_type, Instance):
+        if (arg_type.type.fullname() == 'builtins.list' and
+                expected_type.type.fullname() == 'builtins.list'):
+            invariant_type = 'List'
+            covariant_suggestion = 'Consider using "Sequence" instead, which is covariant'
+        elif (arg_type.type.fullname() == 'builtins.dict' and
+              expected_type.type.fullname() == 'builtins.dict' and
+              arg_type.args[0].type == expected_type.args[0].type and
+              arg_type.args[1].type != expected_type.args[1].type):
+            invariant_type = 'Dict'
+            covariant_suggestion = ('Consider using "Mapping" instead, '
+                                    'which is covariant in the value')
+    if invariant_type:
+        notes.append(
+            '"{}" is invariant --- see '.format(invariant_type) +
+            'http://mypy.readthedocs.io/en/latest/common_issues.html#variance')
+        notes.append(covariant_suggestion)
+    return notes
+
+
 def make_inferred_type_note(context: Context, subtype: Type,
                             supertype: Type, supertype_str: str) -> str:
     """Explain that the user may have forgotten to type a variable.

test-data/unit/check-inference.test

@@ -684,7 +684,9 @@ g('a')() # E: List[str] not callable
 # to backtrack later) and defaults to T = <nothing>. The result is an
 # awkward error message. Either a better error message, or simply accepting the
 # call, would be preferable here.
-g(['a']) # E: Argument 1 to "g" has incompatible type List[str]; expected List[<nothing>]
+g(['a']) # E: Argument 1 to "g" has incompatible type List[str]; expected List[<nothing>] \
+# N: "List" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Sequence" instead, which is covariant
 
 h(g(['a']))
 
@@ -693,7 +695,9 @@ a = [1]
 b = ['b']
 i(a, a, b)
 i(b, a, b)
-i(a, b, b) # E: Argument 1 to "i" has incompatible type List[int]; expected List[str]
+i(a, b, b) # E: Argument 1 to "i" has incompatible type List[int]; expected List[str] \
+# N: "List" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Sequence" instead, which is covariant
 [builtins fixtures/list.pyi]
 
 [case testCallableListJoinInference]

test-data/unit/check-overloading.test

@@ -610,7 +610,9 @@ n = 1
 m = 1
 n = 'x' # E: Incompatible types in assignment (expression has type "str", variable has type "int")
 m = 'x' # E: Incompatible types in assignment (expression has type "str", variable has type "int")
-f(list_object) # E: Argument 1 to "f" has incompatible type List[object]; expected List[int]
+f(list_object) # E: Argument 1 to "f" has incompatible type List[object]; expected List[int] \
+# N: "List" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Sequence" instead, which is covariant
 [builtins fixtures/list.pyi]
 
 [case testOverlappingOverloadSignatures]

test-data/unit/check-varargs.test

@@ -592,3 +592,23 @@ class C:
     def foo(self) -> None: pass
 C().foo()
 C().foo(1)  # The decorator's return type says this should be okay
+
+
+[case testInvariantDictArgNote]
+from typing import Dict, Sequence
+def f(a: Dict[str, Sequence[int]]) -> None: pass
+a = {'a': [1, 2]}
+f(a) # E: Argument 1 to "f" has incompatible type Dict[str, List[int]]; expected Dict[str, Sequence[int]] \
+# N: "Dict" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Mapping" instead, which is covariant in the value
+[builtins fixtures/dict.pyi]
+
+
+[case testInvariantListArgNote]
+from typing import List, Union
+def f(numbers: List[Union[int, float]]) -> None: pass
+a = [1, 2]
+f(a) # E: Argument 1 to "f" has incompatible type List[int]; expected List[Union[int, float]] \
+# N: "List" is invariant --- see http://mypy.readthedocs.io/en/latest/common_issues.html#variance \
+# N: Consider using "Sequence" instead, which is covariant
+[builtins fixtures/list.pyi]