Fixed #30988 -- Deprecated the InvalidQuery exception.

It was barely documented without pointers at its defining location and
was abused to prevent misuse of the QuerySet field deferring feature.

tests/defer/tests.py

@@ -1,4 +1,4 @@
-from django.db.models.query_utils import InvalidQuery
+from django.core.exceptions import FieldError
 from django.test import TestCase
 
 from .models import (
@@ -113,7 +113,7 @@ class DeferTests(AssertionMixin, TestCase):
             'Field Primary.related cannot be both deferred and traversed '
             'using select_related at the same time.'
         )
-        with self.assertRaisesMessage(InvalidQuery, msg):
+        with self.assertRaisesMessage(FieldError, msg):
             Primary.objects.defer("related").select_related("related")[0]
 
     def test_only_select_related_raises_invalid_query(self):
@@ -121,7 +121,7 @@ class DeferTests(AssertionMixin, TestCase):
             'Field Primary.related cannot be both deferred and traversed using '
             'select_related at the same time.'
         )
-        with self.assertRaisesMessage(InvalidQuery, msg):
+        with self.assertRaisesMessage(FieldError, msg):
             Primary.objects.only("name").select_related("related")[0]
 
     def test_defer_foreign_keys_are_deferred_and_not_traversed(self):

tests/queries/test_deprecation.py

@@ -0,0 +1,30 @@
+from contextlib import contextmanager
+
+from django.core.exceptions import FieldDoesNotExist, FieldError
+from django.db.models.query_utils import InvalidQuery
+from django.test import SimpleTestCase
+from django.utils.deprecation import RemovedInDjango40Warning
+
+
+class InvalidQueryTests(SimpleTestCase):
+    @contextmanager
+    def assert_warns(self):
+        msg = (
+            'The InvalidQuery exception class is deprecated. Use '
+            'FieldDoesNotExist or FieldError instead.'
+        )
+        with self.assertWarnsMessage(RemovedInDjango40Warning, msg):
+            yield
+
+    def test_type(self):
+        self.assertIsInstance(InvalidQuery(), InvalidQuery)
+
+    def test_isinstance(self):
+        for exception in (FieldError, FieldDoesNotExist):
+            with self.assert_warns(), self.subTest(exception.__name__):
+                self.assertIsInstance(exception(), InvalidQuery)
+
+    def test_issubclass(self):
+        for exception in (FieldError, FieldDoesNotExist, InvalidQuery):
+            with self.assert_warns(), self.subTest(exception.__name__):
+                self.assertIs(issubclass(exception, InvalidQuery), True)

tests/raw_query/tests.py

@@ -1,8 +1,8 @@
 from datetime import date
 from decimal import Decimal
 
+from django.core.exceptions import FieldDoesNotExist
 from django.db.models.query import RawQuerySet
-from django.db.models.query_utils import InvalidQuery
 from django.test import TestCase, skipUnlessDBFeature
 
 from .models import (
@@ -235,7 +235,8 @@ class RawQueryTests(TestCase):
 
     def test_missing_fields_without_PK(self):
         query = "SELECT first_name, dob FROM raw_query_author"
-        with self.assertRaisesMessage(InvalidQuery, 'Raw query must include the primary key'):
+        msg = 'Raw query must include the primary key'
+        with self.assertRaisesMessage(FieldDoesNotExist, msg):
             list(Author.objects.raw(query))
 
     def test_annotations(self):