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

[jedie]

​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'])

[jedie]

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

[anonymous]

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.

[jedie]

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!

[Adam Vandenberg]

Attempt at clarifying the regroup docs.

[Michael Radziej]

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.

[Michael Radziej]

patch to improve the documentation; replaces previous patches

[Michael Radziej]

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

[James Bennett]

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.

[Jacob]

Milestone 1.0 deleted