root/django/branches/new-admin/docs/faq.txt

==========
Django FAQ
==========

General questions
=================

Why does this project exist?
----------------------------

Django grew from a very practical need: in our fast-paced newsroom, we often
have only a matter of hours to take a complicated Web application from
concept to public launch.  Django was designed to not only allow us to
build Web applications quickly, but to allow us to build them right.

Django would not be possible without a whole host of open-source projects --
`Apache`_, `Python`_, and `PostgreSQL`_ to name a few -- and we're thrilled to be
able to give something back to the open-source community.

.. _Apache: http://httpd.apache.org/
.. _Python: http://www.python.org/
.. _PostgreSQL: http://www.postgresql.org/

What does "Django" mean, and how do you pronounce it?
-----------------------------------------------------

Django is named after `Django Reinhardt`_, a gypsy jazz guitarist from the 1930s
to early 1950s. To this day, he's considered one of the best guitarists of all time.

Listen to his music. You'll like it.

According to Wikipedia_, "Django is pronounced **zhane**-go (with a long 'a')."

.. _Django Reinhardt: http://en.wikipedia.org/wiki/Django_Reinhardt
.. _Wikipedia: http://en.wikipedia.org/wiki/Django_Reinhardt

Is Django stable?
-----------------

We've been using Django for almost two years. Sites built on Django have
weathered traffic spikes of over one million hits an hour, and at least
one Slashdotting. Yes, it's quite stable.

Does Django scale?
------------------

Yes. Compared to development time, hardware is cheap, and so Django is
designed to take advantage of as much hardware as you can throw at it.
Django ships with clean separation of the database layer from the
application layer and a simple-yet-powerful `cache framework`_.

.. _`cache framework`: http://www.djangoproject.com/documentation/cache/

Who's behind this?
------------------

Django was developed at `World Online`_, the Web department of a newspaper in
Lawrence, Kansas, USA.

`Adrian Holovaty`_
    Adrian is a Web developer with a background in journalism. He was lead
    developer at World Online for 2.5 years, during which time Django was
    developed and implemented on World Online's sites. Now he's editor of
    editorial innovations at washingtonpost.com, and he continues to oversee
    Django development. He likes playing guitar (Django Reinhardt style) and
    hacking on side projects such as `chicagocrime.org`_. He lives in Chicago.

    On IRC, Adrian goes by ``adrian_h``.

`Simon Willison`_
    Simon is a well-respected Web developer from England. He had a one-year
    internship at World Online, during which time he and Adrian developed
    Django from scratch. He's enthusiastic, he's passionate about best
    practices in Web development, and he really likes squirrels. Probably to a
    fault. He went back to university to finish his degree and is poised to
    continue doing big, exciting things on the Web. He lives in England.

    On IRC, Simon goes by ``SimonW``.

`Jacob Kaplan-Moss`_
    Jacob is a whipper-snapper from California who spends equal time coding and
    cooking. He does Web development for World Online and actively hacks on
    various cool side projects. He's contributed to the Python-ObjC bindings and
    was the first guy to figure out how to write Tivo apps in Python. Lately
    he's been messing with Python on the PSP. He lives in Lawrence, Kansas.

    On IRC, Jacob goes by ``jacobkm``.

`Wilson Miner`_
    Wilson's design-fu makes us all look like rock stars. When not sneaking
    into apartment complex swimming pools, he's the Commercial Development
    Director for World Online, which means he makes the money that pays all our
    paychecks. He lives in Lawrence, Kansas.

    On IRC, Wilson goes by ``wilsonian``.

.. _`World Online`: http://code.djangoproject.com/wiki/WorldOnline
.. _`Adrian Holovaty`: http://www.holovaty.com/
.. _`chicagocrime.org`: http://www.chicagocrime.org/
.. _`Simon Willison`: http://simon.incutio.com/
.. _`simon.incutio.com`: http://simon.incutio.com/
.. _`Jacob Kaplan-Moss`: http://www.jacobian.org/
.. _`Wilson Miner`: http://www.wilsonminer.com/live/

Django appears to be a MVC framework, but you call the Controller the "view", and the View the "template". How come you don't use the standard names?
-----------------------------------------------------------------------------------------------------------------------------------------------------

That's because Django isn't strictly a MVC framework. We don't really believe in
any capital-M Methodologies; we do what "feels" right. If you squint the right
way, you can call Django's ORM the "Model", the view functions the "View", and
the dynamically-generated API the "Controller" -- but not really.

In fact, you might say that Django is a "MTV" framework -- that is, Model,
Template, and View make much more sense to us.

So, although we've been strongly influenced by MVC -- especially in the
separation-of-data-from-logic department -- we've also strayed from the path
where it makes sense.

<Framework X> does <feature Y> -- why doesn't Django?
-----------------------------------------------------

We're well aware that there are other awesome Web frameworks out there, and
we're not adverse to borrowing ideas where appropriate. However, Django was
developed precisely because we were unhappy with the status quo, so please be
aware that "because <Framework X>" does it is not going to be sufficient reason
to add a given feature to Django.

Why did you write all of Django from scratch, instead of using other Python libraries?
--------------------------------------------------------------------------------------

When Django was originally written a couple of years ago, Adrian and Simon
spent quite a bit of time exploring the various Python Web frameworks
available.

In our opinion, none of them were completely up to snuff.

We're picky. You might even call us perfectionists. (With deadlines.)

Over time, we stumbled across open-source libraries that did things we'd
already implemented. It was reassuring to see other people solving similar
problems in similar ways, but it was too late to integrate outside code: We'd
already written, tested and implemented our own framework bits in several
production settings -- and our own code met our needs delightfully.

In most cases, however, we found that existing frameworks/tools inevitably had
some sort of fundamental, fatal flaw that made us squeamish. No tool fit our
philosophies 100%.

Like we said: We're picky.

We've documented our philosophies on the `design philosophies page`_.

.. _design philosophies page: http://www.djangoproject.com/documentation/design_philosophies/

Do you have any of those nifty "screencast" things?
---------------------------------------------------

They're in the works. It's amazing how much time those things take! Stay tuned...

Installation questions
======================

How do I get started?
---------------------

    #. `Download the code`_.
    #. Install Django (read the `installation guide`_).
    #. Walk through the tutorial_.
    #. Check out the rest of the documentation_, and `ask questions`_ if you
       run into trouble.

.. _`Download the code`: http://www.djangoproject.com/download/
.. _`installation guide`: http://www.djangoproject.com/documentation/install/
.. _tutorial:  http://www.djangoproject.com/documentation/tutorial1/
.. _documentation: http://www.djangoproject.com/documentation/
.. _ask questions: http://www.djangoproject.com/community/

How do I fix the "install a later version of setuptools" error?
---------------------------------------------------------------

Just run the ``ex_setup.py`` script in the Django distribution.

What are Django's prerequisites?
--------------------------------

Django requires Python_ 2.3 or later.

For a development environment -- if you just want to experiment with Django --
you don't need to have a separate Web server installed; Django comes with its
own lightweight development server. For a production environment, we recommend
`Apache 2`_ and mod_python_, although Django follows the WSGI_ spec, which
means it can run on a variety of server platforms.

You'll also need a database engine. PostgreSQL_ is recommended, and MySQL_
and `SQLite 3`_ are supported.

.. _Python: http://www.python.org/
.. _Apache 2: http://httpd.apache.org/
.. _mod_python: http://www.modpython.org/
.. _WSGI: http://www.python.org/peps/pep-0333.html
.. _PostgreSQL: http://www.postgresql.org/
.. _MySQL: http://www.mysql.com/
.. _`SQLite 3`: http://www.sqlite.org/

Do I have to use mod_python?
----------------------------

Not if you just want to play around and develop things on your local computer.
Django comes with its own Web server, and things should Just Work.

For production use, though, we recommend mod_python. The Django developers have
been running it on mod_python for about two years, and it's quite stable.

However, if you don't want to use mod_python, you can use a different server,
as long as that server has WSGI_ hooks. More information on alternate server
arrangements is forthcoming.

.. _WSGI: http://www.python.org/peps/pep-0333.html

How do I install mod_python on Windows?
---------------------------------------

    * For Python 2.4, check out this `guide to mod_python & Python 2.3`_.
    * For Python 2.3, grab mod_python from http://www.modpython.org/ and read
      `Running mod_python on Apache on Windows2000`_.
    * Also, try this (not Windows-specific) `guide to getting mod_python
      working`_.

.. _`guide to mod_python & Python 2.3`: http://www.lehuen.com/nicolas/index.php/2005/02/21/39-win32-build-of-mod_python-314-for-python-24
.. _`Running mod_python on Apache on Windows2000`: http://groups-beta.google.com/group/comp.lang.python/msg/139af8c83a5a9d4f
.. _`guide to getting mod_python working`: http://www.dscpl.com.au/articles/modpython-001.html

(Thanks to deelan for this info.)

Will Django run under shared hosting (like TextDrive or Dreamhost)?
-------------------------------------------------------------------

See our `Django-friendly Web hosts`_ page.

.. _`Django-friendly Web hosts`: http://code.djangoproject.com/wiki/DjangoFriendlyWebHosts

Should I use the official version or development version?
---------------------------------------------------------

The Django developers improve Django every day and are pretty good about not
checking in broken code. We use the development code (from the Subversion
repository) directly on our servers, so we consider it stable. With that in
mind, we recommend that you use the latest development code, because it
generally contains more features and fewer bugs than the "official" releases.

Using Django
============

Why do I get an error about importing DJANGO_SETTINGS_MODULE?
-------------------------------------------------------------

Make sure that:

    * The environment variable DJANGO_SETTINGS_MODULE is set to a fully-qualified
      Python module (i.e. "mysite.settings.main").

    * Said module is on ``sys.path`` (``import mysite.settings.main`` should work).

    * The module doesn't contain syntax errors (of course).

    * If you're using mod_python but *not* using Django's request handler,
      you'll need to work around a mod_python bug related to the use of
      ``SetEnv``; before you import anything from Django you'll need to do
      the following::

            os.environ.update(req.subprocess_env)

      (where ``req`` is the mod_python request object).

I can't stand your template language. Do I have to use it?
----------------------------------------------------------

We happen to think our template engine is the best thing since chunky bacon,
but we recognize that choosing a template language runs close to religion.
There's nothing about Django that requires using the template language, so
if you're attached to ZPT, Cheetah, or whatever, feel free to use those.

How do I use image and file fields?
-----------------------------------

Using a ``FileField`` or an ``ImageField`` in a model takes a few steps:

    #. In your settings file, define ``MEDIA_ROOT`` as the full path to
       a directory where you'd like Django to store uploaded files. (For
       performance, these files are not stored in the database.) Define
       ``MEDIA_URL`` as the base public URL of that directory. Make sure that
       this directory is writable by the Web server's user account.

    #. Add the ``FileField`` or ``ImageField`` to your model, making sure
       to define the ``upload_to`` option to tell Django to which subdirectory
       of ``MEDIA_ROOT`` it should upload files.

    #. All that will be stored in your database is a path to the file
       (relative to ``MEDIA_ROOT``). You'll must likely want to use the
       convenience ``get_<fieldname>_url`` function provided by Django. For
       example, if your ``ImageField`` is called ``mug_shot``, you can get the
       absolute URL to your image in a template with
       ``{{ object.get_mug_shot_url }}``.

If I make changes to a model, how do I update the database?
-----------------------------------------------------------

If you don't care about clearing data, just do this::

    django-admin.py sqlreset appname | psql dbname

That "psql" assumes you're using PostgreSQL. If you're using MySQL, use the
appropriate command-line utility, ``mysql``.

``django-admin.py sqlreset`` outputs SQL that clears the app's database
table(s) and creates new ones. The above command uses a Unix pipe to send the
SQL directly to the PostgreSQL command-line utility, which accepts SQL as
input.

If you do care about deleting data, you'll have to execute the ``ALTER TABLE``
statements manually in your database. That's the way we've always done it,
because dealing with data is a very sensitive operation that we've wanted to
avoid automating. That said, there's some work being done to add a
``django-admin.py updatedb`` command, which would output the necessary
``ALTER TABLE`` statements, if any.

The database API
================

How can I see the raw SQL queries Django is running?
----------------------------------------------------

Make sure your Django ``DEBUG`` setting is set to ``True``. Then, just do
this::

    >>> from django.core.db import db
    >>> db.queries
    [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls',
    'time': '0.002'}]

``db.queries`` is only available if ``DEBUG`` is ``True``. It's a list of
dictionaries in order of query execution. Each dictionary has the following::

    ``sql`` -- The raw SQL statement
    ``time`` -- How long the statement took to execute, in seconds.

``db.queries`` includes all SQL statements -- INSERTs, UPDATES, SELECTs, etc.

Can I use Django with a pre-existing database?
----------------------------------------------

Yes. See `Integrating with a legacy database`_.

.. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/

The admin site
==============

I can't log in. When I enter a valid username and password, it just brings up the login page again, with no error messages.
---------------------------------------------------------------------------------------------------------------------------

The login cookie isn't being set correctly, because the domain of the cookie
sent out by Django doesn't match the domain in your browser. Try these two
things:

    * Set the ``SESSION_COOKIE_DOMAIN`` setting in your admin config file
      to match your domain. For example, if you're going to
      "http://www.mysite.com/admin/" in your browser, in
      "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.mysite.com'``.

    * Some browsers (Firefox?) don't like to accept cookies from domains that
      don't have dots in them. If you're running the admin site on "localhost"
      or another domain that doesn't have a dot in it, try going to
      "localhost.localdomain" or "127.0.0.1". And set
      ``SESSION_COOKIE_DOMAIN`` accordingly.

I can't log in. When I enter a valid username and password, it brings up the login page again, with a "Please enter a correct username and password" error.
-----------------------------------------------------------------------------------------------------------------------------------------------------------

If you're sure your username and password are correct, make sure your user
account has ``is_active`` and ``is_staff`` set to True. The admin site only
allows access to users with those two fields both set to True.

My "list_filter" contains a ManyToManyField, but the filter doesn't display.
----------------------------------------------------------------------------

Django won't bother displaying the filter for a ManyToManyField if there are
fewer than two related objects.

For example, if your ``list_filter`` includes ``sites``, and there's only one
site in your database, it won't display a "Site" filter. In that case,
filtering by site would be meaningless.

How can I customize the functionality of the admin interface?
-------------------------------------------------------------

You've got several options. If you want to piggyback on top of an add/change
form that Django automatically generates, you can attach arbitrary JavaScript
modules to the page via the model's ``admin.js`` parameter. That parameter is
a list of URLs, as strings, pointing to JavaScript modules that will be
included within the admin form via a <script> tag.

If you want more flexibility than simply tweaking the auto-generated forms,
feel free to write custom views for the admin. The admin is powered by Django
itself, and you can write custom views that hook into the authentication
system, check permissions and do whatever else they need to do.

If you want to customize the look-and-feel of the admin interface, read the
next question.

The dynamically-generated admin site is ugly! How can I change it?
------------------------------------------------------------------

We think it's very purty, but if you don't agree, you can modify the admin
site's presentation by editing the CSS stylesheet and/or associated image files.
The site is built using semantic HTML, so any changes you'd like to make should
be possible by editing the CSS stylesheet. We've got a `guide to the CSS used in
the admin`_ to get you started.

.. _`guide to the CSS used in the admin`: http://www.djangoproject.com/documentation/admin_css/