django.utils.module_loading.import_by_path considered harmful

[Aymeric Augustin]

The purpose of this function is to import whatever its argument points to.

If it fails, it should raise ImportError, signalling that an import failed.

Unfortunately, it catches exceptions, including ImportErrors, and re-raises 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 becomes supremely perverse when some code in Django catches ImproperlyConfigured and things go wrong further down the line.

I understand that the original intent was to provide more frienly error messages, but I believe that ImportError is a perfectly fine and suitable exception and that replacing it with a more generic one is a net loss.

(I know I'm attacking an old dogma, but this is an easy step in the long standing "improved error reporting" project.)

[Tim Graham]

Do you see any way we can make the change backwards compatible?

[Aymeric Augustin]

Well, it's a private API...

[Aymeric Augustin]

Hum, no, it's documented. Well we could provide a replacement in Django and then deprecate it. It was only added in 1.6.

[Berker Peksag]

I've opened a pull request on GitHub: ​https://github.com/django/django/pull/2187

I borrowed the name "import_string" from the Peak project:

​http://svn.eby-sarna.com/Importing/peak/util/imports.py?view=markup

[Claude Paroz]

I think that the ImproperlyConfigured exception might make sense in some cases, especially when dotted_path is coming from a setting. What about adding a new keyword argument to import_by_path, something like: def import_by_path(dotted_path, error_prefix='', error_class=ImproperlyConfigured). Then it would be possible to overwrite the exception raised by that function, on a case-by-case basis.

[Berker Peksag]

Ah, good idea. Thanks claudep.

How about adding a new keyword argument named suppress_import_error? (somewhat similar to ​http://docs.python.org/3.4/library/contextlib.html#contextlib.suppress)

def import_by_path(dotted_path, error_prefix='', suppress_import_error=True):  # or raise_import_error=False
    # snip
    except ImportError as e:
        if not suppress_import_error:
            raise
        raise ImproperlyConfigured
    # snip

[Aymeric Augustin]

Really, I'm not eager to add an error masking API such as error_class. What's wrong with a plain ImportError? Usually it's pretty clear.

If a _caller_ can provide additional information for its specific use-case, it can catch and re-raise an exception. Exception chaining makes this less of a problem on Python 3. As long as we support Python 2, I'm -1 on catching an exception and raising another one.

I would suggest adding a new function that simply perfoms the import and doesn't handle exceptions. We would use it wherever the error_prefix argument of import_by_path isn't needed. We would make this function public and recommend it rather than import_by_path. Regarding its name, import_string sounds reasonable.

[Tim Graham]

Patch needs improvement as noted by Aymeric. Usage of the deprecated function also needs to be removed as I noted on the PR.

[Berker Peksag]

I've updated my pull request to adress Aymeric and Tim's feedbacks: ​https://github.com/django/django/pull/2187

Thanks!

[Aymeric Augustin]

The PR has been heavily reviewed by Timo and improved by Berker. I think it's ready. Thank you very much.

Timo, I'll let you do the merge, in case you want to review Berker's latest changes first.

[Tim Graham]

My only reservation is that I think it's a bit confusing to have to catch AttributeError and ValueError (besides ImportError) for all usage of import_string. Do you think catching these exceptions inside import_string and re-raising ImportError for these cases would be considered harmful?

[Aymeric Augustin]

That would be acceptable.

The biggest problem is that Django raises and catches ImproperlyConfigured too liberally. As long as we avoid that, I'm happy.

[Tim Graham <timograham@…>]

In 5d263dee304fdaf95e18d2f0619d6925984a7f02:

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

Thanks Aymeric Augustin for the suggestion and review.

[Tim Graham <timograham@…>]

In d029fafea1a1f2f257397fbcd0fa3b531e09854f:

Removed utils.module_loading.import_by_path() per deprecation timeline; refs #21674.