Proposal: errors with URLs in them

[Andy McKay]

One of my favourite errors in Python is this one:

File "settings.py", line 2
SyntaxError: Non-ASCII character '\xce' in file settings.py on line 2,
but no encoding declared; see http://www.python.org/peps/pep-0263.html for details

This is when you've declared a non-ASCII character without the encoding declared. In fact I don't even bother to look up the syntax to make it work, it's easier to put the text in, let it fail and then let python tell me the URL to the syntax.

There are common errors that I see being made in putting together Django applications and I'd like to see if we can provide more helpful errors to the user. There are obviously lots of places we can't do this, but I think in some areas we can. One example from #django last night that i've seen a few times is leaving a comma out in INSTALLED_APPS so you have:

INSTALLED_APPS = (
'django.contrib.auth'
'django.contrib.contenttypes',
...)

This leads to:

Error: No module named authdjango.contrib.contenttypes

Which is a pretty confusing error. Supposing this said:

Error: No module named authdjango.contrib.contenttypes. See http://djangoproject.com/errors/32 for help.

And that page gave lots of detail:

This means Django can't find an app from installed apps. This could be because:

- You've misspelled it

- You've missed a comma in INSTALLED_APPS

...

We've already got a page that seems similar to this at:

http://code.djangoproject.com/wiki/BetterErrorMessages

Ideally such errors would be part of the documentation.

This is of course won't be possible for all errors or all parts of Django, but would work for some of the more common errors that crop up regularly. Would this be a course worth pursuing?
--
Andy McKay, @clearwind
http://clearwind.ca/djangoski

[Russell Keith-Magee]

I'd say yes - with some caveats.

Firstly, we need to be careful about casting too wide a net in
catching errors. We don't want to accidentally catch errors and give a
solution that is wrong. We also don't want to hide useful errors under
a 'helpful' blanket (e.g., the way that Django sometimes masks import
errors). If we're going to introduce specific error messages, we need
to make sure they actually refer to a specific problem.

Secondly, we have the problem of getting people to actually read the
error message. I completely agree with you that the Python PEP-0263
error is a great example; however, we have two very good
counterexamples in our own code:

- MySQLdb doesn't appear to be installed

- Accessor for field 'foo' clashes with field "Bar.whiz'. Add a
related_name argument to the definition for foo'

I've lost count of the number of people that have posted to
Django-users, dumped those error messages and said "What do I do?".

I'm always hesitant to blame the user for problems like this. If the
user isn't following instructions, maybe the instructions aren't clear
enough. Maybe the error message in question is just too pithy --
perhaps if they redirected to a single page in the docs that gave a
verbose explanation of the problem (including examples and workarounds
where appropriate), we might be able to avoid a few of these
questions.
However, in the words of Cool Hand Luke: "some folks, you just can't reach". :-)

So - if you can produce a patch that demonstrates 5-10 examples of
patterns that would benefit from an elaborate error message, I
certainly think that patch could find it's way into trunk.

More broadly, *any* patch that improves error handling is most
welcome. Looking at the wiki page you reference, many of those errors
are simple cases of an Attribute/Value error that should be caught and
rethrown with a more meaningful error. Even if we don't put an
explanatory page in the docs, those errors should be improved.

Yours,
Russ Magee %-)

[Andy McKay]

On 2010-01-21, at 3:53 PM, Russell Keith-Magee wrote:

> On Fri, Jan 22, 2010 at 1:35 AM, Andy McKay <an...@clearwind.ca> wrote:
>>
>> This is of course won't be possible for all errors or all parts of Django, but would work for some of the more common errors that crop up regularly. Would this be a course worth pursuing?
>
> I'd say yes - with some caveats.
>
> Firstly, we need to be careful about casting too wide a net in
> catching errors. We don't want to accidentally catch errors and give a
> solution that is wrong. We also don't want to hide useful errors under
> a 'helpful' blanket (e.g., the way that Django sometimes masks import
> errors). If we're going to introduce specific error messages, we need
> to make sure they actually refer to a specific problem.

Absolutely, this should be used sparingly. It just can be a bit frustrating because some of the start up or import errors can be a bit silent or cryptic.

> I'm always hesitant to blame the user for problems like this. If the
> user isn't following instructions, maybe the instructions aren't clear
> enough. Maybe the error message in question is just too pithy --
> perhaps if they redirected to a single page in the docs that gave a
> verbose explanation of the problem (including examples and workarounds
> where appropriate), we might be able to avoid a few of these
> questions.
> However, in the words of Cool Hand Luke: "some folks, you just can't reach". :-)

I think it might help, you are right and we can't save everyone. But I think if we can document the error properly and in some detail somewhere, we'll at least feel good that we've done everything we can.

> So - if you can produce a patch that demonstrates 5-10 examples of
> patterns that would benefit from an elaborate error message, I
> certainly think that patch could find it's way into trunk.

Rightio, we'll give it a try a for a few and see how it lookis.

Thanks for the