Fixed #21674 -- Deprecated the import_by_path() function in favor of import_string().

Thanks Aymeric Augustin for the suggestion and review.

3 files changed, 30 insertions, 7 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 7b5a5d7468..4b79e4696d 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -116,6 +116,9 @@ details on these changes.
 * ``django.db.backends.DatabaseValidation.validate_field`` will be removed in
   favor of the ``check_field`` method.
 
+* ``django.utils.module_loading.import_by_path`` will be removed in favor of
+  ``django.utils.module_loading.import_string``.
+
 .. _deprecation-removed-in-1.8:
 
 1.8
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 6cac9fa058..5313a1de19 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -709,22 +709,31 @@ escaping HTML.
 
 Functions for working with Python modules.
 
-.. function:: import_by_path(dotted_path, error_prefix='')
+.. function:: import_string(dotted_path)
 
-    .. versionadded:: 1.6
+    .. versionadded:: 1.7
 
     Imports a dotted module path and returns the attribute/class designated by
-    the last name in the path. Raises
-    :exc:`~django.core.exceptions.ImproperlyConfigured` if something goes
-    wrong. For example::
+    the last name in the path. Raises ``ImportError`` if the import failed. For
+    example::
 
-        from django.utils.module_loading import import_by_path
-        ImproperlyConfigured = import_by_path('django.core.exceptions.ImproperlyConfigured')
+        from django.utils.module_loading import import_string
+        ImproperlyConfigured = import_string('django.core.exceptions.ImproperlyConfigured')
 
     is equivalent to::
 
         from django.core.exceptions import ImproperlyConfigured
 
+.. function:: import_by_path(dotted_path, error_prefix='')
+
+    .. versionadded:: 1.6
+    .. deprecated:: 1.7
+       Use :meth:`~django.utils.module_loading.import_string` instead.
+
+    Imports a dotted module path and returns the attribute/class designated by
+    the last name in the path. Raises :exc:`~django.core.exceptions.ImproperlyConfigured`
+    if something goes wrong.
+
 ``django.utils.safestring``
 ===========================
 
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index f9d3a7e795..1fe2b25ecf 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -1042,6 +1042,17 @@ Features deprecated in 1.7
 respectively :mod:`logging.config` and :mod:`importlib` provided for Python
 versions prior to 2.7. They have been deprecated.
 
+``django.utils.module_loading.import_by_path``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The current :meth:`~django.utils.module_loading.import_by_path` function
+catches ``AttributeError``, ``ImportError`` and ``ValueError`` exceptions,
+and re-raises :exc:`~django.core.exceptions.ImproperlyConfigured`. Such
+exception masking makes it needlessly hard to diagnose circular import
+problems, because it makes it look like the problem comes from inside Django.
+It has been deprecated in favor of
+:meth:`~django.utils.module_loading.import_string`.
+
 ``django.utils.tzinfo``
 ~~~~~~~~~~~~~~~~~~~~~~~