Fixed #14655 -- Made formsets iterable. This allows a slightly more natural iteration API (`for form in formsets`), and allows you to easily override the form rendering order. Thanks to Kent Hauser for the suggestion and patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14986 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 25 insertions, 11 deletions

diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt
index db53fc296a..8280c7736f 100644
--- a/docs/topics/forms/formsets.txt
+++ b/docs/topics/forms/formsets.txt
@@ -23,7 +23,7 @@ the ability to iterate over the forms in the formset and display them as you
 would with a regular form::
 
     >>> formset = ArticleFormSet()
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
     <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
@@ -35,6 +35,20 @@ display two blank forms::
 
     >>> ArticleFormSet = formset_factory(ArticleForm, extra=2)
 
+.. versionchanged:: 1.3
+
+Prior to Django 1.3, formset instances were not iterable. To render
+the formset you iterated over the ``forms`` attribute::
+
+    >>> formset = ArticleFormSet()
+    >>> for form in formset.forms:
+    ...     print form.as_table()
+
+Iterating over ``formset.forms`` will render the forms in the order
+they were created. The default formset iterator also renders the forms
+in this order, but you can change this order by providing an alternate
+implementation for the :method:`__iter__()` method.
+
 Using initial data with a formset
 ---------------------------------
 
@@ -50,7 +64,7 @@ example::
     ...      'pub_date': datetime.date.today()},
     ... ])
 
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Django is now open source" id="id_form-0-title" /></td></tr>
     <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-12" id="id_form-0-pub_date" /></td></tr>
@@ -77,7 +91,7 @@ limit the maximum number of empty forms the formset will display::
 
     >>> ArticleFormSet = formset_factory(ArticleForm, extra=2, max_num=1)
     >>> formset = ArticleFormset()
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
     <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
@@ -250,7 +264,7 @@ Lets create a formset with the ability to order::
     ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
     ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
     ... ])
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
     <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" value="2008-05-10" id="id_form-0-pub_date" /></td></tr>
@@ -306,7 +320,7 @@ Lets create a formset with the ability to delete::
     ...     {'title': u'Article #1', 'pub_date': datetime.date(2008, 5, 10)},
     ...     {'title': u'Article #2', 'pub_date': datetime.date(2008, 5, 11)},
     ... ])
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ....    print form.as_table()
     <input type="hidden" name="form-TOTAL_FORMS" value="3" id="id_form-TOTAL_FORMS" /><input type="hidden" name="form-INITIAL_FORMS" value="2" id="id_form-INITIAL_FORMS" /><input type="hidden" name="form-MAX_NUM_FORMS" id="id_form-MAX_NUM_FORMS" />
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" value="Article #1" id="id_form-0-title" /></td></tr>
@@ -360,7 +374,7 @@ default fields/attributes of the order and deletion fields::
 
     >>> ArticleFormSet = formset_factory(ArticleForm, formset=BaseArticleFormSet)
     >>> formset = ArticleFormSet()
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-title">Title:</label></th><td><input type="text" name="form-0-title" id="id_form-0-title" /></td></tr>
     <tr><th><label for="id_form-0-pub_date">Pub date:</label></th><td><input type="text" name="form-0-pub_date" id="id_form-0-pub_date" /></td></tr>
@@ -393,7 +407,7 @@ The ``manage_articles.html`` template might look like this:
     <form method="post" action="">
         {{ formset.management_form }}
         <table>
-            {% for form in formset.forms %}
+            {% for form in formset %}
             {{ form }}
             {% endfor %}
         </table>
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index 23ed9a79ae..eb55aaf397 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -684,7 +684,7 @@ so long as the total number of forms does not exceed ``max_num``::
 
     >>> AuthorFormSet = modelformset_factory(Author, max_num=4, extra=2)
     >>> formset = AuthorFormSet(queryset=Author.objects.order_by('name'))
-    >>> for form in formset.forms:
+    >>> for form in formset:
     ...     print form.as_table()
     <tr><th><label for="id_form-0-name">Name:</label></th><td><input id="id_form-0-name" type="text" name="form-0-name" value="Charles Baudelaire" maxlength="100" /><input type="hidden" name="form-0-id" value="1" id="id_form-0-id" /></td></tr>
     <tr><th><label for="id_form-1-name">Name:</label></th><td><input id="id_form-1-name" type="text" name="form-1-name" value="Paul Verlaine" maxlength="100" /><input type="hidden" name="form-1-id" value="3" id="id_form-1-id" /></td></tr>
@@ -778,7 +778,7 @@ itself::
 
     <form method="post" action="">
         {{ formset.management_form }}
-        {% for form in formset.forms %}
+        {% for form in formset %}
             {{ form }}
         {% endfor %}
     </form>
@@ -791,7 +791,7 @@ Third, you can manually render each field::
 
     <form method="post" action="">
         {{ formset.management_form }}
-        {% for form in formset.forms %}
+        {% for form in formset %}
             {% for field in form %}
                 {{ field.label_tag }}: {{ field }}
             {% endfor %}
@@ -804,7 +804,7 @@ if you were rendering the ``name`` and ``age`` fields of a model::
 
     <form method="post" action="">
         {{ formset.management_form }}
-        {% for form in formset.forms %}
+        {% for form in formset %}
             {{ form.id }}
             <ul>
                 <li>{{ form.name }}</li>