Fix migrations.RunSQL stubs (typeddjango#1803)

* Add test from docs

* Relax str constraint

* Add a typealis and a test case

Author: UnknownPlatypus

django-stubs/db/migrations/operations/special.pyi

@@ -4,9 +4,12 @@ from typing import Any, Literal, Protocol
 from django.db.backends.base.schema import BaseDatabaseSchemaEditor
 from django.db.migrations.state import StateApps
 from django.utils.datastructures import _ListOrTuple
+from typing_extensions import TypeAlias
 
 from .base import Operation
 
+_SqlOperations: TypeAlias = str | _ListOrTuple[str | tuple[str, dict[str, Any] | _ListOrTuple[Any] | None]]
+
 class SeparateDatabaseAndState(Operation):
     database_operations: Sequence[Operation]
     state_operations: Sequence[Operation]
@@ -17,14 +20,14 @@ class SeparateDatabaseAndState(Operation):
 
 class RunSQL(Operation):
     noop: Literal[""]
-    sql: str | _ListOrTuple[str | tuple[str, dict[str, Any] | _ListOrTuple[str] | None]]
-    reverse_sql: str | None | _ListOrTuple[str | tuple[str, dict[str, Any] | _ListOrTuple[str] | None]]
+    sql: _SqlOperations
+    reverse_sql: _SqlOperations | None
     state_operations: Sequence[Operation]
     hints: Mapping[str, Any]
     def __init__(
         self,
-        sql: str | _ListOrTuple[str | tuple[str, dict[str, Any] | _ListOrTuple[str] | None]],
-        reverse_sql: str | None | _ListOrTuple[str | tuple[str, dict[str, Any] | _ListOrTuple[str] | None]] = ...,
+        sql: _SqlOperations,
+        reverse_sql: _SqlOperations | None = ...,
         state_operations: Sequence[Operation] | None = ...,
         hints: Mapping[str, Any] | None = ...,
         elidable: bool = ...,

tests/typecheck/db/migrations/test_operations.yml

@@ -16,5 +16,16 @@
 
      RunSQL(sql=["SOME SQLS", ("SOME SQLS %s, %s", ["PARAM", "ANOTHER PARAM"])], reverse_sql=["SOME SQLS", ("SOME SQLS %s, %s", ["PARAM", "ANOTHER PARAM"])])
 
-     RunSQL(sql=("SOME SQL", {}))                                                 # E: Argument "sql" to "RunSQL" has incompatible type "Tuple[str, Dict[<nothing>, <nothing>]]"; expected "Union[str, Union[List[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[str], Tuple[str, ...], Tuple[()]], None]]]], Tuple[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[str], Tuple[str, ...], Tuple[()]], None]]], ...], Tuple[()]]]"  [arg-type]
-     RunSQL(sql=["SOME SQLS", ("SOME SQLS %s, %s", [object(), "ANOTHER PARAM"])]) # E: List item 0 has incompatible type "object"; expected "str"  [list-item]
+     RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")
+     RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])
+     RunSQL([("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])])
+
+     query = "UPDATE posts SET category = %s WHERE category = ANY(%s);"
+     RunSQL([(query, ['new category', ['retired category', 'another retired category']])])
+
+     RunSQL(sql=["SOME SQLS", ("SOME SQLS %s, %s", [object(), "ANOTHER PARAM"])])
+
+     RunSQL(sql=("SOME SQL", {}))  # E: Argument "sql" to "RunSQL" has incompatible type "Tuple[str, Dict[<nothing>, <nothing>]]"; expected "Union[str, Union[List[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]]], Tuple[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]], ...], Tuple[()]]]"  [arg-type]
+     RunSQL(sql=("SOME SQL", 1))   # E: Argument "sql" to "RunSQL" has incompatible type "Tuple[str, int]"; expected "Union[str, Union[List[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]]], Tuple[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]], ...], Tuple[()]]]"  [arg-type]
+     RunSQL(sql=("SOME SQL", None))  # E: Argument "sql" to "RunSQL" has incompatible type "Tuple[str, None]"; expected "Union[str, Union[List[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]]], Tuple[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]], ...], Tuple[()]]]"  [arg-type]
+     RunSQL(sql=("SOME SQLS %(VAL)s", {1: "FOO"}))  # E: Argument "sql" to "RunSQL" has incompatible type "Tuple[str, Dict[int, str]]"; expected "Union[str, Union[List[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]]], Tuple[Union[str, Tuple[str, Union[Dict[str, Any], Union[List[Any], Tuple[Any, ...], Tuple[()]], None]]], ...], Tuple[()]]]"  [arg-type]