diff options
Diffstat (limited to 'parts/django/docs/faq')
| -rw-r--r-- | parts/django/docs/faq/admin.txt | 96 | ||||
| -rw-r--r-- | parts/django/docs/faq/contributing.txt | 102 | ||||
| -rw-r--r-- | parts/django/docs/faq/general.txt | 192 | ||||
| -rw-r--r-- | parts/django/docs/faq/help.txt | 73 | ||||
| -rw-r--r-- | parts/django/docs/faq/index.txt | 14 | ||||
| -rw-r--r-- | parts/django/docs/faq/install.txt | 102 | ||||
| -rw-r--r-- | parts/django/docs/faq/models.txt | 105 | ||||
| -rw-r--r-- | parts/django/docs/faq/usage.txt | 77 |
8 files changed, 761 insertions, 0 deletions
diff --git a/parts/django/docs/faq/admin.txt b/parts/django/docs/faq/admin.txt new file mode 100644 index 0000000..1512675 --- /dev/null +++ b/parts/django/docs/faq/admin.txt @@ -0,0 +1,96 @@ +FAQ: The admin +============== + +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.example.com/admin/" in your browser, in + "myproject.settings" you should set ``SESSION_COOKIE_DOMAIN = 'www.example.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. + +How can I prevent the cache middleware from caching the admin site? +------------------------------------------------------------------- + +Set the :setting:`CACHE_MIDDLEWARE_ANONYMOUS_ONLY` setting to ``True``. See the +:doc:`cache documentation </topics/cache>` for more information. + +How do I automatically set a field's value to the user who last edited the object in the admin? +----------------------------------------------------------------------------------------------- + +The :class:`~django.contrib.admin.ModelAdmin` class provides customization hooks +that allow you to transform an object as it saved, using details from the +request. By extracting the current user from the request, and customizing the +:meth:`~django.contrib.admin.ModelAdmin.save_model` hook, you can update an +object to reflect the user that edited it. See :ref:`the documentation on +ModelAdmin methods <model-admin-methods>` for an example. + +How do I limit admin access so that objects can only be edited by the users who created them? +--------------------------------------------------------------------------------------------- + +The :class:`~django.contrib.admin.ModelAdmin` class also provides customization +hooks that allow you to control the visibility and editability of objects in the +admin. Using the same trick of extracting the user from the request, the +:meth:`~django.contrib.admin.ModelAdmin.queryset` and +:meth:`~django.contrib.admin.ModelAdmin.has_change_permission` can be used to +control the visibility and editability of objects in the admin. + +My admin-site CSS and images showed up fine using the development server, but they're not displaying when using mod_python. +--------------------------------------------------------------------------------------------------------------------------- + +See :ref:`serving the admin files <serving-the-admin-files>` +in the "How to use Django with mod_python" documentation. + +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 ``class 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 like it, 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 and plenty of CSS hooks, so any changes you'd +like to make should be possible by editing the stylesheet. We've got a +:doc:`guide to the CSS used in the admin </obsolete/admin-css>` to get you started. + diff --git a/parts/django/docs/faq/contributing.txt b/parts/django/docs/faq/contributing.txt new file mode 100644 index 0000000..81c06f3 --- /dev/null +++ b/parts/django/docs/faq/contributing.txt @@ -0,0 +1,102 @@ +FAQ: Contributing code +====================== + +How can I get started contributing code to Django? +-------------------------------------------------- + +Thanks for asking! We've written an entire document devoted to this question. +It's titled :doc:`Contributing to Django </internals/contributing>`. + +I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch? +-------------------------------------------------------------------------------------------- + +Don't worry: We're not ignoring you! + +It's important to understand there is a difference between "a ticket is being +ignored" and "a ticket has not been attended to yet." Django's ticket system +contains hundreds of open tickets, of various degrees of impact on end-user +functionality, and Django's developers have to review and prioritize. + +On top of that: the people who work on Django are all volunteers. As a result, +the amount of time that we have to work on the framework is limited and will +vary from week to week depending on our spare time. If we're busy, we may not +be able to spend as much time on Django as we might want. + +The best way to make sure tickets do not get hung up on the way to checkin is +to make it dead easy, even for someone who may not be intimately familiar with +that area of the code, to understand the problem and verify the fix: + + * Are there clear instructions on how to reproduce the bug? If this + touches a dependency (such as PIL), a contrib module, or a specific + database, are those instructions clear enough even for someone not + familiar with it? + + * If there are several patches attached to the ticket, is it clear what + each one does, which ones can be ignored and which matter? + + * Does the patch include a unit test? If not, is there a very clear + explanation why not? A test expresses succinctly what the problem is, + and shows that the patch actually fixes it. + +If your patch stands no chance of inclusion in Django, we won't ignore it -- +we'll just close the ticket. So if your ticket is still open, it doesn't mean +we're ignoring you; it just means we haven't had time to look at it yet. + +When and how might I remind the core team of a patch I care about? +------------------------------------------------------------------ + +A polite, well-timed message to the mailing list is one way to get attention. +To determine the right time, you need to keep an eye on the schedule. If you +post your message when the core developers are trying to hit a feature +deadline or manage a planning phase, you're not going to get the sort of +attention you require. However, if you draw attention to a ticket when the +core developers are paying particular attention to bugs -- just before a bug +fixing sprint, or in the lead up to a beta release for example -- you're much +more likely to get a productive response. + +Gentle IRC reminders can also work -- again, strategically timed if possible. +During a bug sprint would be a very good time, for example. + +Another way to get traction is to pull several related tickets together. When +the core developers sit down to fix a bug in an area they haven't touched for +a while, it can take a few minutes to remember all the fine details of how +that area of code works. If you collect several minor bug fixes together into +a similarly themed group, you make an attractive target, as the cost of coming +up to speed on an area of code can be spread over multiple tickets. + +Please refrain from emailing core developers personally, or repeatedly raising +the same issue over and over. This sort of behavior will not gain you any +additional attention -- certainly not the attention that you need in order to +get your pet bug addressed. + +But I've reminded you several times and you keep ignoring my patch! +------------------------------------------------------------------- + +Seriously - we're not ignoring you. If your patch stands no chance of +inclusion in Django, we'll close the ticket. For all the other tickets, we +need to prioritize our efforts, which means that some tickets will be +addressed before others. + +One of the criteria that is used to prioritize bug fixes is the number of +people that will likely be affected by a given bug. Bugs that have the +potential to affect many people will generally get priority over those that +are edge cases. + +Another reason that bugs might be ignored for while is if the bug is a symptom +of a larger problem. While we can spend time writing, testing and applying +lots of little patches, sometimes the right solution is to rebuild. If a +rebuild or refactor of a particular component has been proposed or is +underway, you may find that bugs affecting that component will not get as much +attention. Again, this is just a matter of prioritizing scarce resources. By +concentrating on the rebuild, we can close all the little bugs at once, and +hopefully prevent other little bugs from appearing in the future. + +Whatever the reason, please keep in mind that while you may hit a particular +bug regularly, it doesn't necessarily follow that every single Django user +will hit the same bug. Different users use Django in different ways, stressing +different parts of the code under different conditions. When we evaluate the +relative priorities, we are generally trying to consider the needs of the +entire community, not just the severity for one particular user. This doesn't +mean that we think your problem is unimportant -- just that in the limited +time we have available, we will always err on the side of making 10 people +happy rather than making 1 person happy. diff --git a/parts/django/docs/faq/general.txt b/parts/django/docs/faq/general.txt new file mode 100644 index 0000000..96abad2 --- /dev/null +++ b/parts/django/docs/faq/general.txt @@ -0,0 +1,192 @@ +FAQ: General +============ + +Why does this project exist? +---------------------------- + +Django grew from a very practical need: World Online, a newspaper Web +operation, is responsible for building intensive Web applications on journalism +deadlines. In the fast-paced newsroom, World Online often has only a matter of +hours to take a complicated Web application from concept to public launch. + +At the same time, the World Online Web developers have consistently been +perfectionists when it comes to following best practices of Web development. + +In fall 2003, the World Online developers (Adrian Holovaty and Simon Willison) +ditched PHP and began using Python to develop its Web sites. As they built +intensive, richly interactive sites such as Lawrence.com, they began to extract +a generic Web development framework that let them build Web applications more +and more quickly. They tweaked this framework constantly, adding improvements +over two years. + +In summer 2005, World Online decided to open-source the resulting software, +Django. 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. + +Django is pronounced **JANG**-oh. Rhymes with FANG-oh. The "D" is silent. + +We've also recorded an `audio clip of the pronunciation`_. + +.. _Django Reinhardt: http://en.wikipedia.org/wiki/Django_Reinhardt +.. _audio clip of the pronunciation: http://red-bean.com/~adrian/django_pronunciation.mp3 + +Is Django stable? +----------------- + +Yes. World Online has been using Django for more than three years. Sites built +on Django have weathered traffic spikes of over one million hits an hour and a +number of Slashdottings. 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 uses a "shared-nothing" architecture, which means you can add hardware +at any level -- database servers, caching servers or Web/application servers. + +The framework cleanly separates components such as its database layer and +application layer. And it ships with a simple-yet-powerful +:doc:`cache framework </topics/cache>`. + +Who's behind this? +------------------ + +Django was originally developed at World Online, the Web department of a +newspaper in Lawrence, Kansas, USA. Django's now run by an international team of +volunteers; you can read all about them over at the :doc:`list of committers +</internals/committers>` + +Which sites use Django? +----------------------- + +The Django wiki features a consistently growing `list of Django-powered sites`_. +Feel free to add your Django-powered site to the list. + +.. _list of Django-powered sites: http://code.djangoproject.com/wiki/DjangoPoweredSites + +.. _mtv: + +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? +----------------------------------------------------------------------------------------------------------------------------------------------------- + +Well, the standard names are debatable. + +In our interpretation of MVC, the "view" describes the data that gets presented +to the user. It's not necessarily *how* the data *looks*, but *which* data is +presented. The view describes *which data you see*, not *how you see it.* It's +a subtle distinction. + +So, in our case, a "view" is the Python callback function for a particular URL, +because that callback function describes which data is presented. + +Furthermore, it's sensible to separate content from presentation -- which is +where templates come in. In Django, a "view" describes which data is presented, +but a view normally delegates to a template, which describes *how* the data is +presented. + +Where does the "controller" fit in, then? In Django's case, it's probably the +framework itself: the machinery that sends a request to the appropriate view, +according to the Django URL configuration. + +If you're hungry for acronyms, you might say that Django is a "MTV" framework +-- that is, "model", "template", and "view." That breakdown makes much more +sense. + +At the end of the day, of course, it comes down to getting stuff done. And, +regardless of how things are named, Django gets stuff done in a way that's most +logical to us. + +<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 averse 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 +:doc:`design philosophies page </misc/design-philosophies>`. + +Is Django a content-management-system (CMS)? +-------------------------------------------- + +No, Django is not a CMS, or any sort of "turnkey product" in and of itself. +It's a Web framework; it's a programming tool that lets you build Web sites. + +For example, it doesn't make much sense to compare Django to something like +Drupal_, because Django is something you use to *create* things like Drupal. + +Of course, Django's automatic admin site is fantastic and timesaving -- but +the admin site is one module of Django the framework. Furthermore, although +Django has special conveniences for building "CMS-y" apps, that doesn't mean +it's not just as appropriate for building "non-CMS-y" apps (whatever that +means!). + +.. _Drupal: http://drupal.org/ + +How can I download the Django documentation to read it offline? +--------------------------------------------------------------- + +The Django docs are available in the ``docs`` directory of each Django tarball +release. These docs are in reST (reStructuredText) format, and each text file +corresponds to a Web page on the official Django site. + +Because the documentation is `stored in revision control`_, you can browse +documentation changes just like you can browse code changes. + +Technically, the docs on Django's site are generated from the latest development +versions of those reST documents, so the docs on the Django site may offer more +information than the docs that come with the latest Django release. + +.. _stored in revision control: http://code.djangoproject.com/browser/django/trunk/docs + +Where can I find Django developers for hire? +-------------------------------------------- + +Consult our `developers for hire page`_ for a list of Django developers who +would be happy to help you. + +You might also be interested in posting a job to http://djangogigs.com/ . +If you want to find Django-capable people in your local area, try +http://djangopeople.net/ . + +.. _developers for hire page: http://code.djangoproject.com/wiki/DevelopersForHire diff --git a/parts/django/docs/faq/help.txt b/parts/django/docs/faq/help.txt new file mode 100644 index 0000000..d84b3f5 --- /dev/null +++ b/parts/django/docs/faq/help.txt @@ -0,0 +1,73 @@ +FAQ: Getting Help +================= + +How do I do X? Why doesn't Y work? Where can I go to get help? +-------------------------------------------------------------- + +If this FAQ doesn't contain an answer to your question, you might want to +try the `django-users mailing list`_. Feel free to ask any question related +to installing, using, or debugging Django. + +If you prefer IRC, the `#django IRC channel`_ on the Freenode IRC network is an +active community of helpful individuals who may be able to solve your problem. + +.. _`django-users mailing list`: http://groups.google.com/group/django-users +.. _`#django IRC channel`: irc://irc.freenode.net/django + +Why hasn't my message appeared on django-users? +----------------------------------------------- + +django-users_ has a lot of subscribers. This is good for the community, as +it means many people are available to contribute answers to questions. +Unfortunately, it also means that django-users_ is an attractive target for +spammers. + +In order to combat the spam problem, when you join the django-users_ mailing +list, we manually moderate the first message you send to the list. This means +that spammers get caught, but it also means that your first question to the +list might take a little longer to get answered. We apologize for any +inconvenience that this policy may cause. + +.. _django-users: http://groups.google.com/group/django-users + +Nobody on django-users answered my question! What should I do? +-------------------------------------------------------------- + +Try making your question more specific, or provide a better example of your +problem. + +As with most open-source mailing lists, the folks on django-users_ are +volunteers. If nobody has answered your question, it may be because nobody +knows the answer, it may be because nobody can understand the question, or it +may be that everybody that can help is busy. One thing you might try is to ask +the question on IRC -- visit the `#django IRC channel`_ on the Freenode IRC +network. + +You might notice we have a second mailing list, called django-developers_ -- +but please don't e-mail support questions to this mailing list. This list is +for discussion of the development of Django itself. Asking a tech support +question there is considered quite impolite. + +.. _django-developers: http://groups.google.com/group/django-developers + +I think I've found a bug! What should I do? +------------------------------------------- + +Detailed instructions on how to handle a potential bug can be found in our +:ref:`Guide to contributing to Django <reporting-bugs>`. + +I think I've found a security problem! What should I do? +-------------------------------------------------------- + +If you think you've found a security problem with Django, please send a message +to security@djangoproject.com. This is a private list only open to long-time, +highly trusted Django developers, and its archives are not publicly readable. + +Due to the sensitive nature of security issues, we ask that if you think you +have found a security problem, *please* don't send a message to one of the +public mailing lists. Django has a +:ref:`policy for handling security issues <reporting-security-issues>`; +while a defect is outstanding, we would like to minimize any damage that +could be inflicted through public knowledge of that defect. + +.. _`policy for handling security issues`: ../contributing/#reporting-security-issues diff --git a/parts/django/docs/faq/index.txt b/parts/django/docs/faq/index.txt new file mode 100644 index 0000000..347caba --- /dev/null +++ b/parts/django/docs/faq/index.txt @@ -0,0 +1,14 @@ +========== +Django FAQ +========== + +.. toctree:: + :maxdepth: 2 + + general + install + usage + help + models + admin + contributing
\ No newline at end of file diff --git a/parts/django/docs/faq/install.txt b/parts/django/docs/faq/install.txt new file mode 100644 index 0000000..3fbcb38 --- /dev/null +++ b/parts/django/docs/faq/install.txt @@ -0,0 +1,102 @@ +FAQ: Installation +================= + +How do I get started? +--------------------- + + #. `Download the code`_. + #. Install Django (read the :doc:`installation guide </intro/install>`). + #. Walk through the :doc:`tutorial </intro/tutorial01>`. + #. Check out the rest of the :doc:`documentation </index>`, and `ask questions`_ if you + run into trouble. + +.. _`Download the code`: http://www.djangoproject.com/download/ +.. _ask questions: http://www.djangoproject.com/community/ + +What are Django's prerequisites? +-------------------------------- + +Django requires Python_, specifically any version of Python from 2.4 +through 2.7. No other Python libraries are required for basic Django +usage. + +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, Django +follows the WSGI_ spec, which means it can run on a variety of server +platforms. See :doc:`Deploying Django </howto/deployment/index>` for some +popular alternatives. Also, the `server arrangements wiki page`_ contains +details for several deployment strategies. + +If you want to use Django with a database, which is probably the case, you'll +also need a database engine. PostgreSQL_ is recommended, because we're +PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported. + +.. _Python: http://www.python.org/ +.. _WSGI: http://www.python.org/dev/peps/pep-0333/ +.. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements +.. _PostgreSQL: http://www.postgresql.org/ +.. _MySQL: http://www.mysql.com/ +.. _`SQLite 3`: http://www.sqlite.org/ +.. _Oracle: http://www.oracle.com/ + +Do I lose anything by using Python 2.4 versus newer Python versions, such as Python 2.5 or 2.6? +----------------------------------------------------------------------------------------------- + +Not in the core framework. Currently, Django itself officially supports any +version of Python from 2.4 through 2.7, inclusive. However, newer versions of +Python are often faster, have more features, and are better supported. +Third-party applications for use with Django are, of course, free to set their +own version requirements. + +Over the next year or two Django will begin dropping support for older Python +versions as part of a migration which will end with Django running on Python 3 +(see below for details). + +All else being equal, we recommend that you use the latest 2.x release +(currently Python 2.7). This will let you take advantage of the numerous +improvements and optimizations to the Python language since version 2.4, and +will help ease the process of dropping support for older Python versions on +the road to Python 3. + +Can I use Django with Python 2.3? +--------------------------------- + +Django 1.1 (and earlier) supported Python 2.3. Django 1.2 and newer does not. +We highly recommend you upgrade Python if at all possible, but Django 1.1 will +continue to work on Python 2.3. + +Can I use Django with Python 3? +------------------------------- + +Not at the moment. Python 3.0 introduced a number of +backwards-incompatible changes to the Python language, and although +these changes are generally a good thing for Python's future, it will +be a while before most Python software catches up and is able to run +on Python 3.0. For larger Python-based software like Django, the +transition is expected to take at least a year or two (since it +involves dropping support for older Python releases and so must be +done gradually). + +In the meantime, Python 2.x releases will be supported and provided +with bug fixes and security updates by the Python development team, so +continuing to use a Python 2.x release during the transition should +not present any risk. + +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 stable version or development version? +------------------------------------------------------- + +Generally, if you're using code in production, you should be using a +stable release. The Django project publishes a full stable release +every nine months or so, with bugfix updates in between. These stable +releases contain the API that is covered by our backwards +compatibility guarantees; if you write code against stable releases, +you shouldn't have any problems upgrading when the next official +version is released. diff --git a/parts/django/docs/faq/models.txt b/parts/django/docs/faq/models.txt new file mode 100644 index 0000000..f00d453 --- /dev/null +++ b/parts/django/docs/faq/models.txt @@ -0,0 +1,105 @@ +FAQ: Databases and models +========================= + +.. _faq-see-raw-sql-queries: + +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.db import connection + >>> connection.queries + [{'sql': 'SELECT polls_polls.id,polls_polls.question,polls_polls.pub_date FROM polls_polls', + 'time': '0.002'}] + +``connection.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. + +``connection.queries`` includes all SQL statements -- INSERTs, UPDATES, +SELECTs, etc. Each time your app hits the database, the query will be recorded. +Note that the raw SQL logged in ``connection.queries`` may not include +parameter quoting. Parameter quoting is performed by the database-specific +backend, and not all backends provide a way to retrieve the SQL after quoting. + +.. versionadded:: 1.2 + +If you are using :doc:`multiple databases</topics/db/multi-db>`, you can use the +same interface on each member of the ``connections`` dictionary:: + + >>> from django.db import connections + >>> connections['my_db_alias'].queries + +Can I use Django with a pre-existing database? +---------------------------------------------- + +Yes. See :doc:`Integrating with a legacy database </howto/legacy-databases>`. + +If I make changes to a model, how do I update the database? +----------------------------------------------------------- + +If you don't mind clearing data, your project's ``manage.py`` utility has an +option to reset the SQL for a particular application:: + + manage.py reset appname + +This drops any tables associated with ``appname`` and recreates them. + +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 partially +automated database-upgrade functionality. + +Do Django models support multiple-column primary keys? +------------------------------------------------------ + +No. Only single-column primary keys are supported. + +But this isn't an issue in practice, because there's nothing stopping you from +adding other constraints (using the ``unique_together`` model option or +creating the constraint directly in your database), and enforcing the +uniqueness at that level. Single-column primary keys are needed for things such +as the admin interface to work; e.g., you need a simple way of being able to +specify an object to edit or delete. + +How do I add database-specific options to my CREATE TABLE statements, such as specifying MyISAM as the table type? +------------------------------------------------------------------------------------------------------------------ + +We try to avoid adding special cases in the Django code to accommodate all the +database-specific options such as table type, etc. If you'd like to use any of +these options, create an :ref:`SQL initial data file <initial-sql>` that +contains ``ALTER TABLE`` statements that do what you want to do. The initial +data files are executed in your database after the ``CREATE TABLE`` statements. + +For example, if you're using MySQL and want your tables to use the MyISAM table +type, create an initial data file and put something like this in it:: + + ALTER TABLE myapp_mytable ENGINE=MyISAM; + +As explained in the :ref:`SQL initial data file <initial-sql>` documentation, +this SQL file can contain arbitrary SQL, so you can make any sorts of changes +you need to make. + +Why is Django leaking memory? +----------------------------- + +Django isn't known to leak memory. If you find your Django processes are +allocating more and more memory, with no sign of releasing it, check to make +sure your ``DEBUG`` setting is set to ``False``. If ``DEBUG`` is ``True``, then +Django saves a copy of every SQL statement it has executed. + +(The queries are saved in ``django.db.connection.queries``. See +`How can I see the raw SQL queries Django is running?`_.) + +To fix the problem, set ``DEBUG`` to ``False``. + +If you need to clear the query list manually at any point in your functions, +just call ``reset_queries()``, like this:: + + from django import db + db.reset_queries() diff --git a/parts/django/docs/faq/usage.txt b/parts/django/docs/faq/usage.txt new file mode 100644 index 0000000..c11514c --- /dev/null +++ b/parts/django/docs/faq/usage.txt @@ -0,0 +1,77 @@ +FAQ: 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"). + + * Said module is on ``sys.path`` (``import mysite.settings`` 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. + +Do I have to use your model/database layer? +------------------------------------------- + +Nope. Just like the template system, the model/database layer is decoupled from +the rest of the framework. + +The one exception is: If you use a different database library, you won't get to +use Django's automatically-generated admin site. That app is coupled to the +Django database layer. + +How do I use image and file fields? +----------------------------------- + +Using a :class:`~django.db.models.FileField` or an +:class:`~django.db.models.ImageField` in a model takes a few steps: + + #. In your settings file, you'll need to define :setting:`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 :setting:`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 :class:`~django.db.models.FileField` or + :class:`~django.db.models.ImageField` to your model, making sure to + define the :attr:`~django.db.models.FileField.upload_to` option to tell + Django to which subdirectory of :setting:`MEDIA_ROOT` it should upload + files. + + #. All that will be stored in your database is a path to the file + (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the + convenience :attr:`~django.core.files.File.url` attribute provided by + Django. For example, if your :class:`~django.db.models.ImageField` is + called ``mug_shot``, you can get the absolute path to your image in a + template with ``{{ object.mug_shot.url }}``. + +How do I make a variable available to all my templates? +------------------------------------------------------- + +Sometimes your templates just all need the same thing. A common example would +be dynamically-generated menus. At first glance, it seems logical to simply +add a common dictionary to the template context. + +The correct solution is to use a ``RequestContext``. Details on how to do this +are here: :ref:`subclassing-context-requestcontext`. |