mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 14:16:09 +00:00
Code Issues 32 Releases Wiki Activity

boulder-oracle-sprint: Merged to trunk [4455].

Browse Source 
git-svn-id: http://code.djangoproject.com/svn/django/branches/boulder-oracle-sprint@4456 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Boulder Sprinters
2007-02-02 17:35:55 +00:00
parent 92b7851424
commit e17f755514
78 changed files with 2389 additions and 592 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/add_ons.txt
View File

@@ -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
=============

4
docs/apache_auth.txt
View File

@@ -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

46
docs/api_stability.txt
View File

@@ -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/

22
docs/authentication.txt
View File

@@ -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::
<p>You don't have permission to do anything in the foo app.</p>
{% 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
============================

2
docs/cache.txt
View File

@@ -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
==================

85
docs/contributing.txt
View File

@@ -122,9 +122,9 @@ 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
@@ -151,24 +151,70 @@ 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.
Pick an open ticket that is missing some details, and try to replicate the
problem. Fill in the missing pieces of the report. If the ticket doesn't have
a patch, create one.
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.
Once you've completed all the missing details on the ticket and you have a
patch with all the required features, e-mail `django-developers`_. Indicate
that you have triaged a ticket, and recommend a course of action for dealing
with that ticket.
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.
At first, this may require you to be persistent. If you find that your triaged
ticket still isn't getting attention, occasional polite requests for eyeballs
to look at your ticket may be necessary. However, as you earn a reputation for
quality triage work, you should find that it is easier to get the developers'
attention.
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
=======================================
@@ -186,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
============
@@ -311,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
----------------------
@@ -548,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

15
docs/db-api.txt
View File

@@ -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()``
~~~~~~~~~~~~~~~~~~~~

2
docs/design_philosophies.txt
View File

@@ -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
----------------------

10
docs/django-admin.txt
View File

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

8
docs/email.txt
View File

@@ -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
========

24
docs/faq.txt
View File

@@ -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?
--------------------------------------------------------------------------------------------

2
docs/fastcgi.txt
View File

@@ -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/

14
docs/flatpages.txt
View File

@@ -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
==================

8
docs/forms.txt
View File

@@ -14,7 +14,7 @@ use the django.newforms system, which we have begun to document in the
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: http://www.djangoproject.com/documentation/newforms/
.. _newforms documentation: ../newforms/
Introduction
============
@@ -665,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/

54
docs/generic_views.txt
View File

@@ -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
``<app_label>/<model_name>_archive.html`` by default, where:
* ``<model_name>`` is your model's name in all lowercase. For a model
``StaffMember``, that'd be ``staffmember``.
``StaffMember``, that'd be ``staffmember``.
* ``<app_label>`` 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.
@@ -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:**
@@ -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:**

20
docs/i18n.txt
View File

@@ -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:

6
docs/install.txt
View File

@@ -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,

18
docs/legacy_databases.txt
View File

@@ -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
====================================
@@ -25,13 +25,13 @@ what the name of the database is. Do that by editing these settings in your
* `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_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
========================
@@ -52,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
==============================

15
docs/middleware.txt
View File

@@ -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
===========================

27
docs/model-api.txt
View File

@@ -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 '<span style="color: #%s;">%s %s</span>' % (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

2
docs/modpython.txt
View File

@@ -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
===================

525
docs/newforms.txt
View File

@@ -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
==============
@@ -51,7 +51,7 @@ too messy. The choice is yours.
Overview
========
As the ``django.forms`` ("manipulators") system before it, ``django.newforms``
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.
@@ -74,7 +74,9 @@ The library deals with these concepts:
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 system.
``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
============
@@ -83,8 +85,8 @@ 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 to implement "contact me" functionality on your personal
Web site.
object that you might use to implement "contact me" functionality on your
personal Web site.
Start with this basic ``Form`` subclass, which we'll call ``ContactForm``::
@@ -101,11 +103,192 @@ 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 first thing we can do with this is output it as HTML. To do so, instantiate
it and ``print`` it::
The second task of a ``Form`` object is to render itself as HTML. To do so,
simply ``print`` it::
>>> f = ContactForm()
>>> print f
@@ -114,6 +297,23 @@ it and ``print`` it::
<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
If the form is bound to data, the HTML output will include that data
appropriately. For example, if a field is represented by an
``<input type="text">``, the data will be in the ``value`` attribute. If a
field is represented by an ``<input type="checkbox">``, 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
<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr>
<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr>
<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr>
This default output is a two-column HTML table, with a ``<tr>`` for each field.
Notice the following:
@@ -125,13 +325,13 @@ Notice the following:
``EmailField`` are represented by an ``<input type="text">``.
``BooleanField`` is represented by an ``<input type="checkbox">``. 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.
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
``'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.
@@ -286,6 +486,37 @@ example, in the ``ContactForm`` example, the fields are defined in the order
``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
output, just change the order in which those fields are listed in the class.
How errors are displayed
~~~~~~~~~~~~~~~~~~~~~~~~
If you render a bound ``Form`` object, the act of rendering will automatically
run the form's validation if it hasn't already happened, and the HTML output
will include the validation errors as a ``<ul>`` near the field. The particular
positioning of the error messages depends on the output method you're using::
>>> data = {'subject': '',
... 'message': 'Hi there',
... 'sender': 'invalid e-mail address',
... 'cc_myself': True}
>>> f = ContactForm(data, auto_id=False)
>>> print f.as_table()
<tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr>
<tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr>
<tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr>
>>> print f.as_ul()
<li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li>
<li>Message: <input type="text" name="message" value="Hi there" /></li>
<li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li>
<li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li>
>>> print f.as_p()
<p><ul class="errorlist"><li>This field is required.</li></ul></p>
<p>Subject: <input type="text" name="subject" maxlength="100" /></p>
<p>Message: <input type="text" name="message" value="Hi there" /></p>
<p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p>
<p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
<p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
More granular output
~~~~~~~~~~~~~~~~~~~~
@@ -322,6 +553,271 @@ The field-specific output honors the form object's ``auto_id`` setting::
>>> print f['message']
<input type="text" name="message" id="id_message" />
For a field's list of errors, access the field's ``errors`` attribute. This
is a list-like object that is displayed as an HTML ``<ul>`` when printed::
>>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
>>> f = ContactForm(data, auto_id=False)
>>> print f['message']
<input type="text" name="message" />
>>> f['message'].errors
[u'This field is required.']
>>> print f['message'].errors
<ul class="errorlist"><li>This field is required.</li></ul>
>>> f['subject'].errors
[]
>>> print f['subject'].errors
>>> str(f['subject'].errors)
''
Fields
======
When you create a ``Form`` class, the most important part is defining the
fields of the form. Each field has custom validation logic, along with a few
other hooks.
Although the primary way you'll use ``Field`` classes is in ``Form`` classes,
you can also instantiate them and use them directly to get a better idea of
how they work. Each ``Field`` instance has a ``clean()`` method, which takes
a single argument and either raises a ``django.newforms.ValidationError``
exception or returns the clean value::
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
u'foo@example.com'
>>> f.clean(u'foo@example.com')
u'foo@example.com'
>>> f.clean('invalid e-mail address')
Traceback (most recent call last):
...
ValidationError: [u'Enter a valid e-mail address.']
If you've used Django's old forms/validation framework, take care in noticing
this ``ValidationError`` is different than the previous ``ValidationError``.
This one lives at ``django.newforms.ValidationError`` rather than
``django.core.validators.ValidationError``.
Core field arguments
--------------------
Each ``Field`` class constructor takes at least these arguments. Some
``Field`` classes take additional, field-specific arguments, but the following
should *always* be available:
``required``
~~~~~~~~~~~~
By default, each ``Field`` class assumes the value is required, so if you pass
an empty value -- either ``None`` or the empty string (``""``) -- then
``clean()`` will raise a ``ValidationError`` exception::
>>> f = forms.CharField()
>>> f.clean('foo')
u'foo'
>>> f.clean('')
Traceback (most recent call last):
...
ValidationError: [u'This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: [u'This field is required.']
>>> f.clean(' ')
u' '
>>> f.clean(0)
u'0'
>>> f.clean(True)
u'True'
>>> f.clean(False)
u'False'
To specify that a field is *not* required, pass ``required=False`` to the
``Field`` constructor::
>>> f = forms.CharField(required=False)
>>> f.clean('foo')
u'foo'
>>> f.clean('')
u''
>>> f.clean(None)
u''
>>> f.clean(0)
u'0'
>>> f.clean(True)
u'True'
>>> f.clean(False)
u'False'
If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value,
then ``clean()`` will return a *normalized* empty value rather than raising
``ValidationError``. For ``CharField``, this will be a Unicode empty string.
For other ``Field`` classes, it might be ``None``. (This varies from field to
field.)
``label``
~~~~~~~~~
The ``label`` argument lets you specify the "human-friendly" label for this
field. This is used when the ``Field`` is displayed in a ``Form``.
As explained in _`Outputting forms as HTML` above, the default label for a
``Field`` is generated from the field name by converting all underscores to
spaces and upper-casing the first letter. Specify ``label`` if that default
behavior doesn't result in an adequate label.
Here's a full example ``Form`` that implements ``label`` for two of its fields.
We've specified ``auto_id=False`` to simplify the output::
>>> class CommentForm(forms.Form):
... name = forms.CharField(label='Your name')
... url = forms.URLField(label='Your Web site', required=False)
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print f
<tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
<tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
``initial``
~~~~~~~~~~~
The ``initial`` argument lets you specify the initial value to use when
rendering this ``Field`` in an unbound ``Form``.
The use-case for this is when you want to display an "empty" form in which a
field is initialized to a particular value. For example::
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print f
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
<tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
You may be thinking, why not just pass a dictionary of the initial values as
data when displaying the form? Well, if you do that, you'll trigger validation,
and the HTML output will include any validation errors::
>>> class CommentForm(forms.Form):
... name = forms.CharField()
... url = forms.URLField()
... comment = forms.CharField()
>>> default_data = {'name': 'Your name', 'url': 'http://'}
>>> f = CommentForm(default_data, auto_id=False)
>>> print f
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" /></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr>
This is why ``initial`` values are only displayed for unbound forms. For bound
forms, the HTML output will use the bound data.
Also note that ``initial`` values are *not* used as "fallback" data in
validation if a particular field's value is not given. ``initial`` values are
*only* intended for initial form display::
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': [u'This field is required.'], 'name': [u'This field is required.']}
``widget``
~~~~~~~~~~
The ``widget`` argument lets you specify a ``Widget`` class to use when
rendering this ``Field``. See _`Widgets` below for more information.
``help_text``
~~~~~~~~~~~~~
The ``help_text`` argument lets you specify descriptive text for this
``Field``. If you provide ``help_text``, it will be displayed next to the
``Field`` when the ``Field`` is rendered in a ``Form``.
Here's a full example ``Form`` that implements ``help_text`` for two of its
fields. We've specified ``auto_id=False`` to simplify the output::
>>> class HelpTextContactForm(forms.Form):
... subject = forms.CharField(max_length=100, help_text='100 characters max.')
... message = forms.CharField()
... sender = forms.EmailField(help_text='A valid e-mail address, please.')
... cc_myself = forms.BooleanField()
>>> f = HelpTextContactForm(auto_id=False)
>>> print f.as_table()
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /><br />100 characters max.</td></tr>
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
<tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
>>> print f.as_ul()
<li>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</li>
<li>Message: <input type="text" name="message" /></li>
<li>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
>>> print f.as_p()
<p>Subject: <input type="text" name="subject" maxlength="100" /> 100 characters max.</p>
<p>Message: <input type="text" name="message" /></p>
<p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
Dynamic initial values
----------------------
The ``initial`` argument to ``Field`` (explained above) lets you hard-code the
initial value for a ``Field`` -- but what if you want to declare the initial
value at runtime? For example, you might want to fill in a ``username`` field
with the username of the current session.
To accomplish this, use the ``initial`` argument to a ``Form``. This argument,
if given, should be a dictionary mapping field names to initial values. Only
include the fields for which you're specifying an initial value; it's not
necessary to include every field in your form. For example::
>>> class CommentForm(forms.Form):
... name = forms.CharField()
... url = forms.URLField()
... comment = forms.CharField()
>>> f = CommentForm(initial={'name': 'your username'}, auto_id=False)
>>> print f
<tr><th>Name:</th><td><input type="text" name="name" value="your username" /></td></tr>
<tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
>>> f = CommentForm(initial={'name': 'another username'}, auto_id=False)
>>> print f
<tr><th>Name:</th><td><input type="text" name="name" value="another username" /></td></tr>
<tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
Just like the ``initial`` parameter to ``Field``, these values are only
displayed for unbound forms, and they're not used as fallback values if a
particular value isn't provided.
Finally, note that if a ``Field`` defines ``initial`` *and* you include
``initial`` when instantiating the ``Form``, then the latter ``initial`` will
have precedence. In this example, ``initial`` is provided both at the field
level and at the form instance level, and the latter gets precedence::
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='class')
... url = forms.URLField()
... comment = forms.CharField()
>>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
>>> print f
<tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
<tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
More coming soon
================
@@ -333,8 +829,5 @@ what's possible.
If you're really itching to learn and use this library, please be patient.
We're working hard on finishing both the code and documentation.
Using forms with templates
==========================
Using forms in views
====================
Widgets
=======

6
docs/outputting_csv.txt
View File

@@ -24,7 +24,7 @@ and Django's ``HttpResponse`` objects are file-like objects.
For more information on the CSV library, see the `CSV library docs`_.
.. _Request and response objects: http://www.djangoproject.com/documentation/request_response/
.. _Request and response objects: ../request_response/
.. _CSV library docs: http://www.python.org/doc/current/lib/module-csv.html
Here's an example::
@@ -115,5 +115,5 @@ a line of CSV for each row. It uses the `addslashes template filter`_ to ensure
there aren't any problems with quotes. If you can be certain your data doesn't
have single or double quotes in it, you can remove the ``addslashes`` filters.
.. _Django template system: http://www.djangoproject.com/documentation/templates/
.. _addslashes template filter: http://www.djangoproject.com/documentation/templates/#addslashes
.. _Django template system: ../templates/
.. _addslashes template filter: ../templates/#addslashes

2
docs/outputting_pdf.txt
View File

@@ -43,7 +43,7 @@ objects.
For more information on ``HttpResponse`` objects, see
`Request and response objects`_.
.. _Request and response objects: http://www.djangoproject.com/documentation/request_response/
.. _Request and response objects: ../request_response/
Here's a "Hello World" example::

2
docs/overview.txt
View File

@@ -11,7 +11,7 @@ understand how Django works, but this isn't intended to be a tutorial or
reference. Please see our more-detailed Django documentation_ when you're ready
to start a project.
.. _documentation: http://www.djangoproject.com/documentation/
.. _documentation: ../
Design your model
=================

12
docs/redirects.txt
View File

@@ -15,8 +15,8 @@ To install the redirects 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
============
@@ -46,8 +46,8 @@ resort.
For more on middleware, read the `middleware docs`_.
.. _SITE_ID: http://www.djangoproject.com/documentation/settings/#site-id
.. _middleware docs: http://www.djangoproject.com/documentation/middleware/
.. _SITE_ID: ../settings/#site-id
.. _middleware docs: ../middleware/
How to add, change and delete redirects
=======================================
@@ -66,6 +66,6 @@ Redirects are represented by a standard `Django model`_, which lives in
`django/contrib/redirects/models.py`_. You can access redirect
objects via the `Django database API`_.
.. _Django model: http://www.djangoproject.com/documentation/model_api/
.. _Django model: ../model_api/
.. _django/contrib/redirects/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/redirects/models.py
.. _Django database API: http://www.djangoproject.com/documentation/db_api/
.. _Django database API: ../db_api/

4
docs/request_response.txt
View File

@@ -117,14 +117,14 @@ All attributes except ``session`` should be considered read-only.
``AuthenticationMiddleware`` activated. For more, 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
``session``
A readable-and-writable, dictionary-like object that represents the current
session. This is only available if your Django installation has session
support activated. See the `session documentation`_ for full details.
.. _`session documentation`: http://www.djangoproject.com/documentation/sessions/
.. _`session documentation`: ../sessions/
``raw_post_data``
The raw HTTP POST data. This is only useful for advanced processing. Use

4
docs/sessions.txt
View File

@@ -27,7 +27,7 @@ If you don't want to use sessions, you might as well remove the
``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'``
from your ``INSTALLED_APPS``. It'll save you a small bit of overhead.
.. _middleware: http://www.djangoproject.com/documentation/middleware/
.. _middleware: ../middleware/
Using sessions in views
=======================
@@ -290,7 +290,7 @@ Whether to save the session data on every request. If this is ``False``
(default), then the session data will only be saved if it has been modified --
that is, if any of its dictionary values have been assigned or deleted.
.. _Django settings: http://www.djangoproject.com/documentation/settings/
.. _Django settings: ../settings/
Technical details
=================

41
docs/settings.txt
View File

@@ -59,7 +59,7 @@ Use the ``--settings`` command-line argument to specify the settings manually::
django-admin.py runserver --settings=mysite.settings
.. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/
.. _django-admin.py: ../django_admin/
On the server (mod_python)
--------------------------
@@ -75,7 +75,7 @@ settings file to use. Do that with ``SetEnv``::
Read the `Django mod_python documentation`_ for more information.
.. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/
.. _Django mod_python documentation: ../modpython/
Default settings
================
@@ -102,7 +102,7 @@ between the current settings file and Django's default settings.
For more, see the `diffsettings documentation`_.
.. _diffsettings documentation: http://www.djangoproject.com/documentation/django_admin/#diffsettings
.. _diffsettings documentation: ../django_admin/#diffsettings
Using settings in Python code
=============================
@@ -157,13 +157,13 @@ ABSOLUTE_URL_OVERRIDES
Default: ``{}`` (Empty dictionary)
A dictionary mapping ``"app_label.module_name"`` strings to functions that take
A dictionary mapping ``"app_label.model_name"`` strings to functions that take
a model object and return its URL. This is a way of overriding
``get_absolute_url()`` methods on a per-installation basis. Example::
ABSOLUTE_URL_OVERRIDES = {
'blogs.blogs': lambda o: "/blogs/%s/" % o.slug,
'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
'blogs.Weblog': lambda o: "/blogs/%s/" % o.slug,
'news.Story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
}
ADMIN_FOR
@@ -306,7 +306,7 @@ pages -- and, possibly, by other parts of the system. See
See also DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT.
.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
.. _allowed date format strings: ../templates/#now
DATETIME_FORMAT
---------------
@@ -319,7 +319,7 @@ pages -- and, possibly, by other parts of the system. See
See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and MONTH_DAY_FORMAT.
.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
.. _allowed date format strings: ../templates/#now
DEBUG
-----
@@ -433,7 +433,7 @@ A tuple of strings designating all applications that are enabled in this Django
installation. Each string should be a full Python path to a Python package that
contains a Django application, as created by `django-admin.py startapp`_.
.. _django-admin.py startapp: http://www.djangoproject.com/documentation/django_admin/#startapp-appname
.. _django-admin.py startapp: ../django_admin/#startapp-appname
INTERNAL_IPS
------------
@@ -464,7 +464,7 @@ A string representing the language code for this installation. This should be
in standard language format. For example, U.S. English is ``"en-us"``. See the
`internationalization docs`_.
.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/
.. _internationalization docs: ../i18n/
LANGUAGES
---------
@@ -557,6 +557,11 @@ Default: ``''`` (Empty string)
URL that handles the media served from ``MEDIA_ROOT``.
Example: ``"http://media.lawrence.com"``
Note that this should have a trailing slash if it has a path component.
Good: ``"http://www.example.com/static/"``
Bad: ``"http://www.example.com/static"``
MIDDLEWARE_CLASSES
------------------
@@ -612,7 +617,7 @@ Default: Not defined
A string representing the full Python import path to your root URLconf. For example:
``"mydjangoapps.urls"``. See `How Django processes a request`_.
.. _How Django processes a request: http://www.djangoproject.com/documentation/url_dispatch/#how-django-processes-a-request
.. _How Django processes a request: ../url_dispatch/#how-django-processes-a-request
SECRET_KEY
----------
@@ -704,7 +709,7 @@ and a single database can manage content for multiple sites.
See the `site framework docs`_.
.. _site framework docs: http://www.djangoproject.com/documentation/sites/
.. _site framework docs: ../sites/
TEMPLATE_CONTEXT_PROCESSORS
---------------------------
@@ -760,7 +765,7 @@ Default: ``''`` (Empty string)
Output, as a string, that the template system should use for invalid (e.g.
misspelled) variables. See `How invalid variables are handled`_.
.. _How invalid variables are handled: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled
.. _How invalid variables are handled: ../templates_python/#how-invalid-variables-are-handled
TEST_RUNNER
-----------
@@ -798,7 +803,7 @@ pages -- and, possibly, by other parts of the system. See
See also DATE_FORMAT, DATETIME_FORMAT, TIME_FORMAT, YEAR_MONTH_FORMAT and
MONTH_DAY_FORMAT.
.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now
.. _allowed date format strings: ../templates/#now
TIME_ZONE
---------
@@ -868,11 +873,11 @@ Different locales have different formats. For example, U.S. English would say
See `allowed date format strings`_. See also DATE_FORMAT, DATETIME_FORMAT,
TIME_FORMAT and MONTH_DAY_FORMAT.
.. _cache docs: http://www.djangoproject.com/documentation/cache/
.. _middleware docs: http://www.djangoproject.com/documentation/middleware/
.. _session docs: http://www.djangoproject.com/documentation/sessions/
.. _cache docs: ../cache/
.. _middleware docs: ../middleware/
.. _session docs: ../sessions/
.. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
.. _template documentation: http://www.djangoproject.com/documentation/templates_python/
.. _template documentation: ../templates_python/
Creating your own settings
==========================

20
docs/sitemaps.txt
View File

@@ -23,8 +23,8 @@ you express this information in Python code.
It works much like Django's `syndication framework`_. To create a sitemap, just
write a ``Sitemap`` class and point to it in your URLconf_.
.. _syndication framework: http://www.djangoproject.com/documentation/syndication/
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _syndication framework: ../syndication/
.. _URLconf: ../url_dispatch/
Installation
============
@@ -41,9 +41,9 @@ To install the sitemap app, follow these steps:
reason it needs to go into ``INSTALLED_APPS`` is so that the
``load_template_source`` template loader can find the default templates.)
.. _INSTALLED_APPS: http://www.djangoproject.com/documentation/settings/#installed-apps
.. _TEMPLATE_LOADERS: http://www.djangoproject.com/documentation/settings/#template-loaders
.. _sites framework: http://www.djangoproject.com/documentation/sites/
.. _INSTALLED_APPS: ../settings/#installed-apps
.. _TEMPLATE_LOADERS: ../settings/#template-loaders
.. _sites framework: ../sites/
Initialization
==============
@@ -68,7 +68,7 @@ The sitemap view takes an extra, required argument: ``{'sitemaps': sitemaps}``.
``NewsSitemap``). It may also map to an *instance* of a ``Sitemap`` class
(e.g., ``BlogSitemap(some_var)``).
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _URLconf: ../url_dispatch/
Sitemap classes
===============
@@ -217,8 +217,8 @@ defined for the current ``SITE_ID`` (see the `sites documentation`_) and
creates an entry in the sitemap. These entries include only the ``location``
attribute -- not ``lastmod``, ``changefreq`` or ``priority``.
.. _flatpages: http://www.djangoproject.com/documentation/flatpages/
.. _sites documentation: http://www.djangoproject.com/documentation/sites/
.. _flatpages: ../flatpages/
.. _sites documentation: ../sites/
``GenericSitemap``
------------------
@@ -232,7 +232,7 @@ the ``lastmod`` attribute in the generated sitemap. You may also pass
``priority`` and ``changefreq`` keyword arguments to the ``GenericSitemap``
constructor to specify these attributes for all URLs.
.. _generic views: http://www.djangoproject.com/documentation/generic_views/
.. _generic views: ../generic_views/
Example
-------
@@ -261,7 +261,7 @@ Here's an example of a URLconf_ using both::
(r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})
)
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _URLconf: ../url_dispatch/
Creating a sitemap index
========================

12
docs/sites.txt
View File

@@ -276,8 +276,8 @@ you want your admin site to have access to all objects (not just site-specific
ones), put ``objects = models.Manager()`` in your model, before you define
``CurrentSiteManager``.
.. _manager: http://www.djangoproject.com/documentation/model_api/#managers
.. _manager documentation: http://www.djangoproject.com/documentation/model_api/#managers
.. _manager: ../model_api/#managers
.. _manager documentation: ../model_api/#managers
How Django uses the sites framework
===================================
@@ -316,7 +316,7 @@ Here's how Django uses the sites framework:
* The shortcut view (``django.views.defaults.shortcut``) uses the domain of
the current ``Site`` object when calculating an object's URL.
.. _redirects framework: http://www.djangoproject.com/documentation/redirects/
.. _flatpages framework: http://www.djangoproject.com/documentation/flatpages/
.. _syndication framework: http://www.djangoproject.com/documentation/syndication/
.. _authentication framework: http://www.djangoproject.com/documentation/authentication/
.. _redirects framework: ../redirects/
.. _flatpages framework: ../flatpages/
.. _syndication framework: ../syndication/
.. _authentication framework: ../authentication/

6
docs/static_files.txt
View File

@@ -24,7 +24,7 @@ production setting. Use this only for development.
For information on serving static files in an Apache production environment,
see the `Django mod_python documentation`_.
.. _Django mod_python documentation: http://www.djangoproject.com/documentation/modpython/#serving-media-files
.. _Django mod_python documentation: ../modpython/#serving-media-files
How to do it
============
@@ -49,7 +49,7 @@ Examples:
* The file ``/path/bar.jpg`` will not be accessible, because it doesn't
fall under the document root.
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _URLconf: ../url_dispatch/
Directory listings
==================
@@ -122,4 +122,4 @@ associated with the ``django.views.static.serve`` view. If not
Of course, the catch here is that you'll have to remember to set ``DEBUG=False``
in your production settings file. But you should be doing that anyway.
.. _DEBUG setting: http://www.djangoproject.com/documentation/settings/#debug
.. _DEBUG setting: ../settings/#debug

14
docs/syndication_feeds.txt
View File

@@ -26,7 +26,7 @@ to determine which feed to output.
To create a feed, just write a ``Feed`` class and point to it in your URLconf_.
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _URLconf: ../url_dispatch/
Initialization
--------------
@@ -72,8 +72,8 @@ The above example registers two feeds:
Once that's set up, you just need to define the ``Feed`` classes themselves.
.. _URLconf: http://www.djangoproject.com/documentation/url_dispatch/
.. _settings file: http://www.djangoproject.com/documentation/settings/
.. _URLconf: ../url_dispatch/
.. _settings file: ../settings/
Feed classes
------------
@@ -156,8 +156,8 @@ put into those elements.
{{ obj.description }}
.. _chicagocrime.org: http://www.chicagocrime.org/
.. _object-relational mapper: http://www.djangoproject.com/documentation/db_api/
.. _Django templates: http://www.djangoproject.com/documentation/templates/
.. _object-relational mapper: ../db_api/
.. _Django templates: ../templates/
A complex example
-----------------
@@ -277,7 +277,7 @@ Feeds created by the syndication framework automatically include the
appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This
comes directly from your `LANGUAGE_CODE setting`_.
.. _LANGUAGE_CODE setting: http://www.djangoproject.com/documentation/settings/#language-code
.. _LANGUAGE_CODE setting: ../settings/#language-code
URLs
----
@@ -292,7 +292,7 @@ Atom feeds require a ``<link rel="self">`` that defines the feed's current
location. The syndication framework populates this automatically, using the
domain of the current site according to the SITE_ID setting.
.. _SITE_ID setting: http://www.djangoproject.com/documentation/settings/#site-id
.. _SITE_ID setting: ../settings/#site-id
Publishing Atom and RSS feeds in tandem
---------------------------------------

4
docs/templates.txt
View File

@@ -792,7 +792,7 @@ Note that if you use ``{% ssi %}``, you'll need to define
See also: ``{% include %}``.
.. _ALLOWED_INCLUDE_ROOTS: http://www.djangoproject.com/documentation/settings/#allowed-include-roots
.. _ALLOWED_INCLUDE_ROOTS: ../settings/#allowed-include-roots
templatetag
~~~~~~~~~~~
@@ -1218,7 +1218,7 @@ django.contrib.humanize
A set of Django template filters useful for adding a "human touch" to data. See
the `humanize documentation`_.
.. _humanize documentation: http://www.djangoproject.com/documentation/add_ons/#humanize
.. _humanize documentation: ../add_ons/#humanize
django.contrib.markup
---------------------

24
docs/templates_python.txt
View File

@@ -11,7 +11,7 @@ If you're looking to use the Django template system as part of another
application -- i.e., without the rest of the framework -- make sure to read
the `configuration`_ section later in this document.
.. _`The Django template language: For template authors`: http://www.djangoproject.com/documentation/templates/
.. _`The Django template language: For template authors`: ../templates/
Basics
======
@@ -327,8 +327,8 @@ Note::
Here's what each of the default processors does:
.. _HttpRequest object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
.. _TEMPLATE_CONTEXT_PROCESSORS setting: http://www.djangoproject.com/documentation/settings/#template-context-processors
.. _HttpRequest object: ../request_response/#httprequest-objects
.. _TEMPLATE_CONTEXT_PROCESSORS setting: ../settings/#template-context-processors
django.core.context_processors.auth
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -353,9 +353,9 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
permissions that the currently logged-in user has. See the `permissions
docs`_.
.. _user authentication docs: http://www.djangoproject.com/documentation/authentication/#users
.. _message docs: http://www.djangoproject.com/documentation/authentication/#messages
.. _permissions docs: http://www.djangoproject.com/documentation/authentication/#permissions
.. _user authentication docs: ../authentication/#users
.. _message docs: ../authentication/#messages
.. _permissions docs: ../authentication/#permissions
django.core.context_processors.debug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -383,9 +383,9 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every
See the `internationalization docs`_ for more.
.. _LANGUAGES setting: http://www.djangoproject.com/documentation/settings/#languages
.. _LANGUAGE_CODE setting: http://www.djangoproject.com/documentation/settings/#language-code
.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/
.. _LANGUAGES setting: ../settings/#languages
.. _LANGUAGE_CODE setting: ../settings/#language-code
.. _internationalization docs: ../i18n/
django.core.context_processors.request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -944,7 +944,7 @@ The ``takes_context`` parameter defaults to ``False``. When it's set to *True*,
the tag is passed the context object, as in this example. That's the only
difference between this case and the previous ``inclusion_tag`` example.
.. _tutorials: http://www.djangoproject.com/documentation/tutorial1/#creating-models
.. _tutorials: ../tutorial1/#creating-models
Setting a variable in the context
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1115,5 +1115,5 @@ settings you wish to specify. You might want to consider setting at least
`settings documentation`_, and any setting starting with *TEMPLATE_*
is of obvious interest.
.. _settings file: http://www.djangoproject.com/documentation/settings/#using-settings-without-the-django-settings-module-environment-variable
.. _settings documentation: http://www.djangoproject.com/documentation/settings/
.. _settings file: ../settings/#using-settings-without-the-django-settings-module-environment-variable
.. _settings documentation: ../settings/

12
docs/testing.txt
View File

@@ -13,7 +13,7 @@ changed unexpectedly as a result of the refactor.
Testing a web application is a complex task, as there are many
components of a web application that must be validated and tested. To
help you test your application, Django provides a test execution
framework, and range of utilities that can be used to stimulate and
framework, and range of utilities that can be used to simulate and
inspect various facets of a web application.
This testing framework is currently under development, and may change
@@ -220,7 +220,7 @@ can be invoked on the ``Client`` instance.
will result in the evaluation of a GET request equivalent to::
http://yoursite.com/customers/details/?name='fred'&age=7
http://yoursite.com/customers/details/?name=fred&age=7
``post(path, data={})``
Make a POST request on the provided ``path``. The key-value pairs in the
@@ -244,11 +244,11 @@ can be invoked on the ``Client`` instance.
``login(path, username, password)``
In a production site, it is likely that some views will be protected with
the @login_required URL provided by ``django.contrib.auth``. Interacting
the @login_required decorator provided by ``django.contrib.auth``. Interacting
with a URL that has been login protected is a slightly complex operation,
so the Test Client provides a simple URL to automate the login process. A
so the Test Client provides a simple method to automate the login process. A
call to ``login()`` stimulates the series of GET and POST calls required
to log a user into a @login_required protected URL.
to log a user into a @login_required protected view.
If login is possible, the final return value of ``login()`` is the response
that is generated by issuing a GET request on the protected URL. If login
@@ -415,7 +415,7 @@ arguments:
tested. This is the same format returned by ``django.db.models.get_apps()``
Verbosity determines the amount of notification and debug information that
will be printed to the console; '0' is no output, '1' is normal output,
will be printed to the console; `0` is no output, `1` is normal output,
and `2` is verbose output.
Testing utilities

10
docs/tutorial01.txt
View File

@@ -17,7 +17,7 @@ installed by running the Python interactive interpreter and typing
``import django``. If that command runs successfully, with no errors, Django is
installed.
.. _`Django installed`: http://www.djangoproject.com/documentation/install/
.. _`Django installed`: ../install/
Creating a project
==================
@@ -108,7 +108,7 @@ It worked!
Full docs for the development server are at `django-admin documentation`_.
.. _django-admin documentation: http://www.djangoproject.com/documentation/django_admin/
.. _django-admin documentation: ../django_admin/
Database setup
--------------
@@ -378,7 +378,7 @@ as you like, and it will only ever create the tables that don't exist.
Read the `django-admin.py documentation`_ for full information on what the
``manage.py`` utility can do.
.. _django-admin.py documentation: http://www.djangoproject.com/documentation/django_admin/
.. _django-admin.py documentation: ../django_admin/
Playing with the API
====================
@@ -555,5 +555,5 @@ For full details on the database API, see our `Database API reference`_.
When you're comfortable with the API, read `part 2 of this tutorial`_ to get
Django's automatic admin working.
.. _Database API reference: http://www.djangoproject.com/documentation/db_api/
.. _part 2 of this tutorial: http://www.djangoproject.com/documentation/tutorial2/
.. _Database API reference: ../db_api/
.. _part 2 of this tutorial: ../tutorial2/

10
docs/tutorial02.txt
View File

@@ -5,7 +5,7 @@ Writing your first Django app, part 2
This tutorial begins where `Tutorial 1`_ left off. We're continuing the Web-poll
application and will focus on Django's automatically-generated admin site.
.. _Tutorial 1: http://www.djangoproject.com/documentation/tutorial1/
.. _Tutorial 1: ../tutorial1/
.. admonition:: Philosophy
@@ -64,7 +64,7 @@ tutorial, remember?) You should see the Django admin index page:
By default, you should see two types of editable content: groups and users.
These are core features Django ships with by default.
.. _"I can't log in" questions: http://www.djangoproject.com/documentation/faq/#the-admin-site
.. _"I can't log in" questions: ../faq/#the-admin-site
Make the poll app modifiable in the admin
=========================================
@@ -402,7 +402,7 @@ Django automatically looks for a ``templates/`` subdirectory within each app
package, for use as a fallback. See the `loader types documentation`_ for full
information.
.. _loader types documentation: http://www.djangoproject.com/documentation/templates_python/#loader-types
.. _loader types documentation: ../templates_python/#loader-types
Customize the admin index page
==============================
@@ -433,5 +433,5 @@ general, see the `Django admin CSS guide`_.
When you're comfortable with the admin site, read `part 3 of this tutorial`_ to
start working on public poll views.
.. _Django admin CSS guide: http://www.djangoproject.com/documentation/admin_css/
.. _part 3 of this tutorial: http://www.djangoproject.com/documentation/tutorial3/
.. _Django admin CSS guide: ../admin_css/
.. _part 3 of this tutorial: ../tutorial3/

13
docs/tutorial03.txt
View File

@@ -5,7 +5,7 @@ Writing your first Django app, part 3
This tutorial begins where `Tutorial 2`_ left off. We're continuing the Web-poll
application and will focus on creating the public interface -- "views."
.. _Tutorial 2: http://www.djangoproject.com/documentation/tutorial2/
.. _Tutorial 2: ../tutorial2/
Philosophy
==========
@@ -117,8 +117,8 @@ time the URLconf module is loaded. They're super fast.
.. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression
.. _Python documentation: http://www.python.org/doc/current/lib/module-re.html
.. _request and response documentation: http://www.djangoproject.com/documentation/request_response/
.. _URLconf documentation: http://www.djangoproject.com/documentation/url_dispatch/
.. _request and response documentation: ../request_response/
.. _URLconf documentation: ../url_dispatch/
Write your first view
=====================
@@ -260,8 +260,7 @@ provides a shortcut. Here's the full ``index()`` view, rewritten::
latest_poll_list = Poll.objects.all().order_by('-pub_date')[:5]
return render_to_response('polls/index.html', {'latest_poll_list': latest_poll_list})
Note that we no longer need to import ``loader``, ``Context`` or
``HttpResponse``.
Note that once we've done this in all these views, we no longer need to import ``loader``, ``Context`` and ``HttpResponse``.
The ``render_to_response()`` function takes a template name as its first
argument and a dictionary as its optional second argument. It returns an
@@ -377,7 +376,7 @@ iterable of Choice objects and is suitable for use in the ``{% for %}`` tag.
See the `template guide`_ for full details on how templates work.
.. _template guide: http://www.djangoproject.com/documentation/templates/
.. _template guide: ../templates/
Simplifying the URLconfs
========================
@@ -464,4 +463,4 @@ All the poll app cares about is its relative URLs, not its absolute URLs.
When you're comfortable with writing views, read `part 4 of this tutorial`_ to
learn about simple form processing and generic views.
.. _part 4 of this tutorial: http://www.djangoproject.com/documentation/tutorial4/
.. _part 4 of this tutorial: ../tutorial4/

6
docs/tutorial04.txt
View File

@@ -120,7 +120,7 @@ Now, go to ``/polls/1/`` in your browser and vote in the poll. You should see a
results page that gets updated each time you vote. If you submit the form
without having chosen a choice, you should see the error message.
.. _request and response documentation: http://www.djangoproject.com/documentation/request_response/
.. _request and response documentation: ../request_response/
Use generic views: Less code is better
======================================
@@ -226,7 +226,7 @@ Run the server, and use your new polling app based on generic views.
For full details on generic views, see the `generic views documentation`_.
.. _generic views documentation: http://www.djangoproject.com/documentation/generic_views/
.. _generic views documentation: ../generic_views/
Coming soon
===========
@@ -241,4 +241,4 @@ installments:
* Advanced admin features: Permissions
* Advanced admin features: Custom JavaScript
.. _Tutorial 3: http://www.djangoproject.com/documentation/tutorial3/
.. _Tutorial 3: ../tutorial3/

14
docs/url_dispatch.txt
View File

@@ -45,8 +45,8 @@ algorithm the system follows to determine which Python code to execute:
`request object`_ as its first argument and any values captured in the
regex as remaining arguments.
.. _settings file: http://www.djangoproject.com/documentation/settings/
.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
.. _settings file: ../settings/
.. _request object: ../request_response/#httprequest-objects
Example
=======
@@ -286,7 +286,7 @@ With this in mind, the above example can be written more concisely as::
Note that you don't put a trailing dot (``"."``) in the prefix. Django puts
that in automatically.
.. _Django overview: http://www.djangoproject.com/documentation/overview/
.. _Django overview: ../overview/
Multiple view prefixes
----------------------
@@ -387,13 +387,13 @@ In this example, for a request to ``/blog/2005/``, Django will call the
This technique is used in `generic views`_ and in the `syndication framework`_
to pass metadata and options to views.
.. _generic views: http://www.djangoproject.com/documentation/generic_views/
.. _syndication framework: http://www.djangoproject.com/documentation/syndication/
.. _generic views: ../generic_views/
.. _syndication framework: ../syndication/
Passing extra options to ``include()``
--------------------------------------
**New in the Django development version.**
**New in Django development version.**
Similarly, you can pass extra options to ``include()``. When you pass extra
options to ``include()``, *each* line in the included URLconf will be passed
@@ -435,7 +435,7 @@ every view in the the included URLconf accepts the extra options you're passing.
Passing callable objects instead of strings
===========================================
**New in the Django development version.**
**New in Django development version.**
Some developers find it more natural to pass the actual Python function object
rather than a string containing the path to its module. This alternative is