Ticket #10239: ticket10239.patch

django/forms/models.py

@@ -139 +139 @@
     ``exclude`` is an optional list of field names. If provided, the named
     fields will be excluded from the returned fields, even if they are listed
     in the ``fields`` argument.
+
+    ``widgets`` is a dictionary of model field names mapped to a widget 
+
+    ``formfield_callback`` is a callable that takes a model field and returns 
+    a form field.
     """
     field_list = []
     ignored = []
@@ -369 +374 @@
 
 def modelform_factory(model, form=ModelForm, fields=None, exclude=None,
                        formfield_callback=None):
+    """
+    Returns a ``SortedDict`` containing form fields for the given model.
+
+    ``fields`` is an optional list of field names. If provided, only the named
+    fields will be included in the returned fields.
+
+    ``exclude`` is an optional list of field names. If provided, the named
+    fields will be excluded from the returned fields, even if they are listed
+    in the ``fields`` argument.
+
+    ``widgets`` is a dictionary of model field names mapped to a widget 
+
+    ``formfield_callback`` is a callable that takes a model field and returns 
+    a form field.
+    """
     # Create the inner Meta class. FIXME: ideally, we should be able to
     # construct a ModelForm without creating and passing in a temporary
     # inner class.

docs/topics/forms/modelforms.txt

@@ -533 +533 @@
 :ref:`Validating objects <validating-objects>` for more information on the
 model's ``clean()`` hook.
 
+ModelForm factory function
+--------------------------
+
+You can create forms from a given model using the standalone function
+``modelformset_factory``, instead of using a class definition. This 
+may be more convenient if you do not have many customisations to make::
+
+    >>> from django.forms.models import modelform_factory
+    >>> BookForm = modelform_factory(Book)
+
+This can also be used to make simple modifications to existing forms, for 
+example by specifying which fields should be displayed::
+
+    >>> Form = modelform_factory(Book, form=BookForm, fields=("author",))
+
+... or which fields should be excluded::
+
+    >>> Form = modelform_factory(Book, form=BookForm, exclude=("title",))
+
+You can also specify the widgets to be used for a given field::
+
+    >>> from django.forms import Textarea
+    >>> Form = modelform_factory(Book, form=BookForm, widgets={"title": Textarea()})
+
 .. _model-formsets:
 
 Model formsets