From 30ea350dabad28b0e524feabce434d446e013d6f Mon Sep 17 00:00:00 2001 From: Honza Král Date: Sat, 7 Nov 2009 17:09:09 +0000 Subject: [soc2009/model-validation] Merged to trunk at r11724 git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/model-validation@11725 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/faq/install.txt | 51 ++-- docs/internals/committers.txt | 13 +- docs/internals/deprecation.txt | 15 + docs/internals/release-process.txt | 2 +- docs/intro/install.txt | 2 +- docs/intro/tutorial01.txt | 1 + docs/intro/tutorial02.txt | 10 +- docs/intro/tutorial03.txt | 22 +- docs/intro/tutorial04.txt | 31 +- docs/ref/contrib/admin/index.txt | 70 ++++- docs/ref/contrib/comments/index.txt | 7 + docs/ref/contrib/csrf.txt | 448 +++++++++++++++++++++++----- docs/ref/contrib/formtools/form-wizard.txt | 2 +- docs/ref/middleware.txt | 4 +- docs/ref/models/querysets.txt | 11 + docs/ref/settings.txt | 69 +++++ docs/ref/templates/api.txt | 15 + docs/ref/templates/builtins.txt | 10 + docs/releases/1.2-alpha.txt | 52 ++++ docs/topics/auth.txt | 36 ++- docs/topics/cache.txt | 6 - docs/topics/conditional-view-processing.txt | 7 - docs/topics/email.txt | 409 +++++++++++++++++++------ docs/topics/http/middleware.txt | 1 + docs/topics/install.txt | 10 +- docs/topics/testing.txt | 12 +- 26 files changed, 1059 insertions(+), 257 deletions(-) create mode 100644 docs/releases/1.2-alpha.txt (limited to 'docs') diff --git a/docs/faq/install.txt b/docs/faq/install.txt index fb8005c7e7..28a89ccc1f 100644 --- a/docs/faq/install.txt +++ b/docs/faq/install.txt @@ -18,7 +18,7 @@ How do I get started? What are Django's prerequisites? -------------------------------- -Django requires Python_, specifically any version of Python from 2.3 +Django requires Python_, specifically any version of Python from 2.4 through 2.6. No other Python libraries are required for basic Django usage. @@ -42,30 +42,35 @@ PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported. .. _`SQLite 3`: http://www.sqlite.org/ .. _Oracle: http://www.oracle.com/ -Do I lose anything by using Python 2.3 versus newer Python versions, such as Python 2.5? ----------------------------------------------------------------------------------------- - -Not in the core framework. Currently, Django itself officially -supports any version of Python from 2.3 through 2.6, -inclusive. However, some add-on components may require a more recent -Python version; the ``django.contrib.gis`` component, for example, -requires at least Python 2.4, and third-party applications for use -with Django are, of course, free to set their own version -requirements. - -Please note, however, that over the next year or two Django will begin -dropping support for older Python versions as part of a migration -which will end with Django running on Python 3.0 (see next question -for details). So if you're just starting out with Python, it's -recommended that you use the latest 2.x release (currently, Python -2.6). This will let you take advantage of the numerous improvements -and optimizations to the Python language since version 2.3, and will -help ease the process of dropping support for older Python versions on -the road to Python 3.0. - -Can I use Django with Python 3.0? +Do I lose anything by using Python 2.4 versus newer Python versions, such as Python 2.5 or 2.6? +----------------------------------------------------------------------------------------------- + +Not in the core framework. Currently, Django itself officially supports any +version of Python from 2.4 through 2.6, inclusive. However, newer versions of +Python are often faster, have more features, and are better supported. +Third-party applications for use with Django are, of course, free to set their +own version requirements. + +Over the next year or two Django will begin dropping support for older Python +versions as part of a migration which will end with Django running on Python 3 +(see below for details). + +All else being equal, we recommend that you use the latest 2.x release +(currently Python 2.6). This will let you take advantage of the numerous +improvements and optimizations to the Python language since version 2.4, and +will help ease the process of dropping support for older Python versions on +the road to Python 3. + +Can I use Django with Python 2.3? --------------------------------- +Django 1.1 (and earlier) supported Python 2.3. Django 1.2 and newer does not. +We highly recommend you upgrade Python if at all possible, but Django 1.1 will +continue to work on Python 2.3. + +Can I use Django with Python 3? +------------------------------- + Not at the moment. Python 3.0 introduced a number of backwards-incompatible changes to the Python language, and although these changes are generally a good thing for Python's future, it will diff --git a/docs/internals/committers.txt b/docs/internals/committers.txt index 7326532ec9..803c3140c7 100644 --- a/docs/internals/committers.txt +++ b/docs/internals/committers.txt @@ -148,7 +148,6 @@ Joseph Kocherhans .. _brian rosner: http://oebfare.com/ .. _eldarion: http://eldarion.com/ -.. _pinax: http://pinaxproject.com/ .. _django dose: http://djangodose.com/ `Gary Wilson`_ @@ -189,6 +188,18 @@ Karen Tracey Karen lives in Apex, NC, USA. +`Jannis Leidel`_ + Jannis graduated in media design from `Bauhaus-University Weimar`_, + is the author of a number of pluggable Django apps and likes to + contribute to Open Source projects like Pinax_. He currently works as + a freelance web developer and designer. + + Jannis lives in Berlin, Germany. + +.. _Jannis Leidel: http://jezdez.com/ +.. _Bauhaus-University Weimar: http://www.uni-weimar.de/ +.. _pinax: http://pinaxproject.com/ + Specialists ----------- diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 7e7f4c6338..480b527d6b 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -13,6 +13,21 @@ their deprecation, as per the :ref:`Django deprecation policy hooking up admin URLs. This has been deprecated since the 1.1 release. + * 1.4 + * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 + release, in favour of the template tag method for inserting the CSRF + token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware`` + and ``CsrfViewMiddleware``, is also deprecated. + + * The old imports for CSRF functionality (``django.contrib.csrf.*``), + which moved to core in 1.2, will be removed. + + * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` + class in favor of a generic E-mail backend API. + + * The many to many SQL generation functions on the database backends + will be removed. These have been deprecated since the 1.2 release. + * 2.0 * ``django.views.defaults.shortcut()``. This function has been moved to ``django.contrib.contenttypes.views.shortcut()`` as part of the diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index 6d4ad9e8c9..e990ab8ab6 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -56,7 +56,7 @@ These releases will contain new features, improvements to existing features, and such. A minor release may deprecate certain features from previous releases. If a feature in version ``A.B`` is deprecated, it will continue to work in version ``A.B+1``. In version ``A.B+2``, use of the feature will raise a -``PendingDeprecationWarning`` but will continue to work. Version ``A.B+3`` will +``DeprecationWarning`` but will continue to work. Version ``A.B+3`` will remove the feature entirely. So, for example, if we decided to remove a function that existed in Django 1.0: diff --git a/docs/intro/install.txt b/docs/intro/install.txt index 237c208f2a..d0776a6ea3 100644 --- a/docs/intro/install.txt +++ b/docs/intro/install.txt @@ -12,7 +12,7 @@ Install Python -------------- Being a Python Web framework, Django requires Python. It works with any Python -version from 2.3 to 2.6 (due to backwards +version from 2.4 to 2.6 (due to backwards incompatibilities in Python 3.0, Django does not currently work with Python 3.0; see :ref:`the Django FAQ ` for more information on supported Python versions and the 3.0 transition), but we recommend installing Python 2.5 or later. If you do so, you won't need to set up a database just yet: Python 2.5 or later includes a lightweight database called SQLite_. diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 69c8d0f3db..afda1f28a2 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -281,6 +281,7 @@ That'll create a directory :file:`polls`, which is laid out like this:: polls/ __init__.py models.py + tests.py views.py This directory structure will house the poll application. diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index 203c945c02..ad1bd9d990 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -34,11 +34,11 @@ activate the admin site for your installation, do these three things: * Run ``python manage.py syncdb``. Since you have added a new application to :setting:`INSTALLED_APPS`, the database tables need to be updated. - * Edit your ``mysite/urls.py`` file and uncomment the lines below the - "Uncomment the next two lines..." comment. This file is a URLconf; - we'll dig into URLconfs in the next tutorial. For now, all you need to - know is that it maps URL roots to applications. In the end, you should - have a ``urls.py`` file that looks like this: + * Edit your ``mysite/urls.py`` file and uncomment the lines that reference + the admin -- there are three lines in total to uncomment. This file is a + URLconf; we'll dig into URLconfs in the next tutorial. For now, all you + need to know is that it maps URL roots to applications. In the end, you + should have a ``urls.py`` file that looks like this: .. versionchanged:: 1.1 The method for adding admin urls has changed in Django 1.1. diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 238dc63f71..1438a9e776 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -171,15 +171,23 @@ and put the following Python code in it:: This is the simplest view possible. Go to "/polls/" in your browser, and you should see your text. -Now add the following view. It's slightly different, because it takes an -argument (which, remember, is passed in from whatever was captured by the -regular expression in the URLconf):: +Now lets add a few more views. These views are slightly different, because +they take an argument (which, remember, is passed in from whatever was +captured by the regular expression in the URLconf):: def detail(request, poll_id): return HttpResponse("You're looking at poll %s." % poll_id) -Take a look in your browser, at "/polls/34/". It'll display whatever ID you -provide in the URL. + def results(request, poll_id): + return HttpResponse("You're looking at the results of poll %s." % poll_id) + + def vote(request, poll_id): + return HttpResponse("You're voting on poll %s." % poll_id) + +Take a look in your browser, at "/polls/34/". It'll run the `detail()` method +and display whatever ID you provide in the URL. Try "/polls/34/results/" and +"/polls/34/vote/" too -- these will display the placeholder results and voting +pages. Write views that actually do something ====================================== @@ -467,10 +475,10 @@ Copy the file ``mysite/urls.py`` to ``mysite/polls/urls.py``. Then, change ``mysite/urls.py`` to remove the poll-specific URLs and insert an :func:`~django.conf.urls.defaults.include`:: - ... + # ... urlpatterns = patterns('', (r'^polls/', include('mysite.polls.urls')), - ... + # ... :func:`~django.conf.urls.defaults.include`, simply, references another URLconf. Note that the regular expression doesn't have a ``$`` (end-of-string match diff --git a/docs/intro/tutorial04.txt b/docs/intro/tutorial04.txt index 28ace85ca8..394fc25ea8 100644 --- a/docs/intro/tutorial04.txt +++ b/docs/intro/tutorial04.txt @@ -21,6 +21,7 @@ tutorial, so that the template contains an HTML ``
`` element: {% if error_message %}

{{ error_message }}

{% endif %} + {% csrf_token %} {% for choice in poll.choice_set.all %}
@@ -46,17 +47,41 @@ A quick rundown: * ``forloop.counter`` indicates how many times the :ttag:`for` tag has gone through its loop + * Since we are creating a POST form (which can have the effect of modifying + data), we unfortunately need to worry about Cross Site Request Forgeries. + Thankfully, you don't have to worry too hard, because Django comes with + very easy-to-use system for protecting against it. In short, all POST + forms that are targetted at internal URLs need the ``{% csrf_token %}`` + template tag adding. + +The ``{% csrf_token %}`` tag requires information from the request object, which +is not normally accessible from within the template context. To fix this, a +small adjustment needs to be made to the ``detail`` view, so that it looks like +the following:: + + from django.template import RequestContext + # ... + def detail(request, poll_id): + p = get_object_or_404(Poll, pk=poll_id) + return render_to_response('polls/detail.html', {'poll': p}, + context_instance=RequestContext(request)) + +The details of how this works are explained in the documentation for +:ref:`RequestContext `. + Now, let's create a Django view that handles the submitted data and does something with it. Remember, in :ref:`Tutorial 3 `, we created a URLconf for the polls application that includes this line:: (r'^(?P\d+)/vote/$', 'vote'), -So let's create a ``vote()`` function in ``mysite/polls/views.py``:: +We also created a dummy implementation of the ``vote()`` function. Let's +create a real version. Add the following to ``mysite/polls/views.py``:: from django.shortcuts import get_object_or_404, render_to_response - from django.http import HttpResponseRedirect + from django.http import HttpResponseRedirect, HttpResponse from django.core.urlresolvers import reverse + from django.template import RequestContext from mysite.polls.models import Choice, Poll # ... def vote(request, poll_id): @@ -68,7 +93,7 @@ So let's create a ``vote()`` function in ``mysite/polls/views.py``:: return render_to_response('polls/detail.html', { 'poll': p, 'error_message': "You didn't select a choice.", - }) + }, context_instance=RequestContext(request)) else: selected_choice.votes += 1 selected_choice.save() diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index c1e05eda1d..0f746bf01b 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -770,7 +770,7 @@ documented in :ref:`topics-http-urls`:: However, the ``self.my_view`` function registered above suffers from two problems: - * It will *not* perform and permission checks, so it will be accessible to + * It will *not* perform any permission checks, so it will be accessible to the general public. * It will *not* provide any header details to prevent caching. This means if the page retrieves data from the database, and caching middleware is @@ -1048,16 +1048,70 @@ automatically:: FriendshipInline, ] +Working with Many-to-Many Models +-------------------------------- + +.. versionadded:: 1.2 + +By default, admin widgets for many-to-many relations will be displayed +on whichever model contains the actual reference to the ``ManyToManyField``. +Depending on your ``ModelAdmin`` definition, each many-to-many field in your +model will be represented by a standard HTML ``