Add recommendation to use string literal escaping

docs/source/common_issues.rst

@@ -533,6 +533,7 @@ Here's the above example modified to use ``MYPY``:
    def listify(arg: 'bar.BarClass') -> 'List[bar.BarClass]':
        return [arg]
 
+.. _not-generic-runtime:
 
 Using classes that are generic in stubs but not at runtime
 ----------------------------------------------------------

mypy/semanal.py

@@ -449,7 +449,7 @@ def add_builtin_aliases(self, tree: MypyFile) -> None:
                     target = self.named_type_or_none(target_name, [])
                     assert target is not None
                     # Transform List to List[Any], etc.
-                    fix_instance_types(target, self.fail)
+                    fix_instance_types(target, self.fail, self.note)
                     alias_node = TypeAlias(target, alias,
                                            line=-1, column=-1,  # there is no context
                                            no_args=True, normalized=True)
@@ -607,7 +607,7 @@ def analyze_func_def(self, defn: FuncDef) -> None:
                 # has external return type `Coroutine[Any, Any, T]`.
                 any_type = AnyType(TypeOfAny.special_form)
                 ret_type = self.named_type_or_none('typing.Coroutine',
-                    [any_type, any_type, defn.type.ret_type])
+                                                   [any_type, any_type, defn.type.ret_type])
                 assert ret_type is not None, "Internal error: typing.Coroutine not found"
                 defn.type = defn.type.copy_modified(ret_type=ret_type)
 
@@ -2489,7 +2489,7 @@ def check_and_set_up_type_alias(self, s: AssignmentStmt) -> bool:
         # so we need to replace it with non-explicit Anys.
         res = make_any_non_explicit(res)
         no_args = isinstance(res, Instance) and not res.args  # type: ignore
-        fix_instance_types(res, self.fail)
+        fix_instance_types(res, self.fail, self.note)
         if isinstance(s.rvalue, (IndexExpr, CallExpr)):  # CallExpr is for `void = type(None)`
             s.rvalue.analyzed = TypeAliasExpr(res, alias_tvars, no_args)
             s.rvalue.analyzed.line = s.line

mypy/typeanal.py

@@ -55,6 +55,11 @@
     'mypy_extensions.KwArg': ARG_STAR2,
 }  # type: Final
 
+GENERIC_STUB_NOT_AT_RUNTIME_TYPES = {
+    'queue.Queue',
+    'os.Pathlike',
+}  # type: Final
+
 
 def analyze_type_alias(node: Expression,
                        api: SemanticAnalyzerCoreInterface,
@@ -221,8 +226,13 @@ def visit_unbound_type_nonoptional(self, t: UnboundType, defining_literal: bool)
                 res = get_proper_type(res)
                 if (isinstance(res, Instance) and len(res.args) != len(res.type.type_vars) and
                         not self.defining_alias):
-                    fix_instance(res, self.fail, disallow_any=disallow_any, use_generic_error=True,
-                                 unexpanded_type=t)
+                    fix_instance(
+                        res,
+                        self.fail,
+                        self.note,
+                        disallow_any=disallow_any,
+                        use_generic_error=True,
+                        unexpanded_type=t)
                 return res
             elif isinstance(node, TypeInfo):
                 return self.analyze_type_with_type_info(node, t.args, t)
@@ -319,13 +329,14 @@ def try_analyze_special_unbound_type(self, t: UnboundType, fullname: str) -> Opt
 
     def get_omitted_any(self, typ: Type, fullname: Optional[str] = None) -> AnyType:
         disallow_any = not self.is_typeshed_stub and self.options.disallow_any_generics
-        return get_omitted_any(disallow_any, self.fail, typ, fullname)
+        return get_omitted_any(disallow_any, self.fail, self.note, typ, fullname)
 
     def analyze_type_with_type_info(self, info: TypeInfo, args: List[Type], ctx: Context) -> Type:
         """Bind unbound type when were able to find target TypeInfo.
 
         This handles simple cases like 'int', 'modname.UserClass[str]', etc.
         """
+
         if len(args) > 0 and info.fullname() == 'builtins.tuple':
             fallback = Instance(info, [AnyType(TypeOfAny.special_form)], ctx.line)
             return TupleType(self.anal_array(args), fallback, ctx.line)
@@ -337,7 +348,7 @@ def analyze_type_with_type_info(self, info: TypeInfo, args: List[Type], ctx: Con
         instance = Instance(info, self.anal_array(args), ctx.line, ctx.column)
         # Check type argument count.
         if len(instance.args) != len(info.type_vars) and not self.defining_alias:
-            fix_instance(instance, self.fail,
+            fix_instance(instance, self.fail, self.note,
                          disallow_any=self.options.disallow_any_generics and
                          not self.is_typeshed_stub)
 
@@ -891,10 +902,10 @@ def tuple_type(self, items: List[Type]) -> TupleType:
 TypeVarList = List[Tuple[str, TypeVarExpr]]
 
 # Mypyc doesn't support callback protocols yet.
-FailCallback = Callable[[str, Context, DefaultNamedArg(Optional[ErrorCode], 'code')], None]
+MsgCallback = Callable[[str, Context, DefaultNamedArg(Optional[ErrorCode], 'code')], None]
 
 
-def get_omitted_any(disallow_any: bool, fail: FailCallback,
+def get_omitted_any(disallow_any: bool, fail: MsgCallback, note: MsgCallback,
                     typ: Type, fullname: Optional[str] = None,
                     unexpanded_type: Optional[Type] = None) -> AnyType:
     if disallow_any:
@@ -907,17 +918,33 @@ def get_omitted_any(disallow_any: bool, fail: FailCallback,
             typ = unexpanded_type or typ
             type_str = typ.name if isinstance(typ, UnboundType) else format_type_bare(typ)
 
-            fail(message_registry.BARE_GENERIC.format(quote_type_string(type_str)), typ,
-                 code=codes.TYPE_ARG)
+            fail(
+                message_registry.BARE_GENERIC.format(
+                    quote_type_string(type_str)),
+                typ,
+                code=codes.TYPE_ARG)
+
+            if fullname in GENERIC_STUB_NOT_AT_RUNTIME_TYPES:
+                # Recommend `from __future__ import annotations` or to put type in quotes
+                # (string literal escaping) for classes not generic at runtime
+                note(
+                    "Subscripting classes that are not generic at runtime may require "
+                    "escaping. If you are running Python 3.7+ you can simply use "
+                    "`from __future__ import annotations`, otherwise please "
+                    "see https://mypy.readthedocs.io/"
+                    "en/latest/common_issues.html#not-generic-runtime",
+                    typ,
+                    code=codes.TYPE_ARG)
+
         any_type = AnyType(TypeOfAny.from_error, line=typ.line, column=typ.column)
     else:
         any_type = AnyType(TypeOfAny.from_omitted_generics, line=typ.line, column=typ.column)
     return any_type
 
 
-def fix_instance(t: Instance, fail: FailCallback,
+def fix_instance(t: Instance, fail: MsgCallback, note: MsgCallback,
                  disallow_any: bool, use_generic_error: bool = False,
-                 unexpanded_type: Optional[Type] = None) -> None:
+                 unexpanded_type: Optional[Type] = None,) -> None:
     """Fix a malformed instance by replacing all type arguments with Any.
 
     Also emit a suitable error if this is not due to implicit Any's.
@@ -927,7 +954,7 @@ def fix_instance(t: Instance, fail: FailCallback,
             fullname = None  # type: Optional[str]
         else:
             fullname = t.type.fullname()
-        any_type = get_omitted_any(disallow_any, fail, t, fullname, unexpanded_type)
+        any_type = get_omitted_any(disallow_any, fail, note, t, fullname, unexpanded_type)
         t.args = [any_type] * len(t.type.type_vars)
         return
     # Invalid number of type parameters.
@@ -950,7 +977,7 @@ def fix_instance(t: Instance, fail: FailCallback,
 
 
 def expand_type_alias(target: Type, alias_tvars: List[str], args: List[Type],
-                      fail: FailCallback, no_args: bool, ctx: Context, *,
+                      fail: MsgCallback, no_args: bool, ctx: Context, *,
                       unexpanded_type: Optional[Type] = None,
                       disallow_any: bool = False) -> Type:
     """Expand a (generic) type alias target following the rules outlined in TypeAlias docstring.
@@ -998,7 +1025,7 @@ def set_any_tvars(tp: Type, vars: List[str],
                   newline: int, newcolumn: int, *,
                   from_error: bool = False,
                   disallow_any: bool = False,
-                  fail: Optional[FailCallback] = None,
+                  fail: Optional[MsgCallback] = None,
                   unexpanded_type: Optional[Type] = None) -> ProperType:
     if from_error or disallow_any:
         type_of_any = TypeOfAny.from_error
@@ -1181,20 +1208,21 @@ def make_optional_type(t: Type) -> Type:
         return UnionType([t, NoneType()], t.line, t.column)
 
 
-def fix_instance_types(t: Type, fail: FailCallback) -> None:
+def fix_instance_types(t: Type, fail: MsgCallback, note: MsgCallback) -> None:
     """Recursively fix all instance types (type argument count) in a given type.
 
     For example 'Union[Dict, List[str, int]]' will be transformed into
     'Union[Dict[Any, Any], List[Any]]' in place.
     """
-    t.accept(InstanceFixer(fail))
+    t.accept(InstanceFixer(fail, note))
 
 
 class InstanceFixer(TypeTraverserVisitor):
-    def __init__(self, fail: FailCallback) -> None:
+    def __init__(self, fail: MsgCallback, note: MsgCallback) -> None:
         self.fail = fail
+        self.note = note
 
     def visit_instance(self, typ: Instance) -> None:
         super().visit_instance(typ)
         if len(typ.args) != len(typ.type.type_vars):
-            fix_instance(typ, self.fail, disallow_any=False, use_generic_error=True)
+            fix_instance(typ, self.fail, self.note, disallow_any=False, use_generic_error=True)