django/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 gypsy-jazz virtuoso, an amateur Beatles historian and a proud
    Chicagoan. He's also a pretty decent programmer, with a knack for whipping
    data into shape and putting it to work for the good of his fellow man.
    Adrian is the lead developer at World Online and the man behind the code at
    `chicagocrime.org`_.

`Simon Willison`_
    Simon is a well-respected Web developer from England. He had a one-year
    stint 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 England to finish his degree and is poised to continue doing big,
    exciting things on the Web. Read his weblog at `simon.incutio.com`_.

`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.

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

.. _`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 belive in
any capital-M Methodoligies; 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 API automatically generated from the models the "Controller" -- but not
really.

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.

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/

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, Apache2_, and mod_python_.  You'll
also need a database engine; PostgreSQL_ is recommended, and MySQL_ is
supported.

.. _Python: http://www.python.org/
.. _Apache2: http://httpd.apache.org/
.. _mod_python: http://www.modpython.org/
.. _PostgreSQL: http://www.postgresql.org/
.. _MySQL: http://www.mysql.com/

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

    * If you are running Python 2.4, check out this `guide to mod_python & Python 2.3`_.

    * For Python 2.3, grab mod_python from http://ww.mod_python.org/, the 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.)

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

In the first release, yes.  However, WSGI_ support (which will let Django run
under FCGI, SCGI, medusa, etc.) is in the works; stay tuned!

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

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

Right now, no, unless you can get your host to install mod_python.  However, as
the previous question says, WSGI support is comming!.

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-qualifed
      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).

The admin interface
===================

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/