newforms-admin: Merged from trunk up to [7877].

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7881 bcc190cf-cafb-0310-a4f2-bffc1f526a37

5 files changed, 54 insertions, 49 deletions

diff --git a/docs/generic_views.txt b/docs/generic_views.txt
index b7beb0b4be..c4fea21016 100644
--- a/docs/generic_views.txt
+++ b/docs/generic_views.txt
@@ -816,15 +816,14 @@ specify the page number in the URL in one of two ways:
 These values and lists are 1-based, not 0-based, so the first page would be
 represented as page ``1``. 
 
-An example of the use of pagination can be found in the `object pagination`_
-example model. 
+For more on pagination, read the `pagination documentation`_.
 	 
-.. _`object pagination`: ../models/pagination/
+.. _`pagination documentation`: ../pagination/
 
 **New in Django development version:** 
 
-As a special case, you are also permitted to use 
-``last`` as a value for ``page``::
+As a special case, you are also permitted to use ``last`` as a value for
+``page``::
 
     /objects/?page=last
 
diff --git a/docs/newforms.txt b/docs/newforms.txt
index 824bdb7ea1..530c9ce828 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1334,23 +1334,12 @@ given length.
     * Validates that non-empty file data has been bound to the form.
     * Error message keys: ``required``, ``invalid``, ``missing``, ``empty``
 
-An ``UploadedFile`` object has two attributes:
-
-    ======================  ====================================================
-    Attribute               Description
-    ======================  ====================================================
-    ``filename``            The name of the file, provided by the uploading
-                            client.
-                            
-    ``content``             The array of bytes comprising the file content.
-    ======================  ====================================================
-
-The string representation of an ``UploadedFile`` is the same as the filename
-attribute.
+To learn more about the ``UploadedFile`` object, see the `file uploads documentation`_.
 
 When you use a ``FileField`` in a form, you must also remember to
 `bind the file data to the form`_.
 
+.. _file uploads documentation: ../upload_handling/
 .. _`bind the file data to the form`: `Binding uploaded files to a form`_
 
 ``FilePathField``
diff --git a/docs/pagination.txt b/docs/pagination.txt
index 486c92264b..bfdf8eea1c 100644
--- a/docs/pagination.txt
+++ b/docs/pagination.txt
@@ -59,6 +59,11 @@ page::
     ...
     InvalidPage
 
+Note that you can give ``Paginator`` a list/tuple or a Django ``QuerySet``. The
+only difference is in implementation; if you pass a ``QuerySet``, the
+``Paginator`` will call its ``count()`` method instead of using ``len()``,
+because the former is more efficient.
+
 ``Paginator`` objects
 =====================
 
@@ -77,6 +82,21 @@ Attributes
 
 ``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
 
+``InvalidPage`` exceptions
+==========================
+
+The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
+(i.e., not an integer) or contains no objects. Generally, it's enough to trap
+the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
+either of the following exceptions:
+
+``PageNotAnInteger`` -- Raised when ``page()`` is given a value that isn't an integer.
+
+``EmptyPage`` -- Raised when ``page()`` is given a valid value but no objects exist on that page.
+
+Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
+them both with a simple ``except InvalidPage``.
+
 ``Page`` objects
 ================
 
@@ -116,13 +136,6 @@ Attributes
 
 ``paginator`` -- The associated ``Paginator`` object.
 
-``QuerySetPaginator`` objects
-=============================
-
-Use ``QuerySetPaginator`` instead of ``Paginator`` if you're paginating across
-a ``QuerySet`` from Django's database API. This is slightly more efficient, and
-there are no API differences between the two classes.
-
 The legacy ``ObjectPaginator`` class
 ====================================
 
diff --git a/docs/settings.txt b/docs/settings.txt
index 4566eea1f9..d7715714d3 100644
--- a/docs/settings.txt
+++ b/docs/settings.txt
@@ -279,7 +279,7 @@ Default: ``''`` (Empty string)
 
 The database backend to use. The build-in database backends are
 ``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'mysql_old'``,
-``'sqlite3'``, ``'oracle'``, and ``'oracle'``.
+``'sqlite3'``, and ``'oracle'``.
 
 In the Django development version, you can use a database backend that doesn't
 ship with Django by setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e.
diff --git a/docs/upload_handling.txt b/docs/upload_handling.txt
index 34cd085ac9..3b88ce4e3d 100644
--- a/docs/upload_handling.txt
+++ b/docs/upload_handling.txt
@@ -22,7 +22,7 @@ Consider a simple form containing a ``FileField``::
     class UploadFileForm(forms.Form):
         title = forms.CharField(max_length=50)
         file  = forms.FileField()
-        
+
 A view handling this form will receive the file data in ``request.FILES``, which
 is a dictionary containing a key for each ``FileField`` (or ``ImageField``, or
 other ``FileField`` subclass) in the form. So the data from the above form would
@@ -64,34 +64,34 @@ methods to access the uploaded content:
     ``UploadedFile.read()``
         Read the entire uploaded data from the file. Be careful with this
         method: if the uploaded file is huge it can overwhelm your system if you
-        try to read it into memory. You'll probably want to use ``chunk()``
+        try to read it into memory. You'll probably want to use ``chunks()``
         instead; see below.
-        
+
     ``UploadedFile.multiple_chunks()``
         Returns ``True`` if the uploaded file is big enough to require
         reading in multiple chunks. By default this will be any file
         larger than 2.5 megabytes, but that's configurable; see below.
-    
+
     ``UploadedFile.chunk()``
         A generator returning chunks of the file. If ``multiple_chunks()`` is
         ``True``, you should use this method in a loop instead of ``read()``.
-        
+
         In practice, it's often easiest simply to use ``chunks()`` all the time;
         see the example below.
-    
+
     ``UploadedFile.file_name``
         The name of the uploaded file (e.g. ``my_file.txt``).
-        
+
     ``UploadedFile.file_size``
         The size, in bytes, of the uploaded file.
-        
+
 There are a few other methods and attributes available on ``UploadedFile``
 objects; see `UploadedFile objects`_ for a complete reference.
 
 Putting it all together, here's a common way you might handle an uploaded file::
-    
+
     def handle_uploaded_file(f):
-        destination = open('some/file/name.txt', 'wb')
+        destination = open('some/file/name.txt', 'wb+')
         for chunk in f.chunks():
             destination.write(chunk)
 
@@ -126,27 +126,27 @@ Three `settings`_ control Django's file upload behavior:
         The maximum size, in bytes, for files that will be uploaded
         into memory. Files larger than ``FILE_UPLOAD_MAX_MEMORY_SIZE``
         will be streamed to disk.
-        
+
         Defaults to 2.5 megabytes.
-        
+
     ``FILE_UPLOAD_TEMP_DIR``
         The directory where uploaded files larger than ``FILE_UPLOAD_TEMP_DIR``
         will be stored.
-        
+
         Defaults to your system's standard temporary directory (i.e. ``/tmp`` on
         most Unix-like systems).
-        
+
     ``FILE_UPLOAD_HANDLERS``
         The actual handlers for uploaded files. Changing this setting
         allows complete customization -- even replacement -- of
         Django's upload process. See `upload handlers`_, below,
         for details.
-        
+
         Defaults to::
-        
+
             ("django.core.files.uploadhandler.MemoryFileUploadHandler",
              "django.core.files.uploadhandler.TemporaryFileUploadHandler",)
-            
+
         Which means "try to upload to memory first, then fall back to temporary
         files."
 
@@ -161,35 +161,39 @@ All ``UploadedFile`` objects define the following methods/attributes:
         Returns a byte string of length ``num_bytes``, or the complete file if
         ``num_bytes`` is ``None``.
 
-    ``UploadedFile.chunk(self, chunk_size=None)``
+    ``UploadedFile.chunks(self, chunk_size=None)``
         A generator yielding small chunks from the file. If ``chunk_size`` isn't
-        given, chunks will be 64 kb.
+        given, chunks will be 64 KB.
 
     ``UploadedFile.multiple_chunks(self, chunk_size=None)``
         Returns ``True`` if you can expect more than one chunk when calling
-        ``UploadedFile.chunk(self, chunk_size)``.
+        ``UploadedFile.chunks(self, chunk_size)``.
 
     ``UploadedFile.file_size``
         The size, in bytes, of the uploaded file.
-    
+
     ``UploadedFile.file_name``
         The name of the uploaded file as provided by the user.
-    
+
     ``UploadedFile.content_type``
         The content-type header uploaded with the file (e.g. ``text/plain`` or
         ``application/pdf``). Like any data supplied by the user, you shouldn't
         trust that the uploaded file is actually this type. You'll still need to
         validate that the file contains the content that the content-type header
         claims -- "trust but verify."
-    
+
     ``UploadedFile.charset``
         For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied
         by the browser. Again, "trust but verify" is the best policy here.
 
+    ``UploadedFile.__iter__()``
+        Iterates over the lines in the file.
+
     ``UploadedFile.temporary_file_path()``
         Only files uploaded onto disk will have this method; it returns the full
         path to the temporary uploaded file.
 
+
 Upload Handlers
 ===============