From fe361e678a46dc4c717c79c2f12b3ba32293b81a Mon Sep 17 00:00:00 2001 From: Robin Munn Date: Wed, 31 Jan 2007 23:43:09 +0000 Subject: Merged revisions 4186 to 4454 from trunk. git-svn-id: http://code.djangoproject.com/svn/django/branches/sqlalchemy@4455 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/add_ons.txt | 16 +- docs/apache_auth.txt | 4 +- docs/api_stability.txt | 46 +-- docs/authentication.txt | 22 +- docs/cache.txt | 2 +- docs/contributing.txt | 168 +++++++++- docs/csrf.txt | 37 +- docs/db-api.txt | 61 +++- docs/design_philosophies.txt | 2 +- docs/django-admin.txt | 10 +- docs/email.txt | 8 +- docs/faq.txt | 24 +- docs/fastcgi.txt | 2 +- docs/flatpages.txt | 14 +- docs/forms.txt | 46 ++- docs/generic_views.txt | 58 ++-- docs/i18n.txt | 20 +- docs/install.txt | 6 +- docs/legacy_databases.txt | 20 +- docs/middleware.txt | 15 +- docs/model-api.txt | 29 +- docs/modpython.txt | 2 +- docs/newforms.txt | 784 ++++++++++++++++++++++++++++++++++++++++++- docs/outputting_csv.txt | 6 +- docs/outputting_pdf.txt | 2 +- docs/overview.txt | 2 +- docs/redirects.txt | 16 +- docs/request_response.txt | 4 +- docs/sessions.txt | 21 +- docs/settings.txt | 43 +-- docs/sitemaps.txt | 20 +- docs/sites.txt | 12 +- docs/static_files.txt | 6 +- docs/syndication_feeds.txt | 14 +- docs/templates.txt | 26 +- docs/templates_python.txt | 24 +- docs/testing.txt | 12 +- docs/tutorial01.txt | 10 +- docs/tutorial02.txt | 10 +- docs/tutorial03.txt | 15 +- docs/tutorial04.txt | 6 +- docs/url_dispatch.txt | 14 +- 42 files changed, 1341 insertions(+), 318 deletions(-) (limited to 'docs') diff --git a/docs/add_ons.txt b/docs/add_ons.txt index 58c01c4fc0..d937eb2141 100644 --- a/docs/add_ons.txt +++ b/docs/add_ons.txt @@ -17,7 +17,7 @@ admin The automatic Django administrative interface. For more information, see `Tutorial 2`_. -.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ +.. _Tutorial 2: ../tutorial2/ auth ==== @@ -26,7 +26,7 @@ Django's authentication framework. See the `authentication documentation`_. -.. _authentication documentation: http://www.djangoproject.com/documentation/authentication/ +.. _authentication documentation: ../authentication/ comments ======== @@ -46,7 +46,7 @@ A middleware for preventing Cross Site Request Forgeries See the `csrf documentation`_. -.. _csrf documentation: http://www.djangoproject.com/documentation/csrf/ +.. _csrf documentation: ../csrf/ formtools ========= @@ -137,7 +137,7 @@ A framework for managing simple "flat" HTML content in a database. See the `flatpages documentation`_. -.. _flatpages documentation: http://www.djangoproject.com/documentation/flatpages/ +.. _flatpages documentation: ../flatpages/ markup ====== @@ -157,7 +157,7 @@ A framework for managing redirects. See the `redirects documentation`_. -.. _redirects documentation: http://www.djangoproject.com/documentation/redirects/ +.. _redirects documentation: ../redirects/ sites ===== @@ -168,7 +168,7 @@ one or more sites. See the `sites documentation`_. -.. _sites documentation: http://www.djangoproject.com/documentation/sites/ +.. _sites documentation: ../sites/ sitemaps ======== @@ -177,7 +177,7 @@ A framework for generating Google sitemap XML files. See the `sitemaps documentation`_. -.. _sitemaps documentation: http://www.djangoproject.com/documentation/sitemaps/ +.. _sitemaps documentation: ../sitemaps/ syndication =========== @@ -186,7 +186,7 @@ A framework for generating syndication feeds, in RSS and Atom, quite easily. See the `syndication documentation`_. -.. _syndication documentation: http://www.djangoproject.com/documentation/syndication/ +.. _syndication documentation: ../syndication/ Other add-ons ============= diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index b85057924b..583cb96b39 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -65,7 +65,7 @@ are equivalent:: SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonOption DJANGO_SETTINGS_MODULE mysite.settings -.. _authentication system: http://www.djangoproject.com/documentation/authentication/ +.. _authentication system: ../authentication/ .. _Subversion: http://subversion.tigris.org/ .. _mod_dav: http://httpd.apache.org/docs/2.0/mod/mod_dav.html -.. _custom permissions: http://www.djangoproject.com/documentation/authentication/#custom-permissions +.. _custom permissions: ../authentication/#custom-permissions diff --git a/docs/api_stability.txt b/docs/api_stability.txt index 18885fbe63..508336e0ef 100644 --- a/docs/api_stability.txt +++ b/docs/api_stability.txt @@ -98,26 +98,26 @@ change: rewrite before Django 1.0. Even if the change isn't quite that drastic, there will at least be moderate changes. -.. _caching: http://www.djangoproject.com/documentation/cache/ -.. _custom template tags and libraries: http://www.djangoproject.com/documentation/templates_python/ -.. _database lookup: http://www.djangoproject.com/documentation/db_api/ -.. _django-admin utility: http://www.djangoproject.com/documentation/django_admin/ -.. _fastcgi integration: http://www.djangoproject.com/documentation/fastcgi/ -.. _flatpages: http://www.djangoproject.com/documentation/flatpages/ -.. _generic views: http://www.djangoproject.com/documentation/generic_views/ -.. _internationalization: http://www.djangoproject.com/documentation/i18n/ -.. _legacy database integration: http://www.djangoproject.com/documentation/legacy_databases/ -.. _model definition: http://www.djangoproject.com/documentation/model_api/ -.. _mod_python integration: http://www.djangoproject.com/documentation/modpython/ -.. _redirects: http://www.djangoproject.com/documentation/redirects/ -.. _request/response objects: http://www.djangoproject.com/documentation/request_response/ -.. _sending email: http://www.djangoproject.com/documentation/email/ -.. _sessions: http://www.djangoproject.com/documentation/sessions/ -.. _settings: http://www.djangoproject.com/documentation/settings/ -.. _syndication: http://www.djangoproject.com/documentation/syndication/ -.. _template language: http://www.djangoproject.com/documentation/templates/ -.. _transactions: http://www.djangoproject.com/documentation/transactions/ -.. _url dispatch: http://www.djangoproject.com/documentation/url_dispatch/ -.. _forms and validation: http://www.djangoproject.com/documentation/forms/ -.. _serialization: http://www.djangoproject.com/documentation/serialization/ -.. _authentication: http://www.djangoproject.com/documentation/authentication/ +.. _caching: ../cache/ +.. _custom template tags and libraries: ../templates_python/ +.. _database lookup: ../db_api/ +.. _django-admin utility: ../django_admin/ +.. _fastcgi integration: ../fastcgi/ +.. _flatpages: ../flatpages/ +.. _generic views: ../generic_views/ +.. _internationalization: ../i18n/ +.. _legacy database integration: ../legacy_databases/ +.. _model definition: ../model_api/ +.. _mod_python integration: ../modpython/ +.. _redirects: ../redirects/ +.. _request/response objects: ../request_response/ +.. _sending email: ../email/ +.. _sessions: ../sessions/ +.. _settings: ../settings/ +.. _syndication: ../syndication/ +.. _template language: ../templates/ +.. _transactions: ../transactions/ +.. _url dispatch: ../url_dispatch/ +.. _forms and validation: ../forms/ +.. _serialization: ../serialization/ +.. _authentication: ../authentication/ diff --git a/docs/authentication.txt b/docs/authentication.txt index 08565e13e1..ef30879ae0 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -144,8 +144,8 @@ custom methods: Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site doesn't allow profiles. -.. _Django model: http://www.djangoproject.com/documentation/model_api/ -.. _DEFAULT_FROM_EMAIL: http://www.djangoproject.com/documentation/settings/#default-from-email +.. _Django model: ../model_api/ +.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email Manager functions ~~~~~~~~~~~~~~~~~ @@ -271,8 +271,8 @@ previous section). You can tell them apart with ``is_authenticated()``, like so: else: # Do something for anonymous users. -.. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects -.. _session documentation: http://www.djangoproject.com/documentation/sessions/ +.. _request objects: ../request_response/#httprequest-objects +.. _session documentation: ../sessions/ How to log a user in -------------------- @@ -441,8 +441,8 @@ block:: {% endblock %} -.. _forms documentation: http://www.djangoproject.com/documentation/forms/ -.. _site framework docs: http://www.djangoproject.com/documentation/sites/ +.. _forms documentation: ../forms/ +.. _site framework docs: ../sites/ Limiting access to logged-in users that pass a test --------------------------------------------------- @@ -544,7 +544,7 @@ For example:: def limited_object_detail(*args, **kwargs): return object_detail(*args, **kwargs) -.. _generic view: http://www.djangoproject.com/documentation/generic_views/ +.. _generic view: ../generic_views/ Permissions =========== @@ -606,7 +606,7 @@ This example model creates three custom permissions:: The only thing this does is create those extra permissions when you run ``syncdb``. -.. _model Meta attribute: http://www.djangoproject.com/documentation/model_api/#meta-options +.. _model Meta attribute: ../model_api/#meta-options API reference ------------- @@ -645,7 +645,7 @@ The currently logged-in user and his/her permissions are made available in the setting contains ``"django.core.context_processors.auth"``, which is default. For more, see the `RequestContext docs`_. - .. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-requestcontext + .. _RequestContext docs: ../templates_python/#subclassing-context-requestcontext Users ----- @@ -691,7 +691,7 @@ Thus, you can check permissions in template ``{% if %}`` statements::

You don't have permission to do anything in the foo app.

{% endif %} -.. _template context: http://www.djangoproject.com/documentation/templates_python/ +.. _template context: ../templates_python/ Groups ====== @@ -756,7 +756,7 @@ scenes, so any messages will be deleted even if you don't display them. Finally, note that this messages framework only works with users in the user database. To send messages to anonymous users, use the `session framework`_. -.. _session framework: http://www.djangoproject.com/documentation/sessions/ +.. _session framework: ../sessions/ Other authentication sources ============================ diff --git a/docs/cache.txt b/docs/cache.txt index 1795345ed9..054d99819d 100644 --- a/docs/cache.txt +++ b/docs/cache.txt @@ -250,7 +250,7 @@ Additionally, ``CacheMiddleware`` automatically sets a few headers in each See the `middleware documentation`_ for more on middleware. -.. _`middleware documentation`: http://www.djangoproject.com/documentation/middleware/ +.. _`middleware documentation`: ../middleware/ The per-view cache ================== diff --git a/docs/contributing.txt b/docs/contributing.txt index 6ff0b038a3..d802d3eaf6 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -22,6 +22,9 @@ of the community, so there are many ways you can help Django's development: likely to be skeptical of large-scale suggestions without some code to back it up. + * Triage patches that have been submitted by other users. Please read + `Ticket triage`_ below, for details on the triage process. + That's all you need to know if you'd like to join the Django development community. The rest of this document describes the details of how our community works and how it handles bugs, mailing lists, and all the other minutiae of @@ -44,8 +47,10 @@ particular: * **Do** write complete, reproducible, specific bug reports. Include as much information as you possibly can, complete with code snippets, test - cases, etc. A minimal example that illustrates the bug in a nice small - test case is the best possible bug report. + cases, etc. This means including a clear, concise description of the + problem, and a clear set of instructions for replicating the problem. + A minimal example that illustrates the bug in a nice small test case + is the best possible bug report. * **Don't** use the ticket system to ask support questions. Use the `django-users`_ list, or the `#django`_ IRC channel for that. @@ -117,9 +122,99 @@ Patch style * Name the patch file with a ``.diff`` extension; this will let the ticket tracker apply correct syntax highlighting, which is quite helpful. - * Put the prefix "[patch] " before the title of your ticket. This will make - it obvious that the ticket includes a patch, and it will add the ticket - to the `list of tickets with patches`_. + * Check the "Has patch" box on the ticket details. This will make it + obvious that the ticket includes a patch, and it will add the ticket to + the `list of tickets with patches`_. + + * The code required to fix a problem or add a feature is an essential part + of a patch, but it is not the only part. A good patch should also include + a regression test to validate the behavior that has been fixed (and prevent + the problem from arising again). + + * If the code associated with a patch adds a new feature, or modifies behavior + of an existing feature, the patch should also contain documentation. + +Non-trivial patches +------------------- + +A "non-trivial" patch is one that is more than a simple bug fix. It's a patch +that introduces Django functionality and makes some sort of design decision. + +If you provide a non-trivial patch, include evidence that alternatives have +been discussed on `django-developers`_. If you're not sure whether your patch +should be considered non-trivial, just ask. + +Ticket triage +============= + +Unfortunately, not all bug reports in the `ticket tracker`_ provide all +the `required details`_. A number of tickets have patches, but those patches +don't meet all the requirements of a `good patch`_. + +One way to help out is to *triage* bugs that have been reported by other +users. A couple of dedicated volunteers work on this regularly, but more help +is always appreciated. + +Most of the workflow is based around the concept of a ticket's "triage stage". +This stage describes where in its lifetime a given ticket is at any time. +Along with a handful of flags, this field easily tells us what and who each +ticket is waiting on. + +Since a picture is worth a thousand words, let's start there: + +.. image:: http://media.djangoproject.com/img/doc/djangotickets.png + :height: 451 + :width: 590 + :alt: Django's ticket workflow + +We've got two roles here: + + * Core developers: people with commit access who make the decisions and + write the bulk of the code. + + * Ticket triagers: community members who keep track of tickets, making + sure the tickets are always categorized correctly. + +Second, note the four triage stages: + + 1. A ticket starts as "Unreviewed", meaning that a triager has yet to + examine the ticket and move it along. + + 2. "Design decision needed" means "this concept requires a design + decision," which should be discussed either in the ticket comments or on + django-developers. + + 3. Once a ticket is ruled to be approved for fixing, it's moved into the + "Accepted" stage. This stage is where all the real work gets done. + + 4. If a ticket has an associated patch (see below), a triager will review the + patch. If the patch is complete, it'll be marked as "ready for checkin" so + that a core developer knows to review and check in the patches. + +The second part of this workflow involves a set of flags the describe what the +ticket has or needs in order to be "ready for checkin": + + "Has patch" + The means the ticket has an associated patch_. These will be + reviewed to see if the patch is "good". + + "Needs documentation" + This flag is used for tickets with patches that need associated + documentation. Complete documentation of features is a prerequisite + before we can check a fix into the codebase. + + "Needs tests" + This flags the patch as needing associated unit tests. Again, this is a + required part of a valid patch. + + "Patch needs improvement" + This flag means that although the ticket *has* a patch, it's not quite + ready for checkin. This could mean the patch no longer applies + cleanly, or that the code doesn't live up to our standards. + +.. _required details: `Reporting bugs`_ +.. _good patch: `Patch style`_ +.. _patch: `Submitting patches`_ Submitting and maintaining translations ======================================= @@ -137,7 +232,7 @@ translated, here's what to do: `i18n documentation`_. .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ -.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ +.. _i18n documentation: ../i18n/ Coding style ============ @@ -262,7 +357,7 @@ The Django tests all use the testing infrastructure that ships with Django for testing applications. See `Testing Django applications`_ for an explanation of how to write new tests. -.. _Testing Django applications: http://www.djangoproject.com/documentation/testing/ +.. _Testing Django applications: ../testing/ Running the unit tests ---------------------- @@ -338,21 +433,63 @@ trunk more than once. Using branches -------------- -To test a given branch, you can simply check out the entire branch, like so:: +To use a branch, you'll need to do two things: + + * Get the branch's code through Subversion. + + * Point your Python ``site-packages`` directory at the branch's version of + the ``django`` package rather than the version you already have + installed. + +Getting the code from Subversion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get the latest version of a branch's code, check it out using Subversion:: svn co http://code.djangoproject.com/svn/django/branches// -Or, if you've got a working directory you'd like to switch to use a branch, -you can use:: +...where ```` is the branch's name. See the `list of branch names`_. - svn switch http://code.djangoproject.com/svn/django/branches// +Alternatively, you can automatically convert an existing directory of the +Django source code as long as you've checked it out via Subversion. To do the +conversion, execute this command from within your ``django`` directory:: -...in the root of your Django sandbox (the directory that contains ``django``, -``docs``, and ``tests``). + svn switch http://code.djangoproject.com/svn/django/branches// The advantage of using ``svn switch`` instead of ``svn co`` is that the ``switch`` command retains any changes you might have made to your local copy -of the code. It attempts to merge those changes into the "switched" code. +of the code. It attempts to merge those changes into the "switched" code. The +disadvantage is that it may cause conflicts with your local changes if the +"switched" code has altered the same lines of code. + +(Note that if you use ``svn switch``, you don't need to point Python at the new +version, as explained in the next section.) + +.. _list of branch names: http://code.djangoproject.com/browser/django/branches + +Pointing Python at the new Django version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you've retrieved the branch's code, you'll need to change your Python +``site-packages`` directory so that it points to the branch version of the +``django`` directory. (The ``site-packages`` directory is somewhere such as +``/usr/lib/python2.4/site-packages`` or +``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.) + +The simplest way to do this is by renaming the old ``django`` directory to +``django.OLD`` and moving the trunk version of the code into the directory +and calling it ``django``. + +Alternatively, you can use a symlink called ``django`` that points to the +location of the branch's ``django`` package. If you want to switch back, just +change the symlink to point to the old code. + +If you're using Django 0.95 or earlier and installed it using +``python setup.py install``, you'll have a directory called something like +``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file +``setuptools.pth`` and remove the line that references the Django ``.egg`` +file. Then copy the branch's version of the ``django`` directory into +``site-packages``. Official releases ================= @@ -457,8 +594,7 @@ requests for commit access are potential flame-war starters, and will be ignored .. _search the tracker: http://code.djangoproject.com/search .. _django-users: http://groups.google.com/group/django-users .. _`#django`: irc://irc.freenode.net/django -.. _list of tickets with patches: http://code.djangoproject.com/report/12 +.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority .. _PEP 8: http://www.python.org/peps/pep-0008.html -.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases diff --git a/docs/csrf.txt b/docs/csrf.txt index 218b43a61a..c12dd1d116 100644 --- a/docs/csrf.txt +++ b/docs/csrf.txt @@ -1,9 +1,9 @@ ===================================== -Cross Site Request Forgery Protection +Cross Site Request Forgery protection ===================================== -The CsrfMiddleware class provides easy-to-use protection against -`Cross Site Request Forgeries`_. This type of attack occurs when a malicious +The CsrfMiddleware class provides easy-to-use protection against +`Cross Site Request Forgeries`_. This type of attack occurs when a malicious web site creates a link or form button that is intended to perform some action on your web site, using the credentials of a logged-in user who is tricked into clicking on the link in their browser. @@ -12,12 +12,12 @@ The first defense against CSRF attacks is to ensure that GET requests are side-effect free. POST requests can then be protected by adding this middleware into your list of installed middleware. - .. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF How to use it ============= -Add the middleware ``'django.contrib.csrf.middleware.CsrfMiddleware'`` to + +Add the middleware ``'django.contrib.csrf.middleware.CsrfMiddleware'`` to your list of middleware classes, ``MIDDLEWARE_CLASSES``. It needs to process the response after the SessionMiddleware, so must come before it in the list. It also must process the response before things like compression @@ -25,16 +25,17 @@ happen to the response, so it must come after GZipMiddleware in the list. How it works ============ + CsrfMiddleware does two things: -1. It modifies outgoing requests by adding a hidden form field to all - 'POST' forms, with the name 'csrfmiddlewaretoken' and a value which is - a hash of the session ID plus a secret. If there is no session ID set, - this modification of the response isn't done, so there is very little +1. It modifies outgoing requests by adding a hidden form field to all + 'POST' forms, with the name 'csrfmiddlewaretoken' and a value which is + a hash of the session ID plus a secret. If there is no session ID set, + this modification of the response isn't done, so there is very little performance penalty for those requests that don't have a session. -2. On all incoming POST requests that have the session cookie set, it - checks that the 'csrfmiddlewaretoken' is present and correct. If it +2. On all incoming POST requests that have the session cookie set, it + checks that the 'csrfmiddlewaretoken' is present and correct. If it isn't, the user will get a 403 error. This ensures that only forms that have originated from your web site @@ -43,26 +44,26 @@ can be used to POST data back. It deliberately only targets HTTP POST requests (and the corresponding POST forms). GET requests ought never to have side effects (if you are using HTTP GET and POST correctly), and so a CSRF attack with a GET -request will always be harmless. +request will always be harmless. POST requests that are not accompanied by a session cookie are not protected, but they do not need to be protected, since the 'attacking' web site could make these kind of requests anyway. -The Content-Type is checked before modifying the response, and only +The Content-Type is checked before modifying the response, and only pages that are served as 'text/html' or 'application/xml+xhtml' are modified. Limitations =========== + CsrfMiddleware requires Django's session framework to work. If you have a custom authentication system that manually sets cookies and the like, it won't help you. -If your app creates HTML pages and forms in some unusual way, (e.g. -it sends fragments of HTML in javascript document.write statements) -you might bypass the filter that adds the hidden field to the form, +If your app creates HTML pages and forms in some unusual way, (e.g. +it sends fragments of HTML in javascript document.write statements) +you might bypass the filter that adds the hidden field to the form, in which case form submission will always fail. It may still be possible to use the middleware, provided you can find some way to get the -CSRF token and ensure that is included when your form is submitted. - +CSRF token and ensure that is included when your form is submitted. \ No newline at end of file diff --git a/docs/db-api.txt b/docs/db-api.txt index 2f0c8b0589..99bb30054b 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -143,9 +143,9 @@ or ``UPDATE`` SQL statements. Specifically, when you call ``save()``, Django follows this algorithm: * If the object's primary key attribute is set to a value that evaluates to - ``False`` (such as ``None`` or the empty string), Django executes a - ``SELECT`` query to determine whether a record with the given primary key - already exists. + ``True`` (i.e., a value other than ``None`` or the empty string), Django + executes a ``SELECT`` query to determine whether a record with the given + primary key already exists. * If the record with the given primary key does already exist, Django executes an ``UPDATE`` query. * If the object's primary key attribute is *not* set, or if it's set but a @@ -525,6 +525,21 @@ Examples:: [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') [datetime.datetime(2005, 3, 20)] + +``none()`` +~~~~~~~~~~ + +**New in Django development version** + +Returns an ``EmptyQuerySet`` -- a ``QuerySet`` that always evaluates to +an empty list. This can be used in cases where you know that you should +return an empty result set and your caller is expecting a ``QuerySet`` +object (instead of returning an empty list, for example.) + +Examples:: + + >>> Entry.objects.none() + [] ``select_related()`` ~~~~~~~~~~~~~~~~~~~~ @@ -1704,6 +1719,46 @@ For every ``ImageField``, the object will have ``get_FOO_height()`` and ``get_FOO_width()`` methods, where ``FOO`` is the name of the field. This returns the height (or width) of the image, as an integer, in pixels. +Shortcuts +========= + +As you develop views, you will discover a number of common idioms in the +way you use the database API. Django encodes some of these idioms as +shortcuts that can be used to simplify the process of writing views. + +get_object_or_404() +------------------- + +One common idiom to use ``get()`` and raise ``Http404`` if the +object doesn't exist. This idiom is captured by ``get_object_or_404()``. +This function takes a Django model as its first argument and an +arbitrary number of keyword arguments, which it passes to the manager's +``get()`` function. It raises ``Http404`` if the object doesn't +exist. For example:: + + # Get the Entry with a primary key of 3 + e = get_object_or_404(Entry, pk=3) + +When you provide a model to this shortcut function, the default manager +is used to execute the underlying ``get()`` query. If you don't want to +use the default manager, or you want to search a list of related objects, +you can provide ``get_object_or_404()`` with a manager object, instead. +For example:: + + # Get the author of blog instance `e` with a name of 'Fred' + a = get_object_or_404(e.authors, name='Fred') + + # Use a custom manager 'recent_entries' in the search for an + # entry with a primary key of 3 + e = get_object_or_404(Entry.recent_entries, pk=3) + +get_list_or_404() +----------------- + +``get_list_or_404`` behaves the same was as ``get_object_or_404()`` +-- except the it uses using ``filter()`` instead of ``get()``. It raises +``Http404`` if the list is empty. + Falling back to raw SQL ======================= diff --git a/docs/design_philosophies.txt b/docs/design_philosophies.txt index 7fdc7ea01b..72aa8ade95 100644 --- a/docs/design_philosophies.txt +++ b/docs/design_philosophies.txt @@ -186,7 +186,7 @@ code. This is the philosophy behind `template inheritance`_. -.. _template inheritance: http://www.djangoproject.com/documentation/templates/#template-inheritance +.. _template inheritance: ../templates/#template-inheritance Be decoupled from HTML ---------------------- diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 7f9682b443..310e8dff0e 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -53,7 +53,7 @@ Prints the admin-index template snippet for the given appnames. Use admin-index template snippets if you want to customize the look and feel of your admin's index page. See `Tutorial 2`_ for more information. -.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/ +.. _Tutorial 2: ../tutorial2/ createcachetable [tablename] ---------------------------- @@ -61,7 +61,7 @@ createcachetable [tablename] Creates a cache table named ``tablename`` for use with the database cache backend. See the `cache documentation`_ for more information. -.. _cache documentation: http://www.djangoproject.com/documentation/cache/ +.. _cache documentation: ../cache/ dbshell ------- @@ -190,7 +190,7 @@ By default, the development server doesn't serve any static files for your site you want to configure Django to serve static media, read the `serving static files`_ documentation. -.. _serving static files: http://www.djangoproject.com/documentation/static_files/ +.. _serving static files: ../static_files/ Turning off auto-reload ~~~~~~~~~~~~~~~~~~~~~~~ @@ -253,6 +253,8 @@ files are piped directly into the database after all of the models' table-creation statements have been executed. Use this SQL hook to populate tables with any necessary initial records, SQL functions or test data. +Note that the order in which the SQL files are processed is undefined. + sqlreset [appname appname ...] -------------------------------------- @@ -380,7 +382,7 @@ Example usage:: django-admin.py syncdb --verbosity=2 -Verbosity determines the amount of notification and debug information that +Verbosity determines the amount of notification and debug information that will be printed to the console. '0' is no output, '1' is normal output, and `2` is verbose output. diff --git a/docs/email.txt b/docs/email.txt index 37a4f38a5e..1edce88cef 100644 --- a/docs/email.txt +++ b/docs/email.txt @@ -101,9 +101,9 @@ The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting` This method exists for convenience and readability. -.. _ADMINS setting: http://www.djangoproject.com/documentation/settings/#admins -.. _EMAIL_SUBJECT_PREFIX setting: http://www.djangoproject.com/documentation/settings/#email-subject-prefix -.. _SERVER_EMAIL setting: http://www.djangoproject.com/documentation/settings/#server-email +.. _ADMINS setting: ../settings/#admins +.. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix +.. _SERVER_EMAIL setting: ../settings/#server-email mail_managers() function ======================== @@ -114,7 +114,7 @@ Here's the definition:: mail_managers(subject, message, fail_silently=False) -.. _MANAGERS setting: http://www.djangoproject.com/documentation/settings/#managers +.. _MANAGERS setting: ../settings/#managers Examples ======== diff --git a/docs/faq.txt b/docs/faq.txt index eaccc6be43..33e8ef01b4 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -63,7 +63,7 @@ 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 `cache framework`_. -.. _`cache framework`: http://www.djangoproject.com/documentation/cache/ +.. _`cache framework`: ../cache/ Who's behind this? ------------------ @@ -191,7 +191,7 @@ 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/ +.. _design philosophies page: ../design_philosophies/ Do you have any of those nifty "screencast" things? --------------------------------------------------- @@ -277,9 +277,9 @@ How do I get started? 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/ +.. _`installation guide`: ../install/ +.. _tutorial: ../tutorial1/ +.. _documentation: ../ .. _ask questions: http://www.djangoproject.com/community/ How do I fix the "install a later version of setuptools" error? @@ -337,7 +337,7 @@ If you just want to play around and develop things on your local computer, use the development Web server that comes with Django. Things should Just Work. .. _WSGI: http://www.python.org/peps/pep-0333.html -.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ +.. _How to use Django with FastCGI: ../fastcgi/ .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements How do I install mod_python on Windows? @@ -464,7 +464,7 @@ 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/ +.. _`Integrating with a legacy database`: ../legacy_databases/ If I make changes to a model, how do I update the database? ----------------------------------------------------------- @@ -511,7 +511,7 @@ type, create an initial data file and put something like this in it:: As explained in the `SQL initial data file`_ documentation, this SQL file can contain arbitrary SQL, so you can make any sorts of changes you need to make. -.. _SQL initial data file: http://www.djangoproject.com/documentation/model_api/#providing-initial-sql-data +.. _SQL initial data file: ../model_api/#providing-initial-sql-data Why is Django leaking memory? ----------------------------- @@ -592,7 +592,7 @@ My admin-site CSS and images showed up fine using the development server, but th See `serving the admin files`_ in the "How to use Django with mod_python" documentation. -.. _serving the admin files: http://www.djangoproject.com/documentation/modpython/#serving-the-admin-files +.. _serving the admin files: ../modpython/#serving-the-admin-files My "list_filter" contains a ManyToManyField, but the filter doesn't display. ---------------------------------------------------------------------------- @@ -630,7 +630,7 @@ 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 `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/ +.. _`guide to the CSS used in the admin`: ../admin_css/ How do I create users without having to edit password hashes? ------------------------------------------------------------- @@ -640,7 +640,7 @@ development version, where this problem was fixed on Aug. 4, 2006. You can also use the Python API. See `creating users`_ for full info. -.. _creating users: http://www.djangoproject.com/documentation/authentication/#creating-users +.. _creating users: ../authentication/#creating-users Contributing code ================= @@ -651,7 +651,7 @@ 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 `Contributing to Django`_. -.. _Contributing to Django: http://www.djangoproject.com/documentation/contributing/ +.. _Contributing to Django: ../contributing/ I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch? -------------------------------------------------------------------------------------------- diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index e2f4e933b4..b61df49190 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -17,7 +17,7 @@ served with no startup time. Unlike mod_python (or `mod_perl`_), a FastCGI process doesn't run inside the Web server process, but in a separate, persistent process. -.. _current preferred setup: http://www.djangoproject.com/documentation/modpython/ +.. _current preferred setup: ../modpython/ .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ diff --git a/docs/flatpages.txt b/docs/flatpages.txt index 06979f7a9a..cb910e812d 100644 --- a/docs/flatpages.txt +++ b/docs/flatpages.txt @@ -29,8 +29,8 @@ To install the flatpages app, follow these steps: to your MIDDLEWARE_CLASSES_ setting. 3. Run the command ``manage.py syncdb``. -.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps -.. _MIDDLEWARE_CLASSES: http://www.djangoproject.com/documentation/settings/#middleware-classes +.. _INSTALLED_APPS: ../settings/#installed-apps +.. _MIDDLEWARE_CLASSES: ../settings/#middleware-classes How it works ============ @@ -63,9 +63,9 @@ resort. For more on middleware, read the `middleware docs`_. -.. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id -.. _RequestContext: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext -.. _middleware docs: http://www.djangoproject.com/documentation/middleware/ +.. _SITE_ID: ../settings/#site-id +.. _RequestContext: ../templates_python/#subclassing-context-djangocontext +.. _middleware docs: ../middleware/ How to add, change and delete flatpages ======================================= @@ -84,9 +84,9 @@ Flatpages are represented by a standard `Django model`_, which lives in `django/contrib/flatpages/models.py`_. You can access flatpage objects via the `Django database API`_. -.. _Django model: http://www.djangoproject.com/documentation/model_api/ +.. _Django model: ../model_api/ .. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py -.. _Django database API: http://www.djangoproject.com/documentation/db_api/ +.. _Django database API: ../db_api/ Flatpage templates ================== diff --git a/docs/forms.txt b/docs/forms.txt index ff192a4717..3fa11fea64 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -2,15 +2,27 @@ Forms, fields, and manipulators =============================== +Forwards-compatibility note +=========================== + +The legacy forms/manipulators system described in this document is going to be +replaced in the next Django release. If you're starting from scratch, we +strongly encourage you not to waste your time learning this. Instead, learn and +use the django.newforms system, which we have begun to document in the +`newforms documentation`_. + +If you have legacy form/manipulator code, read the "Migration plan" section in +that document to understand how we're making the switch. + +.. _newforms documentation: ../newforms/ + +Introduction +============ + Once you've got a chance to play with Django's admin interface, you'll probably wonder if the fantastic form validation framework it uses is available to user code. It is, and this document explains how the framework works. - .. admonition:: A note to the lazy - - If all you want to do is present forms for a user to create and/or - update a given object, you may be able to use `generic views`_. - We'll take a top-down approach to examining Django's form validation framework, because much of the time you won't need to use the lower-level APIs. Throughout this document, we'll be working with the following model, a "place" object:: @@ -41,17 +53,17 @@ this document, we'll be working with the following model, a "place" object:: Defining the above class is enough to create an admin interface to a ``Place``, but what if you want to allow public users to submit places? -Manipulators -============ +Automatic Manipulators +====================== The highest-level interface for object creation and modification is the -**Manipulator** framework. A manipulator is a utility class tied to a given -model that "knows" how to create or modify instances of that model and how to -validate data for the object. Manipulators come in two flavors: -``AddManipulators`` and ``ChangeManipulators``. Functionally they are quite -similar, but the former knows how to create new instances of the model, while -the latter modifies existing instances. Both types of classes are automatically -created when you define a new class:: +**automatic Manipulator** framework. An automatic manipulator is a utility +class tied to a given model that "knows" how to create or modify instances of +that model and how to validate data for the object. Automatic Manipulators come +in two flavors: ``AddManipulators`` and ``ChangeManipulators``. Functionally +they are quite similar, but the former knows how to create new instances of the +model, while the latter modifies existing instances. Both types of classes are +automatically created when you define a new class:: >>> from mysite.myapp.models import Place >>> Place.AddManipulator @@ -653,6 +665,6 @@ fails. If no message is passed in, a default message is used. the executable specified in the ``JING_PATH`` setting (see the settings_ document for more details). -.. _`generic views`: http://www.djangoproject.com/documentation/generic_views/ -.. _`models API`: http://www.djangoproject.com/documentation/model_api/ -.. _settings: http://www.djangoproject.com/documentation/settings/ +.. _`generic views`: ../generic_views/ +.. _`models API`: ../model_api/ +.. _settings: ../settings/ diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 1736770a20..23f40acb24 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -71,7 +71,7 @@ are first evaluated, so if you want to pass in a QuerySet via ``extra_context`` that is always fresh you need to wrap it in a function or lambda that returns the QuerySet. -.. _database API docs: http://www.djangoproject.com/documentation/db_api/ +.. _database API docs: ../db_api/ "Simple" generic views ====================== @@ -99,7 +99,7 @@ which is a dictionary of the parameters captured in the URL. dictionary is callable, the generic view will call it just before rendering the template. (**This is new in the Django development version.**) - + **Example:** Given the following URL patterns:: @@ -205,11 +205,11 @@ If ``template_name`` isn't specified, this view will use the template ``/_archive.html`` by default, where: * ```` is your model's name in all lowercase. For a model - ``StaffMember``, that'd be ``staffmember``. + ``StaffMember``, that'd be ``staffmember``. * ```` is the right-most part of the full Python path to - your model's app. For example, if your model lives in - ``apps/blog/models.py``, that'd be ``blog``. + your model's app. For example, if your model lives in + ``apps/blog/models.py``, that'd be ``blog``. **Template context:** @@ -223,7 +223,7 @@ In addition to ``extra_context``, the template's context will be: by ``date_field``. For example, if ``num_latest`` is ``10``, then ``latest`` will be a list of the latest 10 objects in ``queryset``. -.. _RequestContext docs: http://www.djangoproject.com/documentation/templates_python/#subclassing-context-djangocontext +.. _RequestContext docs: ../templates_python/#subclassing-context-djangocontext ``django.views.generic.date_based.archive_year`` ------------------------------------------------ @@ -266,9 +266,9 @@ to ``True``. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. * ``make_object_list``: A boolean specifying whether to retrieve the full list of objects for this year and pass those to the template. If ``True``, @@ -360,9 +360,9 @@ date in the *future* are not displayed unless you set ``allow_future`` to the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -441,9 +441,9 @@ in the *future* are not displayed unless you set ``allow_future`` to ``True``. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -526,9 +526,9 @@ you set ``allow_future`` to ``True``. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -638,7 +638,7 @@ future, the view will throw a 404 error by default, unless you set the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. + to use in the template context. By default, this is ``'object'``. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -710,9 +710,9 @@ A page representing a list of objects. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. The - view will append ``'_list'`` to the value of this parameter in - determining the variable's name. + to use in the template context. By default, this is ``'object'``. The + view will append ``'_list'`` to the value of this parameter in + determining the variable's name. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -824,7 +824,7 @@ A page representing an individual object. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. + to use in the template context. By default, this is ``'object'``. * ``mimetype``: The MIME type to use for the resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE`` setting. @@ -902,7 +902,7 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``form``: A ``django.forms.FormWrapper`` instance representing the form + * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form for editing the object. This lets you refer to form fields easily in the template system. @@ -916,8 +916,8 @@ In addition to ``extra_context``, the template's context will be: See the `manipulator and formfield documentation`_ for more information about using ``FormWrapper`` objects in templates. -.. _authentication system: http://www.djangoproject.com/documentation/authentication/ -.. _manipulator and formfield documentation: http://www.djangoproject.com/documentation/forms/ +.. _authentication system: ../authentication/ +.. _manipulator and formfield documentation: ../forms/ ``django.views.generic.create_update.update_object`` ---------------------------------------------------- @@ -973,7 +973,7 @@ object. This uses the automatic manipulators that come with Django models. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. + to use in the template context. By default, this is ``'object'``. **Template name:** @@ -984,7 +984,7 @@ If ``template_name`` isn't specified, this view will use the template In addition to ``extra_context``, the template's context will be: - * ``form``: A ``django.forms.FormWrapper`` instance representing the form + * ``form``: A ``django.oldforms.FormWrapper`` instance representing the form for editing the object. This lets you refer to form fields easily in the template system. @@ -1054,7 +1054,7 @@ contain a form that POSTs to the same URL. the view's template. See the `RequestContext docs`_. * ``template_object_name``: Designates the name of the template variable - to use in the template context. By default, this is ``'object'``. + to use in the template context. By default, this is ``'object'``. **Template name:** diff --git a/docs/i18n.txt b/docs/i18n.txt index 4d0d92b082..d7f5db6861 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -53,7 +53,7 @@ internationalization machinery. See the `documentation for USE_I18N`_. You'll probably also want to remove ``'django.core.context_processors.i18n'`` from your ``TEMPLATE_CONTEXT_PROCESSORS`` setting. -.. _documentation for USE_I18N: http://www.djangoproject.com/documentation/settings/#use-i18n +.. _documentation for USE_I18N: ../settings/#use-i18n How to specify translation strings ================================== @@ -175,7 +175,7 @@ class, though:: verbose_name = _('my thing') verbose_name_plural = _('mythings') -.. _Django models: http://www.djangoproject.com/documentation/model_api/ +.. _Django models: ../model_api/ Pluralization ~~~~~~~~~~~~~ @@ -274,7 +274,7 @@ translation string. Example:: In this case, both the tag and the filter will see the already-translated string, so they don't need to be aware of translations. -.. _Django templates: http://www.djangoproject.com/documentation/templates_python/ +.. _Django templates: ../templates_python/ How to create language files ============================ @@ -394,7 +394,7 @@ That's it. Your translations are ready for use. please let us know! See `Submitting and maintaining translations`_ for the steps to take. - .. _Submitting and maintaining translations: http://www.djangoproject.com/documentation/contributing/ + .. _Submitting and maintaining translations: ../contributing/ How Django discovers language preference ======================================== @@ -472,7 +472,7 @@ Notes: selection to German and English (and any sublanguage, like de-ch or en-us). - .. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages + .. _LANGUAGES setting: ../settings/#languages * If you define a custom ``LANGUAGES`` setting, as explained in the previous bullet, it's OK to mark the languages as translation strings @@ -530,10 +530,10 @@ Note that, with static (middleware-less) translation, the language is in ``settings.LANGUAGE_CODE``, while with dynamic (middleware) translation, it's in ``request.LANGUAGE_CODE``. -.. _settings file: http://www.djangoproject.com/documentation/settings/ -.. _middleware documentation: http://www.djangoproject.com/documentation/middleware/ -.. _session: http://www.djangoproject.com/documentation/sessions/ -.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects +.. _settings file: ../settings/ +.. _middleware documentation: ../middleware/ +.. _session: ../sessions/ +.. _request object: ../request_response/#httprequest-objects The ``set_language`` redirect view ================================== @@ -599,7 +599,7 @@ message file. The choice is yours. of the settings file to determine this, and a settings file doesn't exist if you're manually configuring your settings.) -.. _settings documentation: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable +.. _settings documentation: ../settings/#using-settings-without-the-django-settings-module-environment-variable All message file repositories are structured the same way. They are: diff --git a/docs/install.txt b/docs/install.txt index ff8e1a8318..89a1415f5a 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -38,7 +38,7 @@ each platform. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _WSGI: http://www.python.org/peps/pep-0333.html -.. _How to use Django with mod_python: http://www.djangoproject.com/documentation/modpython/ +.. _How to use Django with mod_python: ../modpython/ .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements Get your database running @@ -113,14 +113,14 @@ latest bug fixes and improvements, follow these instructions: svn co http://code.djangoproject.com/svn/django/trunk/django c:\Python24\lib\site-packages\django -4. Copy the file ``django_src/django/bin/django-admin.py`` to somewhere on your +3. Copy the file ``django_src/django/bin/django-admin.py`` to somewhere on your system path, such as ``/usr/local/bin`` (Unix) or ``C:\Python24\Scripts`` (Windows). This step simply lets you type ``django-admin.py`` from within any directory, rather than having to qualify the command with the full path to the file. You *don't* have to run ``python setup.py install``, because that command -takes care of steps 3 and 4 for you. +takes care of steps 2 and 3 for you. When you want to update your copy of the Django source code, just run the command ``svn update`` from within the ``django`` directory. When you do this, diff --git a/docs/legacy_databases.txt b/docs/legacy_databases.txt index 66cb1a2ef4..8230c11f61 100644 --- a/docs/legacy_databases.txt +++ b/docs/legacy_databases.txt @@ -9,7 +9,7 @@ utilities to automate as much of this process as possible. This document assumes you know the Django basics, as covered in the `official tutorial`_. -.. _official tutorial: http://www.djangoproject.com/documentation/tutorial1/ +.. _official tutorial: ../tutorial1/ Give Django your database parameters ==================================== @@ -22,18 +22,16 @@ what the name of the database is. Do that by editing these settings in your * `DATABASE_ENGINE`_ * `DATABASE_USER`_ * `DATABASE_PASSWORD`_ - * `DATABASE_NAME`_ * `DATABASE_HOST`_ * `DATABASE_PORT`_ -.. _settings file: http://www.djangoproject.com/documentation/settings/ -.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name -.. _DATABASE_ENGINE: http://www.djangoproject.com/documentation/settings/#database-engine -.. _DATABASE_USER: http://www.djangoproject.com/documentation/settings/#database-user -.. _DATABASE_PASSWORD: http://www.djangoproject.com/documentation/settings/#database-password -.. _DATABASE_NAME: http://www.djangoproject.com/documentation/settings/#database-name -.. _DATABASE_HOST: http://www.djangoproject.com/documentation/settings/#database-host -.. _DATABASE_PORT: http://www.djangoproject.com/documentation/settings/#database-port +.. _settings file: ../settings/ +.. _DATABASE_NAME: ../settings/#database-name +.. _DATABASE_ENGINE: ../settings/#database-engine +.. _DATABASE_USER: ../settings/#database-user +.. _DATABASE_PASSWORD: ../settings/#database-password +.. _DATABASE_HOST: ../settings/#database-host +.. _DATABASE_PORT: ../settings/#database-port Auto-generate the models ======================== @@ -54,7 +52,7 @@ Once you've cleaned up your models, name the file ``models.py`` and put it in the Python package that holds your app. Then add the app to your ``INSTALLED_APPS`` setting. -.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/ +.. _django-admin.py documentation: ../django_admin/ Install the core Django tables ============================== diff --git a/docs/middleware.txt b/docs/middleware.txt index efc4d89569..7635442a5c 100644 --- a/docs/middleware.txt +++ b/docs/middleware.txt @@ -47,7 +47,7 @@ Enables site-wide cache. If this is enabled, each Django-powered page will be cached for as long as the ``CACHE_MIDDLEWARE_SECONDS`` setting defines. See the `cache documentation`_. -.. _`cache documentation`: http://www.djangoproject.com/documentation/cache/#the-per-site-cache +.. _`cache documentation`: ../cache/#the-per-site-cache django.middleware.common.CommonMiddleware ----------------------------------------- @@ -106,9 +106,10 @@ django.middleware.http.SetRemoteAddrFromForwardedFor **New in Django development version** -Sets ``request['REMOTE_ADDR']`` based on ``request.['HTTP_X_FORWARDED_FOR']``, -if the latter is set. This is useful if you're sitting behind a reverse proxy -that causes each request's ``REMOTE_ADDR`` to be set to ``127.0.0.1``. +Sets ``request.META['REMOTE_ADDR']`` based on +``request.META['HTTP_X_FORWARDED_FOR']``, if the latter is set. This is useful +if you're sitting behind a reverse proxy that causes each request's +``REMOTE_ADDR`` to be set to ``127.0.0.1``. **Important note:** This does NOT validate ``HTTP_X_FORWARDED_FOR``. If you're not behind a reverse proxy that sets ``HTTP_X_FORWARDED_FOR`` automatically, do @@ -122,7 +123,7 @@ django.contrib.sessions.middleware.SessionMiddleware Enables session support. See the `session documentation`_. -.. _`session documentation`: http://www.djangoproject.com/documentation/sessions/ +.. _`session documentation`: ../sessions/ django.contrib.auth.middleware.AuthenticationMiddleware ------------------------------------------------------- @@ -130,7 +131,7 @@ django.contrib.auth.middleware.AuthenticationMiddleware Adds the ``user`` attribute, representing the currently-logged-in user, to every incoming ``HttpRequest`` object. See `Authentication in Web requests`_. -.. _Authentication in Web requests: http://www.djangoproject.com/documentation/authentication/#authentication-in-web-requests +.. _Authentication in Web requests: ../authentication/#authentication-in-web-requests django.middleware.transaction.TransactionMiddleware --------------------------------------------------- @@ -146,7 +147,7 @@ the same transaction control as the view functions. See the `transaction management documentation`_. -.. _`transaction management documentation`: http://www.djangoproject.com/documentation/transactions/ +.. _`transaction management documentation`: ../transactions/ Writing your own middleware =========================== diff --git a/docs/model-api.txt b/docs/model-api.txt index 1aa8c811f4..8abd88f7ec 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -94,7 +94,7 @@ Django places only two restrictions on model field names: the way Django's query lookup syntax works. For example:: class Example(models.Model): - foo__bar = models.IntegerField() 'foo__bar' has two underscores! + foo__bar = models.IntegerField() # 'foo__bar' has two underscores! These limitations can be worked around, though, because your field name doesn't necessarily have to match your database column name. See `db_column`_ below. @@ -874,6 +874,10 @@ the relationship should work. All are optional: force Django to add the descriptor for the reverse relationship, allowing ``ManyToMany`` relationships to be non-symmetrical. + + ``db_table`` The name of the table to create for storing the many-to-many + data. If this is not provided, Django will assume a default + name based upon the names of the two tables being joined. ======================= ============================================================ @@ -1268,6 +1272,24 @@ A few special cases to note about ``list_display``: return '%s %s' % (self.color_code, self.first_name, self.last_name) colored_name.allow_tags = True + * If the string given is a method of the model that returns True or False + Django will display a pretty "on" or "off" icon if you give the method a + ``boolean`` attribute whose value is ``True``. + + Here's a full example model:: + + class Person(models.Model): + first_name = models.CharField(maxlength=50) + birthday = models.DateField() + + class Admin: + list_display = ('name', 'born_in_fifties') + + def born_in_fifties(self): + return self.birthday.strftime('%Y')[:3] == 5 + born_in_fifties.boolean = True + + * The ``__str__()`` method is just as valid in ``list_display`` as any other model method, so it's perfectly OK to do this:: @@ -1390,7 +1412,10 @@ This should be set to a list of field names that will be searched whenever somebody submits a search query in that text box. These fields should be some kind of text field, such as ``CharField`` or -``TextField``. +``TextField``. You can also perform a related lookup on a ``ForeignKey`` with +the lookup API "follow" notation:: + + search_fields = ['foreign_key__related_fieldname'] When somebody does a search in the admin search box, Django splits the search query into words and returns all objects that contain each of the words, case diff --git a/docs/modpython.txt b/docs/modpython.txt index 5177abf728..2c999753c7 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -20,7 +20,7 @@ You may also be interested in `How to use Django with FastCGI`_. .. _mod_perl: http://perl.apache.org/ .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html -.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ +.. _How to use Django with FastCGI: ../fastcgi/ Basic configuration =================== diff --git a/docs/newforms.txt b/docs/newforms.txt index 9bfbc75ee7..063f686ed5 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -2,9 +2,9 @@ The newforms library ==================== -``django.newforms`` is a new replacement for ``django.forms``, the old Django -form/manipulator/validation framework. This document explains how to use this -new form library. +``django.newforms`` is Django's fantastic new form-handling library. It's a +replacement for ``django.forms``, the old form/manipulator/validation +framework. This document explains how to use this new library. Migration plan ============== @@ -13,18 +13,23 @@ Migration plan -- i.e., it's not available in the Django 0.95 release. For the next Django release, our plan is to do the following: - * Move the current ``django.forms`` to ``django.oldforms``. This will allow - for an eased migration of form code. You'll just have to change your - import statements:: + * As of revision [4208], we've copied the current ``django.forms`` to + ``django.oldforms``. This allows you to upgrade your code *now* rather + than waiting for the backwards-incompatible change and rushing to fix + your code after the fact. Just change your import statements like this:: from django import forms # old from django import oldforms as forms # new - * Move the current ``django.newforms`` to ``django.forms``. + * At an undecided future date, we will move the current ``django.newforms`` + to ``django.forms``. This will be a backwards-incompatible change, and + anybody who is still using the old version of ``django.forms`` at that + time will need to change their import statements, as described in the + previous bullet. * We will remove ``django.oldforms`` in the release *after* the next Django release -- the release that comes after the release in which we're - creating ``django.oldforms``. + creating the new ``django.forms``. With this in mind, we recommend you use the following import statement when using ``django.newforms``:: @@ -46,9 +51,14 @@ too messy. The choice is yours. Overview ======== -As the ``django.forms`` system before it, ``django.newforms`` is intended to -handle HTML form display, validation and redisplay. It's what you use if you -want to perform server-side validation for an HTML form. +As with the ``django.forms`` ("manipulators") system before it, ``django.newforms`` +is intended to handle HTML form display, validation and redisplay. It's what +you use if you want to perform server-side validation for an HTML form. + +For example, if your Web site has a contact form that visitors can use to +send you e-mail, you'd use this library to implement the display of the HTML +form fields, along with the form validation. Any time you need to use an HTML +``
``, you can use this library. The library deals with these concepts: @@ -62,13 +72,751 @@ The library deals with these concepts: * **Form** -- A collection of fields that knows how to validate itself and display itself as HTML. +The library is decoupled from the other Django components, such as the database +layer, views and templates. It relies only on Django settings, a couple of +``django.utils`` helper functions and Django's internationalization hooks (but +you're not required to be using internationalization features to use this +library). +Form objects +============ -Using forms with templates -========================== +The primary way of using the ``newforms`` library is to create a form object. +Do this by subclassing ``django.newforms.Form`` and specifying the form's +fields, in a declarative style that you'll be familiar with if you've used +Django database models. In this section, we'll iteratively develop a form +object that you might use to implement "contact me" functionality on your +personal Web site. -Using forms in views -==================== +Start with this basic ``Form`` subclass, which we'll call ``ContactForm``:: + + from django import newforms as forms + + class ContactForm(forms.Form): + subject = forms.CharField(max_length=100) + message = forms.CharField() + sender = forms.EmailField() + cc_myself = forms.BooleanField() + +A form is composed of ``Field`` objects. In this case, our form has four +fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. We'll explain +the different types of fields -- e.g., ``CharField`` and ``EmailField`` -- +shortly. + +Creating ``Form`` instances +--------------------------- + +A ``Form`` instance is either **bound** or **unbound** to a set of data. + + * If it's **bound** to a set of data, it's capable of validating that data + and rendering the form as HTML with the data displayed in the HTML. + + * If it's **unbound**, it cannot do validation (because there's no data to + validate!), but it can still render the blank form as HTML. + +To create an unbound ``Form`` instance, simply instantiate the class:: + + >>> f = ContactForm() + +To bind data to a form, pass the data as a dictionary as the first parameter to +your ``Form`` class constructor:: + + >>> data = {'subject': 'hello', + ... 'message': 'Hi there', + ... 'sender': 'foo@example.com', + ... 'cc_myself': True} + >>> f = ContactForm(data) + +In this dictionary, the keys are the field names, which correspond to the +attributes in your ``Form`` class. The values are the data you're trying +to validate. These will usually be strings, but there's no requirement that +they be strings; the type of data you pass depends on the ``Field``, as we'll +see in a moment. + +If you need to distinguish between bound and unbound form instances at runtime, +check the value of the form's ``is_bound`` attribute:: + + >>> f = ContactForm() + >>> f.is_bound + False + >>> f = ContactForm({'subject': 'hello'}) + >>> f.is_bound + True + +Note that passing an empty dictionary creates a *bound* form with empty data:: + + >>> f = ContactForm({}) + >>> f.is_bound + True + +If you have a bound ``Form`` instance and want to change the data somehow, or +if you want to bind an unbound ``Form`` instance to some data, create another +``Form`` instance. There is no way to change data in a ``Form`` instance. Once +a ``Form`` instance has been created, you should consider its data immutable, +whether it has data or not. + +Using forms to validate data +---------------------------- + +The primary task of a ``Form`` object is to validate data. With a bound +``Form`` instance, call the ``is_valid()`` method to run validation and return +a boolean designating whether the data was valid:: + + >>> data = {'subject': 'hello', + ... 'message': 'Hi there', + ... 'sender': 'foo@example.com', + ... 'cc_myself': True} + >>> f = ContactForm(data) + >>> f.is_valid() + True + +Let's try with some invalid data. In this case, ``subject`` is blank (an error, +because all fields are required by default) and ``sender`` is not a valid +e-mail address:: + + >>> data = {'subject': '', + ... 'message': 'Hi there', + ... 'sender': 'invalid e-mail address', + ... 'cc_myself': True} + >>> f = ContactForm(data) + >>> f.is_valid() + False + +Access the ``Form`` attribute ``errors`` to get a dictionary of error messages:: + + >>> f.errors + {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']} + +In this dictionary, the keys are the field names, and the values are lists of +Unicode strings representing the error messages. The error messages are stored +in lists because a field can have multiple error messages. + +You can access ``errors`` without having to call ``is_valid()`` first. The +form's data will be validated the first time either you call ``is_valid()`` or +access ``errors``. + +Behavior of unbound forms +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's meaningless to validate a form with no data, but, for the record, here's +what happens with unbound forms:: + + >>> f = ContactForm() + >>> f.is_valid() + False + >>> f.errors + {} + +Accessing "clean" data +---------------------- + +Each ``Field`` in a ``Form`` class is responsible not only for validating data, +but also for "cleaning" it -- normalizing it to a consistent format. This is a +nice feature, because it allows data for a particular field to be input in +a variety of ways, always resulting in consistent output. + +For example, ``DateField`` normalizes input into a Python ``datetime.date`` +object. Regardless of whether you pass it a string in the format +``'1994-07-15'``, a ``datetime.date`` object or a number of other formats, +``DateField`` will always normalize it to a ``datetime.date`` object as long as +it's valid. + +Once you've created a ``Form`` instance with a set of data and validated it, +you can access the clean data via the ``clean_data`` attribute of the ``Form`` +object:: + + >>> data = {'subject': 'hello', + ... 'message': 'Hi there', + ... 'sender': 'foo@example.com', + ... 'cc_myself': True} + >>> f = ContactForm(data) + >>> f.is_valid() + True + >>> f.clean_data + {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} + +Note that any text-based field -- such as ``CharField`` or ``EmailField`` -- +always cleans the input into a Unicode string. We'll cover the encoding +implications later in this document. + +If your data does *not* validate, your ``Form`` instance will not have a +``clean_data`` attribute:: + + >>> data = {'subject': '', + ... 'message': 'Hi there', + ... 'sender': 'invalid e-mail address', + ... 'cc_myself': True} + >>> f = ContactForm(data) + >>> f.is_valid() + False + >>> f.clean_data + Traceback (most recent call last): + ... + AttributeError: 'ContactForm' object has no attribute 'clean_data' + +``clean_data`` will always *only* contain a key for fields defined in the +``Form``, even if you pass extra data when you define the ``Form``. In this +example, we pass a bunch of extra fields to the ``ContactForm`` constructor, +but ``clean_data`` contains only the form's fields:: + + >>> data = {'subject': 'hello', + ... 'message': 'Hi there', + ... 'sender': 'foo@example.com', + ... 'cc_myself': True, + ... 'extra_field_1': 'foo', + ... 'extra_field_2': 'bar', + ... 'extra_field_3': 'baz'} + >>> f = ContactForm(data) + >>> f.is_valid() + True + >>> f.clean_data # Doesn't contain extra_field_1, etc. + {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'} + +Behavior of unbound forms +~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's meaningless to request "clean" data in a form with no data, but, for the +record, here's what happens with unbound forms:: + + >>> f = ContactForm() + >>> f.clean_data + Traceback (most recent call last): + ... + AttributeError: 'ContactForm' object has no attribute 'clean_data' + +Outputting forms as HTML +------------------------ + +The second task of a ``Form`` object is to render itself as HTML. To do so, +simply ``print`` it:: + + >>> f = ContactForm() + >>> print f + + + + + +If the form is bound to data, the HTML output will include that data +appropriately. For example, if a field is represented by an +````, the data will be in the ``value`` attribute. If a +field is represented by an ````, then that HTML will +include ``checked="checked"`` if appropriate:: + + >>> data = {'subject': 'hello', + ... 'message': 'Hi there', + ... 'sender': 'foo@example.com', + ... 'cc_myself': True} + >>> f = ContactForm(data) + >>> print f + + + + + +This default output is a two-column HTML table, with a ```` for each field. +Notice the following: + + * For flexibility, the output does *not* include the ```` and + ``
`` tags, nor does it include the ```` and ``
`` + tags or an ```` tag. It's your job to do that. + + * Each field type has a default HTML representation. ``CharField`` and + ``EmailField`` are represented by an ````. + ``BooleanField`` is represented by an ````. Note + these are merely sensible defaults; you can specify which HTML to use for + a given field by using widgets, which we'll explain shortly. + + * The HTML ``name`` for each tag is taken directly from its attribute name + in the ``ContactForm`` class. + + * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and + ``'Cc myself:'`` is generated from the field name by converting all + underscores to spaces and upper-casing the first letter. Again, note + these are merely sensible defaults; you can also specify labels manually. + + * Each text label is surrounded in an HTML ``