Pluggable rating fields in Django.
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1 commit ahead, 49 commits behind dcramer:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A generic ratings module. The field itself appends two additional fields on the model, for optimization reasons. It adds <field>_score, and <field>_votes fields, which are both integer fields.


You will need to add djangoratings to your INSTALLED_APPS:


Finally, run python syncdb in your application's directory to create the tables.

Setup your models

The way django-ratings is built requires you to attach a RatingField to your models. This field will create two columns, a votes column, and a score column. They will both be prefixed with your field name:

from djangoratings import RatingField

class MyModel(models.Model):
    rating = RatingField(range=5) # 5 possible rating values, 1-5

Alternatively you could do something like:

from djangoratings import AnonymousRatingField

class MyModel(models.Model):
    rating = AnonymousRatingField(range=10)

If you'd like to use the built-in weighting methods, to make it appear more difficult for an object to obtain a higher rating, you can use the weight kwarg:

class MyModel(models.Model):
    rating = RatingField(range=10, weight=10)

Using the model API

And adding votes is also simple:

myinstance.rating.add(score=1, user=request.user, ip_address=request.META['REMOTE_ADDR'])

Retrieving votes is just as easy:

myinstance_ai.get_rating(request.user, request.META['REMOTE_ADDR'])

Accessing information about the rating of an object is also easy:

# these do not hit the database

How you can order by top-rated using an algorithm (example from source):

# In this example, ``rating`` is the attribute name for your ``RatingField``
qs = qs.extra(select={
    'rating': '((100/%s*rating_score/(rating_votes+%s))+100)/2' % (MyModel.rating.range, MyModel.rating.weight)
qs = qs.order_by('-rating')

Get recent ratings for your instance:

# This returns ``Vote`` instances.

Get the percent of voters approval:


Get that same percentage, but excluding your weight:


Generic Views: Processing Votes

The best way to use the generic views is by extending it, or calling it within your own code:

from djangoratings.views import AddRatingFromModule

urlpatterns = patterns('',
    url(r'rate-my-post/(?P<object_id>\d+)/(?P<score>\d+)/', AddRatingFromModel(), {
        'app_label': 'blogs',
        'model': 'post',

Another example, on Nibbits we use a basic API interface, and we simply call the AddRatingView within our own view:

from djangoratings.views import AddRatingView

# For the sake of this actually looking like documentation:
params = {
    'content_type_id': 23,
    'object_id': 34,
    'field_name': 'ratings', # this should match the field name defined in your model
    'score': 1, # the score value they're sending
response = AddRatingView()(request, **params)
if response.status_code == 200:
    if response.content == 'Vote recorded.':
    return {'message': response.content, 'score': params['score']}
return {'error': 9, 'message': response.content}