Add some comments

python · ilevkivskyi · Sep 13, 2023 · Sep 2, 2023 · Sep 7, 2023 · Sep 8, 2023
commit 75a9024de83ab5ef05c86162058a9ef0553b04ec
diff --git a/mypy/constraints.py b/mypy/constraints.py
@@ -744,6 +744,8 @@ def visit_instance(self, template: Instance) -> list[Constraint]:
                 tvars = mapped.type.defn.type_vars
 
                 if instance.type.has_type_var_tuple_type:
+                    # Variadic types need special handling to map each type argument to
+                    # the correct corresponding type variable.
                     assert instance.type.type_var_tuple_prefix is not None
                     assert instance.type.type_var_tuple_suffix is not None
                     prefix_len = instance.type.type_var_tuple_prefix
@@ -807,6 +809,8 @@ def visit_instance(self, template: Instance) -> list[Constraint]:
                 mapped = map_instance_to_supertype(instance, template.type)
                 tvars = template.type.defn.type_vars
                 if template.type.has_type_var_tuple_type:
+                    # Variadic types need special handling to map each type argument to
+                    # the correct corresponding type variable.
                     assert template.type.type_var_tuple_prefix is not None
                     assert template.type.type_var_tuple_suffix is not None
                     prefix_len = template.type.type_var_tuple_prefix
@@ -1034,7 +1038,7 @@ def visit_callable_type(self, template: CallableType) -> list[Constraint]:
                         res.extend(unpack_constraints)
                     else:
                         # TODO: do we need some special-casing when unpack is present in actual
-                        # but not in template?
+                        # callable but not in template callable?
                         res.extend(
                             infer_callable_arguments_constraints(template, cactual, self.direction)
                         )
@@ -1170,10 +1174,12 @@ def visit_tuple_type(self, template: TupleType) -> list[Constraint]:
                             and unpacked_type.type.fullname == "builtins.tuple"
                         )
                         res = infer_constraints(unpacked_type, actual, self.direction)
-                    assert isinstance(actual, Instance)
+                    assert isinstance(actual, Instance)  # ensured by is_varlength_tuple == True
                     for i, ti in enumerate(template.items):
                         if i == unpack_index:
+                            # This one we just handled above.
                             continue
+                        # For Tuple[T, *Ts, S] <: tuple[X, ...] infer also T <: X and S <: X.
                         res.extend(infer_constraints(ti, actual.args[0], self.direction))
                     return res
                 else:
@@ -1187,6 +1193,9 @@ def visit_tuple_type(self, template: TupleType) -> list[Constraint]:
             elif isinstance(actual, TupleType):
                 a_unpack_index = find_unpack_in_list(actual.items)
                 if a_unpack_index is not None:
+                    # The case where template tuple doesn't have an unpack, but actual tuple
+                    # has an unpack. We can infer something if actual unpack is a variadic tuple.
+                    # Tuple[T, S, U] <: tuple[X, *tuple[Y, ...], Z] => T <: X, S <: Y, U <: Z.
                     a_unpack = actual.items[a_unpack_index]
                     assert isinstance(a_unpack, UnpackType)
                     a_unpacked = get_proper_type(a_unpack.type)
@@ -1435,7 +1444,8 @@ def build_constraints_for_simple_unpack(
         common_prefix = min(template_prefix, actual_prefix)
         common_suffix = min(template_suffix, actual_suffix)
         if actual_prefix >= template_prefix and actual_suffix >= template_suffix:
-            # This is the only case where we can guarantee there will be no partial overlap.
+            # This is the only case where we can guarantee there will be no partial overlap
+            # (note however partial overlap is OK for variadic tuples, it is handled below).
             t_unpack = template_args[template_unpack]
 
     # Handle constraints from prefixes/suffixes first.
@@ -1466,6 +1476,8 @@ def build_constraints_for_simple_unpack(
         elif isinstance(tp, TypeVarTupleType):
             res.append(Constraint(tp, direction, TupleType(list(middle), tp.tuple_fallback)))
     elif actual_unpack is not None:
+        # A special case for a variadic tuple unpack, we simply infer T <: X from
+        # Tuple[..., *tuple[T, ...], ...] <: Tuple[..., *tuple[X, ...], ...].
         actual_unpack_type = actual_args[actual_unpack]
         assert isinstance(actual_unpack_type, UnpackType)
         a_unpacked = get_proper_type(actual_unpack_type.type)

diff --git a/mypy/erasetype.py b/mypy/erasetype.py
@@ -79,6 +79,7 @@ def visit_deleted_type(self, t: DeletedType) -> ProperType:
     def visit_instance(self, t: Instance) -> ProperType:
         args: list[Type] = []
         for tv in t.type.defn.type_vars:
+            # Valid erasure for *Ts is *tuple[Any, ...], not just Any.
             if isinstance(tv, TypeVarTupleType):
                 args.append(
                     tv.tuple_fallback.copy_modified(args=[AnyType(TypeOfAny.special_form)])

diff --git a/mypy/join.py b/mypy/join.py
@@ -70,6 +70,9 @@ def join_instances(self, t: Instance, s: Instance) -> ProperType:
             # N.B: We use zip instead of indexing because the lengths might have
             # mismatches during daemon reprocessing.
             if t.type.has_type_var_tuple_type:
+                # We handle joins of variadic instances by simply creating correct mapping
+                # for type arguments and compute the individual joins same as for regular
+                # instances. All the heavy lifting is done in the join of tuple types.
                 assert s.type.type_var_tuple_prefix is not None
                 assert s.type.type_var_tuple_suffix is not None
                 prefix = s.type.type_var_tuple_prefix
@@ -112,6 +115,9 @@ def join_instances(self, t: Instance, s: Instance) -> ProperType:
                         new_type = join_types(ta, sa, self)
                 elif isinstance(type_var, TypeVarTupleType):
                     new_type = get_proper_type(join_types(ta, sa, self))
+                    # Put the joined arguments back into instance in the normal form:
+                    #   a) Tuple[X, Y, Z] -> [X, Y, Z]
+                    #   b) tuple[X, ...] -> [*tuple[X, ...]]
                     if isinstance(new_type, Instance):
                         assert new_type.type.fullname == "builtins.tuple"
                         new_type = UnpackType(new_type)
@@ -467,6 +473,12 @@ def visit_overloaded(self, t: Overloaded) -> ProperType:
         return join_types(t.fallback, s)
 
     def join_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
+        """Join two tuple types while handling variadic entries.
+
+        This is surprisingly tricky, and we don't handle some tricky corner cases.
+        Most of the trickiness comes from the variadic tuple items like *tuple[X, ...]
+        since they can have arbitrary partial overlaps (while *Ts can't be split).
+        """
         s_unpack_index = find_unpack_in_list(s.items)
         t_unpack_index = find_unpack_in_list(t.items)
         if s_unpack_index is None and t_unpack_index is None:
@@ -477,13 +489,17 @@ def join_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
                 return items
             return None
         if s_unpack_index is not None and t_unpack_index is not None:
+            # The most complex case: both tuples have an upack item.
             s_unpack = s.items[s_unpack_index]
             assert isinstance(s_unpack, UnpackType)
             s_unpacked = get_proper_type(s_unpack.type)
             t_unpack = t.items[t_unpack_index]
             assert isinstance(t_unpack, UnpackType)
             t_unpacked = get_proper_type(t_unpack.type)
             if s.length() == t.length() and s_unpack_index == t_unpack_index:
+                # We can handle a case where arity is perfectly aligned, e.g.
+                # join(Tuple[X1, *tuple[Y1, ...], Z1], Tuple[X2, *tuple[Y2, ...], Z2]).
+                # We can essentially perform the join elementwise.
                 prefix_len = t_unpack_index
                 suffix_len = t.length() - t_unpack_index - 1
                 items = []
@@ -512,6 +528,9 @@ def join_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
                     for si, ti in zip(s.items[-suffix_len:], t.items[-suffix_len:]):
                         items.append(join_types(si, ti))
             if s.length() == 1 or t.length() == 1:
+                # Another case we can handle is when one of tuple is purely variadic
+                # (i.e. a non-normalized form of tuple[X, ...]), in this case the join
+                # will be again purely variadic.
                 if not (isinstance(s_unpacked, Instance) and isinstance(t_unpacked, Instance)):
                     return None
                 assert s_unpacked.type.fullname == "builtins.tuple"
@@ -533,12 +552,15 @@ def join_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
             variadic = t
             unpack_index = t_unpack_index
             fixed = s
+        # Case where one tuple has variadic item and the other one doesn't. The join will
+        # be variadic, since fixed tuple is a subtype of variadic, but not vice versa.
         unpack = variadic.items[unpack_index]
         assert isinstance(unpack, UnpackType)
         unpacked = get_proper_type(unpack.type)
         if not isinstance(unpacked, Instance):
             return None
         if fixed.length() < variadic.length() - 1:
+            # There are no non-trivial types that are supertype of both.
            return None
         prefix_len = unpack_index
         suffix_len = variadic.length() - prefix_len - 1

diff --git a/mypy/meet.py b/mypy/meet.py
@@ -724,6 +724,9 @@ def visit_instance(self, t: Instance) -> ProperType:
                     # N.B: We use zip instead of indexing because the lengths might have
                     # mismatches during daemon reprocessing.
                     if t.type.has_type_var_tuple_type:
+                        # We handle meet of variadic instances by simply creating correct mapping
+                        # for type arguments and compute the individual meets same as for regular
+                        # instances. All the heavy lifting is done in the meet of tuple types.
                         s = self.s
                         assert s.type.type_var_tuple_prefix is not None
                         assert s.type.type_var_tuple_suffix is not None
@@ -746,6 +749,8 @@ def visit_instance(self, t: Instance) -> ProperType:
                     for ta, sa, tv in zip(t_args, s_args, t.type.defn.type_vars):
                         meet = self.meet(ta, sa)
                         if isinstance(tv, TypeVarTupleType):
+                            # Correctly unpack possible outcomes of meets of tuples: it can be
+                            # either another tuple type or Never (normalized as *tuple[Never, ...])
                             if isinstance(meet, TupleType):
                                 args.extend(meet.items)
                                 continue
@@ -842,6 +847,14 @@ def visit_overloaded(self, t: Overloaded) -> ProperType:
         return meet_types(t.fallback, s)
 
     def meet_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
+        """Meet two tuple types while handling variadic entries.
+
+        This is surprisingly tricky, and we don't handle some tricky corner cases.
+        Most of the trickiness comes from the variadic tuple items like *tuple[X, ...]
+        since they can have arbitrary partial overlaps (while *Ts can't be split). This
+        function is roughly a mirror of join_tuples() w.r.t. to the fact that fixed
+        tuples are subtypes of variadic ones but not vice versa.
+        """
         s_unpack_index = find_unpack_in_list(s.items)
         t_unpack_index = find_unpack_in_list(t.items)
         if s_unpack_index is None and t_unpack_index is None:
@@ -852,7 +865,12 @@ def meet_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
                 return items
             return None
         if s_unpack_index is not None and t_unpack_index is not None:
-            # TODO: handle more cases (like strictly shorter prefix/suffix).
+            # The only simple case we can handle if both tuples are variadic
+            # is when they are purely variadic. Other cases are tricky because
+            # a variadic item is effectively a union of tuples of all length, thus
+            # potentially causing overlap between a suffix in `s` and a prefix
+            # in `t` (see how this is handled in is_subtype() for details).
+            # TODO: handle more cases (like when both prefix/suffix are strictly shorter).
             if s.length() == 1 and t.length() == 1:
                 s_unpack = s.items[0]
                 assert isinstance(s_unpack, UnpackType)
@@ -876,6 +894,7 @@ def meet_tuples(self, s: TupleType, t: TupleType) -> list[Type] | None:
             variadic = t
             unpack_index = t_unpack_index
             fixed = s
+        # If one tuple is variadic one, and the other one is fixed, the meet will be fixed.
         unpack = variadic.items[unpack_index]
         assert isinstance(unpack, UnpackType)
         unpacked = get_proper_type(unpack.type)
@@ -913,6 +932,8 @@ def visit_tuple_type(self, t: TupleType) -> ProperType:
                 # A named tuple that inherits from a normal class
                 return t
             elif self.s.type.has_type_var_tuple_type and is_subtype(t, self.s):
+                # This is a bit ad-hoc but more principled handling is tricky, and this
+                # special case is important for type narrowing in binder to work.
                 return t
         return self.default(self.s)
 

diff --git a/mypy/semanal_typeargs.py b/mypy/semanal_typeargs.py
@@ -207,7 +207,8 @@ def visit_unpack_type(self, typ: UnpackType) -> None:
             return
         if isinstance(proper_type, TypeVarTupleType):
             return
-        # TODO: this should probably be .has_base("builtins.tuple"), also elsewhere.
+        # TODO: this should probably be .has_base("builtins.tuple"), also elsewhere. This is
+      
10000
  # tricky however, since this needs map_instance_to_supertype() available in many places.
         if isinstance(proper_type, Instance) and proper_type.type.fullname == "builtins.tuple":
             return
         if not isinstance(proper_type, (UnboundType, AnyType)):

diff --git a/mypy/subtypes.py b/mypy/subtypes.py
@@ -446,18 +446,24 @@ def visit_instance(self, left: Instance) -> bool:
             return self._is_subtype(left, mypy.typeops.tuple_fallback(right))
         if isinstance(right, TupleType):
             if len(right.items) == 1:
-                # Non-normalized Tuple type (may be left after semantic analysis).
+                # Non-normalized Tuple type (may be left after semantic analysis
+                # because semanal_typearg visitor is not a type translator).
                 item = right.items[0]
                 if isinstance(item, UnpackType):
                     unpacked = get_proper_type(item.type)
                     if isinstance(unpacked, Instance):
                         return self._is_subtype(left, unpacked)
             if len(left.args) == 1 and isinstance(left.args[0], UnpackType):
+                # Special case to consider Foo[*tuple[Any, ...]] (i.e. bare Foo) a
+                # subtype of Foo[<whatever>], when Foo is user defined variadic tuple type.
+                # TODO: be sure we handle Bar <: Foo[*tuple[Any, ...]] <: Foo[<whatever>].
                 unpacked = get_proper_type(left.args[0].type)
                 if isinstance(unpacked, Instance):
                     assert unpacked.type.fullname == "builtins.tuple"
                     if isinstance(get_proper_type(unpacked.args[0]), AnyType):
                         return self._is_subtype(left, mypy.typeops.tuple_fallback(right))
+            # TODO: we need a special case similar to above to consider (something that maps to)
+            # tuple[Any, ...] a subtype of Tuple[<whatever>].
             return False
         if isinstance(right, Instance):
             if type_state.is_cached_subtype_check(self._subtype_kind, left, right):
@@ -498,6 +504,8 @@ def visit_instance(self, left: Instance) -> bool:
                     t = erased
                 nominal = True
                 if right.type.has_type_var_tuple_type:
+                    # For variadic instances we simply find the correct type argument mappings,
+                    # all the heavy lifting is done by the tuple subtyping.
                     assert right.type.type_var_tuple_prefix is not None
                     assert right.type.type_var_tuple_suffix is not None
                     prefix = right.type.type_var_tuple_prefix
@@ -734,20 +742,32 @@ def visit_tuple_type(self, left: TupleType) -> bool:
             return False
 
     def variadic_tuple_subtype(self, left: TupleType, right: TupleType) -> bool:
+        """Check subtyping between two potentially variadic tuples.
+
+        Most non-trivial cases here are due to variadic unpacks like *tuple[X, ...],
+        we handle such unpacks as infinite unions Tuple[()] | Tuple[X] | Tuple[X, X] | ...
+
+        Note: the cases where right is fixed or has *Ts unpack should be handled
+        by the caller.
+        """
         right_unpack_index = find_unpack_in_list(right.items)
         if right_unpack_index is None:
+            # This case should be handled by the caller.
             return False
         right_unpack = right.items[right_unpack_index]
         assert isinstance(right_unpack, UnpackType)
         right_unpacked = get_proper_type(right_unpack.type)
         if not isinstance(right_unpacked, Instance):
+            # This case should be handled by the caller.
             return False
         assert right_unpacked.type.fullname == "builtins.tuple"
         right_item = right_unpacked.args[0]
         right_prefix = right_unpack_index
         right_suffix = len(right.items) - right_prefix - 1
         left_unpack_index = find_unpack_in_list(left.items)
         if left_unpack_index is None:
+            # Simple case: left is fixed, simply find correct mapping to the right
+            # (effectively selecting item with matching length from an infinite union).
             if len(left.items) < right_prefix + right_suffix:
                 return False
             prefix, middle, suffix = split_with_prefix_and_suffix(
@@ -764,14 +784,22 @@ def variadic_tuple_subtype(self, left: TupleType, right: TupleType) -> bool:
             return all(self._is_subtype(li, right_item) for li in middle)
         else:
             if len(left.items) < len(right.items):
+                # There are some items on the left that will never have a matching length
+                # on the right.
                 return False
             left_unpack = left.items[left_unpack_index]
             assert isinstance(left_unpack, UnpackType)
             left_unpacked = get_proper_type(left_unpack.type)
             if not isinstance(left_unpacked, Instance):
+                # *Ts unpacks can't be split.
                 return False
             assert left_unpacked.type.fullname == "builtins.tuple"
             left_item = left_unpacked.args[0]
+
+            # The most tricky case with two variadic unpacks we handle similar to union
+            # subtyping: *each* item on the left, must be a subtype of *some* item on the right.
+            # For this we first check the "asymptotic case", i.e. that both unpacks a subtypes,
+            # and then check subtyping for all finite overlaps.
             if not self._is_subtype(left_item, right_item):
                 return False
             left_prefix = left_unpack_index