Opened 4 years ago

Closed 4 years ago

Last modified 4 years ago

#30917 closed Cleanup/optimization (fixed)

Clarify Formset documentation.

Reported by: Ken Whitesell Owned by: Ken Whitesell
Component: Documentation Version: dev
Severity: Normal Keywords: Formset
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

I believe the documentation for formsets is either misleading or possibly
incorrect.

From the existing documentation at
https://docs.djangoproject.com/en/2.2/topics/forms/formsets/

You might want to allow the user to create several articles at once. 
To create a formset out of an ArticleForm you would do:
   
>>> from django.forms import formset_factory
>>> ArticleFormSet = formset_factory(ArticleForm)
   
You now have created a formset named ArticleFormSet.

It's my understanding that *at this point* you have not yet created a formset.
What you have done is create a formset class, from which you can create
instances of formsets.

It's not until you execute this line:

>>> formset = ArticleFormSet()


that you have actually created the formset.

By analogy, consider the detail provided for both Models and Forms.
On the page https://docs.djangoproject.com/en/2.2/ref/models/instances/
it is specified that "To create a new instance of a model, instantiate it like
any other Python class:"

Likewise, with Forms, at https://docs.djangoproject.com/en/2.2/ref/forms/api/
it states: "To create an unbound Form instance, simply instantiate the class:"

In both these cases, the distinction is made that there's a fundamental
difference between creating the Model and Form classes, and creating the
instances of those classes.

I believe the same distinction should be made with reference to Formsets,
making it explicitly clear that the formset_factory function creates a
class, and the class needs to be instantiated to create the instances to
be used within a page.

Change History (7)

comment:1 by Ken Whitesell, 4 years ago

Owner: changed from nobody to Ken Whitesell
Status: newassigned

comment:2 by Ken Whitesell, 4 years ago

Has patch: set

comment:3 by Carlton Gibson, 4 years ago

Triage Stage: UnreviewedAccepted
Type: BugCleanup/optimization

comment:4 by Carlton Gibson, 4 years ago

Summary: Formset documentationClarify Formset documentation.

comment:5 by Carlton Gibson <carlton.gibson@…>, 4 years ago

Resolution: fixed
Status: assignedclosed

In 4c762588:

Fixed #30917 -- Clarified formsets topic documentation.

comment:6 by Carlton Gibson <carlton.gibson@…>, 4 years ago

In 574f2385:

[3.0.x] Fixed #30917 -- Clarified formsets topic documentation.

Backport of 4c762588ff6748a9a9bad111894fd418c43b74a9 from master

comment:7 by Carlton Gibson <carlton.gibson@…>, 4 years ago

In 9d15f1ea:

[2.2.x] Fixed #30917 -- Clarified formsets topic documentation.

Backport of 4c762588ff6748a9a9bad111894fd418c43b74a9 from master

Note: See TracTickets for help on using tickets.
Back to Top