Fix migrations.RunSQL stubs (#1803)

* Add test from docs

* Relax str constraint

* Add a typealis and a test case

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]