Fixed #22401 -- Deprecated regular expression parsing of initial SQL in favor of installing sqlparse.

4 files changed, 25 insertions, 0 deletions

diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt
index d003db6497..fc59132ccb 100644
--- a/docs/howto/initial-data.txt
+++ b/docs/howto/initial-data.txt
@@ -103,6 +103,14 @@ directories.
 Providing initial SQL data
 ==========================
 
+.. deprecated:: 1.8
+
+    Historically this functionality has used regular expression parsing of the
+    initial SQL which is a bit buggy. This parsing is now deprecated in favor
+    of installing `sqlparse <https://pypi.python.org/pypi/sqlparse>`_; doing so
+    will be required for this functionality in Django 2.0. You can install it
+    using ``pip install sqlparse``.
+
 Django provides a hook for passing the database arbitrary SQL that's executed
 just after the CREATE TABLE statements when you run :djadmin:`migrate`. You can
 use this hook to populate default records, or you could also create SQL
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index bcee13f6d3..fcf7c0549f 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -166,6 +166,7 @@ dependencies:
 *  memcached_, plus a :ref:`supported Python binding <memcached>`
 *  gettext_ (:ref:`gettext_on_windows`)
 *  selenium_
+*  sqlparse_
 
 You can find these dependencies in `pip requirements files`_ inside the
 ``tests/requirements`` directory of the Django source tree and install them
@@ -197,6 +198,7 @@ associated tests will be skipped.
 .. _memcached: http://memcached.org/
 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
 .. _selenium: https://pypi.python.org/pypi/selenium
+.. _sqlparse: https://pypi.python.org/pypi/sqlparse
 .. _pip requirements files: http://www.pip-installer.org/en/latest/cookbook.html#requirements-files
 
 Code coverage
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index a0d3b8a80c..7d440c428a 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -25,6 +25,9 @@ about each item can often be found in the release notes of two versions prior.
 * Using an incorrect count of unpacked values in the ``for`` template tag
   will raise an exception rather than fail silently.
 
+* The regular expression parsing of SQL initial data will be removed and
+  ``sqlparse`` will be required for the feature.
+
 .. _deprecation-removed-in-1.9:
 
 1.9
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 79b7168030..977b166880 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -128,6 +128,9 @@ Management Commands
 * :djadmin:`dumpdata` now has the option :djadminopt:`--output` which allows
   specifying the file to which the serialized data is written.
 
+* :ref:`initial-sql` now works better if the `sqlparse
+  <https://pypi.python.org/pypi/sqlparse>`_ Python library is installed.
+
 Models
 ^^^^^^
 
@@ -276,3 +279,12 @@ Using an incorrect count of unpacked values in the :ttag:`for` template tag
 
 Using an incorrect count of unpacked values in :ttag:`for` tag will raise an
 exception rather than fail silently in Django 2.0.
+
+Regular expression parsing of initial SQL
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The somewhat buggy regular expression logic used for parsing :ref:`SQL initial
+data <initial-sql>` has been deprecated. Install `sqlparse
+<https://pypi.python.org/pypi/sqlparse>`_ if you wish to use this feature.
+Doing so will be required in Django 2.0 when the regular expression logic is
+removed.