Support 'pyformat' style parameters in raw queries, Refs #10070

Add support for Oracle, fix an issue with the repr of RawQuerySet,
add tests and documentations. Also added a 'supports_paramstyle_pyformat'
database feature, True by default, False for SQLite.

Thanks Donald Stufft for review of documentation.

tests/raw_query/tests.py

@@ -3,7 +3,7 @@ from __future__ import absolute_import
 from datetime import date
 
 from django.db.models.query_utils import InvalidQuery
-from django.test import TestCase
+from django.test import TestCase, skipUnlessDBFeature
 
 from .models import Author, Book, Coffee, Reviewer, FriendlyAuthor
 
@@ -123,10 +123,27 @@ class RawQueryTests(TestCase):
         query = "SELECT * FROM raw_query_author WHERE first_name = %s"
         author = Author.objects.all()[2]
         params = [author.first_name]
-        results = list(Author.objects.raw(query, params=params))
+        qset = Author.objects.raw(query, params=params)
+        results = list(qset)
         self.assertProcessed(Author, results, [author])
         self.assertNoAnnotations(results)
         self.assertEqual(len(results), 1)
+        self.assertIsInstance(repr(qset), str)
+
+    @skipUnlessDBFeature('supports_paramstyle_pyformat')
+    def testPyformatParams(self):
+        """
+        Test passing optional query parameters
+        """
+        query = "SELECT * FROM raw_query_author WHERE first_name = %(first)s"
+        author = Author.objects.all()[2]
+        params = {'first': author.first_name}
+        qset = Author.objects.raw(query, params=params)
+        results = list(qset)
+        self.assertProcessed(Author, results, [author])
+        self.assertNoAnnotations(results)
+        self.assertEqual(len(results), 1)
+        self.assertIsInstance(repr(qset), str)
 
     def testManyToMany(self):
         """