Opened 16 years ago

Closed 16 years ago

Last modified 12 years ago

#7863 closed (worksforme)

Documentation fix: Stress that template tag "regroup" needs a sorted list

Reported by: jedie Owned by: nobody
Component: Documentation Version: dev
Severity: Keywords:
Cc: django@… Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

regroup does only a right job, if the list is sorted with the key for the grouping?!?

Example:
Source data:

people = [
    {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
    {'first_name': 'Pat', 'last_name': 'Smith2', 'gender': 'Unknown'},
    {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
    {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
    {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
    {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
]

Template tag:

{% regroup people by gender as grouped %}

Result:

 u'grouped': [{'grouper': 'Male',
                     'list': [{'first_name': 'George',
                               'gender': 'Male',
                               'last_name': 'Bush'}]},
                    {'grouper': 'Unknown',
                     'list': [{'first_name': 'Pat',
                               'gender': 'Unknown',
                               'last_name': 'Smith2'}]},
                    {'grouper': 'Female',
                     'list': [{'first_name': 'Condoleezza',
                               'gender': 'Female',
                               'last_name': 'Rice'}]},
                    {'grouper': 'Male',
                     'list': [{'first_name': 'Bill',
                               'gender': 'Male',
                               'last_name': 'Clinton'}]},
                    {'grouper': 'Unknown',
                     'list': [{'first_name': 'Pat',
                               'gender': 'Unknown',
                               'last_name': 'Smith'}]},
                    {'grouper': 'Female',
                     'list': [{'first_name': 'Margaret',
                               'gender': 'Female',
                               'last_name': 'Thatcher'}]}]}

work a round, using sorted, e.g:

people = sorted(people, key=lambda x: x['gender'])

Attachments (3)

defaulttags_patch.txt (539 bytes ) - added by jedie 16 years ago.
r8016-regroup-sorted.diff (777 bytes ) - added by Adam Vandenberg 16 years ago.
Attempt at clarifying the regroup docs.
7863-take-3.diff (770 bytes ) - added by Michael Radziej 16 years ago.
patch to improve the documentation; replaces previous patches

Download all attachments as: .zip

Change History (11)

by jedie, 16 years ago

Attachment: defaulttags_patch.txt added

comment:1 by jedie, 16 years ago

Component: Template systemDocumentation
Summary: template tag "regroup" needs a sorted list...More info on template tag "regroup" (needs a sorted list)

OK, now i see in the sourcecode ./django/template/defaulttags.py this:

    Note that `{% regroup %}`` does not work when the list to be grouped is not
    sorted by the key you are grouping by!  This means that if your list of
    people was not sorted by gender, you'd need to make sure it is sorted
    before using it, i.e.::

        {% regroup people|dictsort:"gender" by gender as grouped %}

IMHO this should be added to the docu: http://www.djangoproject.com/documentation/templates/#regroup

comment:2 by anonymous, 16 years ago

The docs already mention this: Note that {% regroup %} does not order its input! Our example relies on the fact that the people list was ordered by gender in the first place.

comment:3 by jedie, 16 years ago

Yes. But IMHO it should be made many clearer.

btw. regroup without a dict sort makes IMHO no sense, so it should made a dict sort by default!

by Adam Vandenberg, 16 years ago

Attachment: r8016-regroup-sorted.diff added

Attempt at clarifying the regroup docs.

comment:4 by Michael Radziej, 16 years ago

Has patch: set
milestone: 1.0 beta
Triage Stage: UnreviewedReady for checkin

Please, let's drop the first patch (defaulttags_patch.txt), which changes the behaviour of the tag. The current behaviour is intended, and I don't think that the core developers want to change it. But you're right about the docs.

While the current docs mention that you have to sort before using the tag, it does so only after a lengthy explanation with many examples. The sorting requirement should better go before the examples. I have amended your patch so that its style fits the other tag descriptions.

Since it's a kind of documentation buggie, I put this into the 1.0beta milestone.

by Michael Radziej, 16 years ago

Attachment: 7863-take-3.diff added

patch to improve the documentation; replaces previous patches

comment:5 by Michael Radziej, 16 years ago

Summary: More info on template tag "regroup" (needs a sorted list)Documentation fix: Stress that template tag "regroup" needs a sorted list

comment:6 by Michael Radziej, 16 years ago

milestone: 1.0 beta1.0

Sorry, just learned that normal bugs go to the 1.0 milestone, not 1.0beta.

comment:7 by James Bennett, 16 years ago

Resolution: worksforme
Status: newclosed

Since the docs already do mention this, I don't see a bug here; yes, the explanation comes after the example, but until you've seen the example of what regroup does it wouldn't make sense to explain why the initial ordering matters.

comment:8 by Jacob, 12 years ago

milestone: 1.0

Milestone 1.0 deleted

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