Often it is necessary in Django to denormalize aggregation metadata about models. Whether they be votes, polls, or something else, it can often be helpful to have precomputed information about that data. This project provides an abstracted means for dealing with (simple) aggregation of models.

Update: I am looking for someone to take over maintenance of this project.

News

• August 03, 2007 - Version 0.2.1 released, added get_aggregate helper function
• August 02, 2007 - Version 0.2 released, with bugfixes and better pagination support.
• July 30, 2007 - django-simpleaggregation 0.1 initially released.

Download

The recommended download is always the "Featured" download listed to the right. To track the newest changes, follow subversion.

Note: Do not follow the instructions on the svn page. Instead, type this command:

svn checkout http://django-simpleaggregation.googlecode.com/svn/trunk/ django_simpleaggregation

Installation

Thank you for installing django-simpleaggregation.

To install, simply place this directory somewhere on your Python
path, or symlink to it from somewhere on your Python path.

Note that this application requires Python 2.3 or later, and a recent
Subversion checkout of Django. You can obtain Python from
http://www.python.org/ and Django from http://www.djangoproject.com/.

Tutorial

First, it must be added to INSTALLED_APPS:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django_simpleaggregation',
)

Now, let's set up some basic models:

from django.db import models

class Opinion(models.Model):
    title = models.CharField(maxlength=100)
    body = models.TextField()
    
    def __unicode__(self):
        return self.title

class Vote(models.Model):
    voter_name = models.CharField(maxlength=100)
    vote = models.IntegerField(choices=((-1, '-1'),(1, '+1')))
    opinion = models.ForeignKey(Opinion)
    
    def __unicode__(self):
        return u"%s voted %d for %s" % (self.voter_name, self.vote, self.opinion)

Then, run python manage.py syncdb

Let's set up an aggregate which counts how many votes a specific user casts (place this anywhere, probably right under the model):

from django_simpleaggregation import aggregates
aggregates.register(Vote, 'voter_name')

...and you're done! Wow, that was hard, wasn't it? (Rhetorical question...it was easy). This step should be familiar for anyone who is using the newforms_admin branch. In the background, a new Aggregate object is being created for each unique Vote.voter_name that is saved.

So that was easy, but not very interesting. After all, you could just do a .count() on a queryset to get the same results. So, now let's keep track of the sum of all votes (the score), but still count how many votes are cast on each object:

def vote_callback(obj, current_user_defined, increment_or_decrement):
    return current_user_defined + obj.vote

aggregates.register(Vote, 'opinion.id', vote_callback)

There are several things to note here. Firstly, we've passed in a dot-separated string representing the relationship path to take. So for every Vote.opinion.id which is unique, django_simpleaggregation will create a new Aggregate object.

Secondly, we've registered a callback function to compute some user_defined data. That callback always takes the same form of callback(obj, current_user_defined, increment_or_decrement) where obj is an instance of the registered object (Vote, in this case), current_user_defined is the value of the current user_defined data for the aggregate, and increment_or_decrement is either the string 'increment' or the string 'decrement'. This allows for different behavior depending on whether something is being incremented or decremented.

The user_defined aggregate gets set to whatever value is returned from the callback. In this case, we're simply setting it to the new score! This is a little harder, but I think we're doing pretty well.

Now lets create some views:

from mysite.example.models import Vote, Opinion
from django_simpleaggregation.helpers import AggregateAccessor
from django.shortcuts import render_to_response

def opinions(request):
    agg_access = AggregateAccessor(Vote, 'opinion.id', direction = 'descending', stop_before = 1)
    context = { 'opinions' : agg_access.get_list_by_user_defined() }
    return render_to_response('votes.html', context)

The AggregateAccessor the most complicated function in this project, so if you can get past this, you're home free. Anyways, AggregateAccessor takes these arguments:

• The model class for which the aggregate was created (the same as was registered).
• The unique field dot-separated string (the same as was registered).
• paginate_by (default is None) - The number of items to get per page.
• page (default is None) - The page of items that you would like to get.
• direction (default is 'descending') - A direction to sort the results by.
• stop_before (default is 0) - Stop this many dots back, so in our working example, 1 back. That's why the result is an Opinion object, it stops at 'opinion'. If it were set to 0, it would stop at 'id', which is not very useful in this case.
• unique (default is True) - It's possible to have aggregates on non-unique fields. If unique is set to False, a sorted list of lists of related objects will be set up to be returned, instead of a simple list.

Once you have that AggregateAccessor instance, you can get the objects by using either get_list_by_count() or get_list_by_user_defined().

Our result is a list of opinion objects. But that's not much good unless we display it. Let's do that now:

{% load simpleaggregation %}

{% for opinion in opinions %}
    {% get_aggregate opinion.vote_set.all opinion.id as aggregate %}
    <h1>{{ opinion.title }}</h1>
    <p>{{ opinion.body }}</p>
    <p>Number of Votes: {{ aggregate.count }}</p>
    <p>Score: {{ aggregate.user_defined }}</p>
{% endfor %}

Now, first things first, yes I know that this is totally incorrect HTML, but since it's a tutorial, let's forget about that. get_aggregate takes two possibilities as the its first argument:

1. An object instance whose class has been registered for aggregation.
2. An iterable of those object instances (the first value will be taken) for convenience, as you can see in our working example.

Well, that's all there is for now. Please post tickets, email me, add wiki pages, etc with comments, suggestions, or just to chat!

Pagination

Pagination is now possible using django_simpleaggregation, as you may have noticed in the argument list to AggregateAccessor. Passing in keywords 'paginate_by' and 'page' will result in a single page to return upon the next get_list_by_count() or get_list_by_user_defined().

After one of those two methods is called, another method on the AggregateAccessor is useful: get_pagination_dict().

get_pagination_dict() returns a dictionary of some common pagination properties:

1. has_next - Boolean which determines whether there is a next page
2. has_previous - Boolean which determines whether there is a previous page
3. next - The number of the next page
4. previous - The number of the previous page
5. is_paginated - Boolean which determines whether there is any pagination at all

Also, each of those are accessible as methods on the AggregateAccessor instance. For example, if you have an AggregateAccessor instance called agg_access, calling agg_access.has_next() will be the exact same thing as agg_access.get_pagination_dict()['has_next'].

More

More is coming, but for now this is all. Oh, and I assume no responsibility if this breaks your code, your database, or your life in some way.