Add some info about get_proper_type() (#7950)

Author: ilevkivskyi

misc/proper_plugin.py

@@ -42,6 +42,8 @@ def isinstance_proper_hook(ctx: FunctionContext) -> Type:
                 return ctx.default_return_type
             ctx.api.fail('Never apply isinstance() to unexpanded types;'
                          ' use mypy.types.get_proper_type() first', ctx.context)
+            ctx.api.note('If you pass on the original type'  # type: ignore[attr-defined]
+                         ' after the check, always use its unexpanded version', ctx.context)
     return ctx.default_return_type
 
 

mypy/types.py

@@ -1896,6 +1896,14 @@ def get_proper_type(typ: Type) -> ProperType: ...
 
 
 def get_proper_type(typ: Optional[Type]) -> Optional[ProperType]:
+    """Get the expansion of a type alias type.
+
+    If the type is already a proper type, this is a no-op. Use this function
+    wherever a decision is made on a call like e.g. 'if isinstance(typ, UnionType): ...',
+    because 'typ' in this case may be an alias to union. Note: if after making the decision
+    on the isinstance() call you pass on the original type (and not one of its components)
+    it is recommended to *always* pass on the unexpanded alias.
+    """
     if typ is None:
         return None
     while isinstance(typ, TypeAliasType):