queryset-refactor: Merged to [6250]

git-svn-id: http://code.djangoproject.com/svn/django/branches/queryset-refactor@6339 bcc190cf-cafb-0310-a4f2-bffc1f526a37

5 files changed, 226 insertions, 13 deletions

diff --git a/docs/add_ons.txt b/docs/add_ons.txt
index a1d78b8685..00c6e0dcf4 100644
--- a/docs/add_ons.txt
+++ b/docs/add_ons.txt
@@ -70,8 +70,9 @@ An abstraction of the following workflow:
 
 "Display an HTML form, force a preview, then do something with the submission."
 
-Full documentation for this feature does not yet exist, but you can read the
-code and docstrings in ``django/contrib/formtools/preview.py`` for a start.
+See the `form preview documentation`_.
+
+.. _form preview documentation: ../form_preview/
 
 humanize
 ========
diff --git a/docs/form_preview.txt b/docs/form_preview.txt
new file mode 100644
index 0000000000..4be7b07a74
--- /dev/null
+++ b/docs/form_preview.txt
@@ -0,0 +1,97 @@
+============
+Form preview
+============
+
+Django comes with an optional "form preview" application that helps automate
+the following workflow:
+
+"Display an HTML form, force a preview, then do something with the submission."
+
+To force a preview of a form submission, all you have to do is write a short
+Python class.
+
+Overview
+=========
+
+Given a ``django.newforms.Form`` subclass that you define, this application
+takes care of the following workflow:
+
+    1. Displays the form as HTML on a Web page.
+    2. Validates the form data when it's submitted via POST.
+       a. If it's valid, displays a preview page.
+       b. If it's not valid, redisplays the form with error messages.
+    3. When the "confirmation" form is submitted from the preview page, calls
+       a hook that you define -- a ``done()`` method that gets passed the valid
+       data.
+
+The framework enforces the required preview by passing a shared-secret hash to
+the preview page via hidden form fields. If somebody tweaks the form parameters
+on the preview page, the form submission will fail the hash-comparison test.
+
+How to use ``FormPreview``
+==========================
+
+    1. Point Django at the default FormPreview templates. There are two ways to
+       do this:
+
+       * Add ``'django.contrib.formtools'`` to your ``INSTALLED_APPS``
+         setting. This will work if your ``TEMPLATE_LOADERS`` setting includes
+         the ``app_directories`` template loader (which is the case by
+         default). See the `template loader docs`_ for more.
+
+       * Otherwise, determine the full filesystem path to the
+         ``django/contrib/formtools/templates`` directory, and add that
+         directory to your ``TEMPLATE_DIRS`` setting.
+
+    2. Create a ``FormPreview`` subclass that overrides the ``done()`` method::
+
+           from django.contrib.formtools import FormPreview
+           from myapp.models import SomeModel
+
+           class SomeModelFormPreview(FormPreview):
+
+               def done(self, request, cleaned_data):
+                   # Do something with the cleaned_data, then redirect
+                   # to a "success" page.
+                   return HttpResponseRedirect('/form/success')
+
+       This method takes an ``HttpRequest`` object and a dictionary of the form
+       data after it has been validated and cleaned. It should return an
+       ``HttpResponseRedirect`` that is the end result of the form being
+       submitted.
+
+    3. Change your URLconf to point to an instance of your ``FormPreview``
+       subclass::
+
+           from myapp.preview import SomeModelFormPreview
+           from myapp.models import SomeModel
+           from django import newforms as forms
+
+       ...and add the following line to the appropriate model in your URLconf::
+
+           (r'^post/$', SomeModelFormPreview(forms.models.form_for_model(SomeModel))),
+
+       Or, if you already have a Form class defined for the model::
+
+           (r'^post/$', SomeModelFormPreview(SomeModelForm)),
+
+    4. Run the Django server and visit ``/post/`` in your browser.
+
+.. _template loader docs: ../templates_python/#loader-types
+
+``FormPreview`` classes
+=======================
+
+A ``FormPreview`` class is a simple Python class that represents the preview
+workflow.  ``FormPreview`` classes must subclass
+``django.contrib.formtools.preview.FormPreview`` and override the ``done()``
+method. They can live anywhere in your codebase.
+
+``FormPreview`` templates
+=========================
+
+By default, the form is rendered via the template ``formtools/form.html``, and
+the preview page is rendered via the template ``formtools.preview.html``.
+These values can be overridden for a particular form preview by setting
+``preview_template`` and ``form_template`` attributes on the FormPreview
+subclass. See ``django/contrib/formtools/templates`` for the default templates.
diff --git a/docs/shortcuts.txt b/docs/shortcuts.txt
index 2c0dbb5663..6c55486b5f 100644
--- a/docs/shortcuts.txt
+++ b/docs/shortcuts.txt
@@ -6,36 +6,138 @@ The package ``django.shortcuts`` collects helper functions and classes that
 "span" multiple levels of MVC. In other words, these functions/classes
 introduce controlled coupling for convenience's sake.
 
-``render_to_response``
-======================
+``render_to_response()``
+========================
 
 ``django.shortcuts.render_to_response`` renders a given template with a given
 context dictionary and returns an ``HttpResponse`` object with that rendered
 text.
 
-Example::
+Required arguments
+------------------
+
+``template``
+    The full name of a template to use.
+
+Optional arguments
+------------------
+
+``context``
+    A dictionary of values to add to the template context. By default, this
+    is an empty dictionary. If a value in the dictionary is callable, the
+    view will call it just before rendering  the template.
+
+``mimetype``
+    **New in Django development version:** The MIME type to use for the
+    resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
+    setting.
+
+Example
+-------
+
+The following example renders the template ``myapp/index.html`` with the
+MIME type ``application/xhtml+xml``::
 
     from django.shortcuts import render_to_response
-    r = render_to_response('myapp/template.html', {'foo': 'bar'})
+
+    def my_view(request):
+        # View code here...
+        return render_to_response('myapp/index.html', {"foo": "bar"},
+            mimetype="application/xhtml+xml")
 
 This example is equivalent to::
 
     from django.http import HttpResponse
     from django.template import Context, loader
-    t = loader.get_template('myapp/template.html')
-    c = Context({'foo': 'bar'})
-    r = HttpResponse(t.render(c))
+
+    def my_view(request):
+        # View code here...
+        t = loader.get_template('myapp/template.html')
+        c = Context({'foo': 'bar'})
+        r = HttpResponse(t.render(c),
+            mimetype="application/xhtml+xml")
+
+.. _an HttpResponse object: ../request_response/#httpresponse-objects
 
 ``get_object_or_404``
 =====================
 
-``django.shortcuts.get_object_or_404`` calls ``get()`` on a given model
+``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model
 manager, but it raises ``django.http.Http404`` instead of the model's
 ``DoesNotExist`` exception.
 
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets the object with the primary key of 1 from
+``MyModel``::
+
+    from django.shortcuts import get_object_or_404
+
+    def my_view(request):
+        my_object = get_object_or_404(MyModel, pk=1)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        try:
+            my_object = MyModel.object.get(pk=1)
+        except MyModel.DoesNotExist:
+            raise Http404
+
+Note: As with ``get()``, an ``AssertionError`` will be raised if more than
+one object is found.
+
+.. _get(): ../db-api/#get-kwargs
+
 ``get_list_or_404``
 ===================
 
-``django.shortcuts.get_list_or_404`` returns the result of ``filter()`` on a
+``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a
 given model manager, raising ``django.http.Http404`` if the resulting list is
 empty.
+
+Required arguments
+------------------
+
+``klass``
+    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
+    object.
+
+``**kwargs``
+    Lookup parameters, which should be in the format accepted by ``get()`` and
+    ``filter()``.
+
+Example
+-------
+
+The following example gets all published objects from ``MyModel``::
+
+    from django.shortcuts import get_list_or_404
+
+    def my_view(request):
+        my_objects = get_list_or_404(MyModel, published=True)
+
+This example is equivalent to::
+
+    from django.http import Http404
+
+    def my_view(request):
+        my_objects = MyModels.object.filter(published=True)
+        if not my_objects:
+            raise Http404
+
+.. _filter(): ../db-api/#filter-kwargs
diff --git a/docs/templates.txt b/docs/templates.txt
index 0c8cc79311..dbed0ba5c9 100644
--- a/docs/templates.txt
+++ b/docs/templates.txt
@@ -1135,12 +1135,15 @@ Returns a boolean of whether the value's length is the argument.
 linebreaks
 ~~~~~~~~~~
 
-Converts newlines into ``<p>`` and ``<br />`` tags.
+Replaces line breaks in plain text with appropriate HTML; a single
+newline becomes an HTML line break (``<br />``) and a new line
+followed by a blank line becomes a paragraph break (``</p>``).
 
 linebreaksbr
 ~~~~~~~~~~~~
 
-Converts newlines into ``<br />`` tags.
+Converts all newlines in a piece of plain text to HTML line breaks
+(``<br />``).
 
 linenumbers
 ~~~~~~~~~~~
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 77b5b11103..2e18fd6130 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -41,6 +41,16 @@ From the command line, ``cd`` into a directory where you'd like to store your
 code, then run the command ``django-admin.py startproject mysite``. This
 will create a ``mysite`` directory in your current directory.
 
+.. admonition:: Max OS X permissions
+   
+   If you're using Mac OS X, you may see the message "permission
+   denied" when you try to run ``django-admin.py startproject``. This
+   is because, on Unix-based systems like OS X, a file must be marked
+   as "exceutable" before it can be run as a program. To do this, open
+   Terminal.app and navigate (using the `cd` command) to the directory
+   where ``django-admin.py`` is installed, then run the command
+   ``chmod +x django-admin.py``.
+
 .. note::
 
     You'll need to avoid naming projects after built-in Python or Django