a points, positions and levels app for Django
Python HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.


Pinax Points

CircleCi Codecov

Table of Contents

About Pinax

Pinax is an open-source platform built on the Django Web Framework. It is an ecosystem of reusable Django apps, themes, and starter project templates. This collection can be found at http://pinaxproject.com.



pinax-points is a points, positions and levels app for Django.


pinax-points provides the ability to track points on arbitrary objects in your system. The common case being User instances. It can additionally keep track of positions for these objects to produce leaderboards.

Supported Django and Python versions

Django \ Python 2.7 3.4 3.5 3.6
1.11 * * * *
2.0 * * *



To install pinax-points:

    $ pip install pinax-points

Add pinax.points to your INSTALLED_APPS setting:

        # other apps


Setting and Getting Points

award_points(target, value, reason="", source=None)

Award points to any model instance by invoking award_points().

    from pinax.points.models import award_points
    award_points(user, 50)

Obtain points awarded based on argument criteria.

    from pinax.points.models import points_awarded
    points = points_awarded(user)

Template Display

To display overall points for an object, use templatetag points_for_object to set and display a context variable:

    {% load pinax_points_tags %}
    {% points_for_object user as points %}
    <div class="user-points">{{ points }}</div>

Although this example shows points for a User, any type of model instance is valid. For example if you want to display points for a blog post:

    {% load pinax_points_tags %}
    {% points_for_object post as points %}
    <div class="post-points">{{ points }}</div>



Triggered when points are awarded to an object.

providing_args=["target", "key", "points", "source"]

Template Tags


Returns the current points for an object.


    {% points_for_object user %}


    {% points_for_object user as points %}


    {% points_for_object user limit 7 days as points %}

Returns a queryset of the model passed in with points annotated.


    {% top_objects "auth.User" as top_users limit 10 %}


    {% top_objects "auth.User" as top_users %}


    {% top_objects "auth.User" as top_users limit 10 timeframe 7 days %}

Returns True if user has voted on obj, False otherwise.


    {% user_has_voted user obj as var %}

Change Log


  • Improve usage documentation
  • Improving tox.ini syntax
  • Standardizing setup.py and docs
  • Improving .gitignore
  • Standardize documentation layout
  • Drop Django v1.8, 1.9, 1.10 support
  • Drop Python 3.3 support
  • Add Django 2.0 support
  • Move documentation into README.md
  • Convert CI and coverage to CircleCi and CodeCov
  • Add PyPi-compatible long description


  • updated to




pinax-points was formerly known as agon. The code was mostly extracted from typewar and made slightly more generic to work well.


For an overview on how contributing to Pinax works read this blog post and watch the included video, or read our How to Contribute section. For concrete contribution ideas, please see our Ways to Contribute/What We Need Help With section.

In case of any questions we recommend you join our Pinax Slack team and ping us there instead of creating an issue on GitHub. Creating issues on GitHub is of course also valid but we are usually able to help you faster if you ping us in Slack.

We also highly recommend reading our blog post on Open Source and Self-Care.

Code of Conduct

In order to foster a kind, inclusive, and harassment-free community, the Pinax Project has a code of conduct. We ask you to treat everyone as a smart human programmer that shares an interest in Python, Django, and Pinax with you.

Connect with Pinax

For updates and news regarding the Pinax Project, please follow us on Twitter @pinaxproject and check out our Pinax Project blog.


Copyright (c) 2012-2018 James Tauber and contributors under the MIT license.