mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
039d121227
git-svn-id: http://code.djangoproject.com/svn/django/trunk@237 bcc190cf-cafb-0310-a4f2-bffc1f526a37
297 lines
13 KiB
Plaintext
297 lines
13 KiB
Plaintext
==========
|
|
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`_. He lives in Chicago.
|
|
|
|
`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.
|
|
|
|
`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.
|
|
|
|
`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. He lives in Lawrence, Kansas.
|
|
|
|
.. _`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.
|
|
|
|
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/
|
|
.. _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_ is
|
|
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/
|
|
|
|
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.mod_python.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)?
|
|
-------------------------------------------------------------------
|
|
|
|
Right now, no, unless you can get your host to install mod_python. However, as
|
|
the community starts to use Django's WSGI bindings with other Web servers, this
|
|
will probably be possible sooner rather than later.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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 ``REGISTRATION_COOKIE_DOMAIN`` setting to match your domain. For
|
|
example, if you're going to "http://www.mysite.com/admin/" in your browser,
|
|
set ``REGISTRATION_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 ``REGISTRATION_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.
|
|
|
|
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/
|