Following the call to test the MR branch, I followed the steps that a
newbie might do: check out MR and start going through tutorial1. Almost
immediately I ran into a hitch with a misleading error message.
In settings.py set DATABASE_ENGINE='sqlite3' and run 'python manage.py
syncdb'. If you don't happen to have pysqlite2 installed, you get an
error message that says DATABASE_ENGINE is incorrect and might be
misspelled. The error results in 11 lines of text on the screen,
including a traceback. The traceback in this case is _not_ helpful
because it hides the real error - hidden somewhere in the text is a
message 'No module named pysqlite2'. At first I thought, why is it
looking for pysqlite2 when I said I want sqlite3? must not have read my
settings file correctly and used some default older version of sqlite.
If you're not a newbie or have used sqlite3 with python before, you
probably have pysqlite2 installed already and would never see this
message, or you might recognize the name and know how to find it and
install it. If you dive in to debug it, you find the answer inside a
comment in the sqlite3 backend code.
(I happened to be using a linux system on which sqlite3 was already
installed).
If the error is really that pysqlite2 is not installed, it should not
print a traceback, should not tell the user that DATABASE_ENGINE is
misspelled, and should instead specifically instruct the user to
install pysqlite2.
For example, in db/backends/sqlite3/base.py the import pysqlite2 could
be inside a try/catch block and raise MissingDependencyException with
the message "pysqlite2 is not in the PYTHONPATH. The sqlite3 backend
requires the pysqlite2 driver that can be downloaded from pysqlite.org"
[The name of the existing exception 'ImproperlyConfigured?' is
misleading.]
In db/init.py, catch MissingDependencyException and print the
message. This should avoid the misleading error message about your
database engine name being misspelled.
In docs/tutorial1.txt where the user is first instructed to
edit settings.py, it would be helpful to explicitly state that the
sqlite3 backend requires installation of pysqlite2 from pysqlite.org.
Alternately, a comment could be added to settings.py where it would be
visible to people who didn't arrive there from the tutorial. These
documentation changes are less important if the error message is
cleaned up, since the user will be quickly steered toward the solution.
However, it may still be a good idea to add this documentation if you
want a newbie to have a flawless "Hello World" experience.
