docs: def regroup(target, expression):
      """
      Regroups a list of alike objects by a common attribute.
  
      This complex tag is best illustrated by use of an example:  say that
      ``people`` is a list of ``Person`` objects that have ``first_name``,
      ``last_name``, and ``gender`` attributes, and you'd like to display a list
      that looks like:
  
          * Male:
              * George Bush
              * Bill Clinton
          * Female:
              * Margaret Thatcher
              * Colendeeza Rice
          * Unknown:
              * Pat Smith
  
      The following snippet of template code would accomplish this dubious task::
  
          {% regroup people by gender as grouped %}
          <ul>
          {% for group in grouped %}
              <li>{{ group.grouper }}
              <ul>
                  {% for item in group.list %}
                  <li>{{ item }}</li>
                  {% endfor %}
              </ul>
          {% endfor %}
          </ul>
  
      As you can see, ``{% regroup %}`` populates a variable with a list of
      objects with ``grouper`` and ``list`` attributes.  ``grouper`` contains the
      item that was grouped by; ``list`` contains the list of objects that share
      that ``grouper``.  In this case, ``grouper`` would be ``Male``, ``Female``
      and ``Unknown``, and ``list`` is the list of people with those genders.
  
      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 %}
  
      """
      if not target: return ''
      return [
          # List of dictionaries in the format:
          # {'grouper': 'key', 'list': [list of contents]}.
          {'grouper': key, 'list': list(val)}
          for key, val in
          groupby(obj_list, lambda v, f=expression.resolve: f(v, True))
      ]