django-objectcounters 0.1

Associate counters with Django model records.

Object Counters for Django
==========================

This is a simple app for associating named integer values with
arbitrary Django model objects.

Using counters allows you to keep scalar values out of your models.
Instead of this:

class Person(models.Model):
name = models.CharField(...)
number_of_friends_total = models.IntegerField(...)
number_of_friends_recent = models.IntegerField(...)
number_of_friends_last_month = models.IntegerField(...)

You can do this:

capt = Person.objects.get(name='Jean-Luc Picard')
Counter.objects.create_for_object('friends_total', capt, 1014)

And:

last = Counter.objects.get_for_object('friends_last_month', capt)
last.value += -3 # lost the away team.
last.save()

The approach of reading and writing values in a separate model allows
you to evolve some of your data without touching the models. And it
keeps your models a bit more tidy.

Install
-------

Pull down the app:

$ pip install django-objectcounters

Add it to your `INSTALLED_APPS`:

INSTALLED_APPS = (
...
'objectcounters'
)

Sync your database:

$ ./manage.py syncdb --migrate

To run the sample app, make sure you've got generic admin installed globally
(ugh), or better yet, create a new virtual env and install it there with the
sample.


Python Usage
-------------

The `Counter` model is a regular Django model, so you can create, read, update
and delete records in the usual way. Additionally, the model provides a manager
with a few more methods:

1. `Counter.get_for_object(name, instance, **kwargs)`

Use this method to get an existing counter for an object. Pass in the name of
the counter, like 'total-holodeck-hours', and a model instance. Keyword
arguments are passed thru to the `get()` call.

2. `Counter.get_value_for_object(self, name, instance, default=0, **kwargs)`

Use this method when you need just the value of a counter and not the counter
record. Keyword arguments are passed thru to the `get()` call.

3. `Counter.create_for_object(self, name, instance, value=0)`

This is just like Django's `get_or_create` and returns the same kind of
two-tuple. Use this when you need to get a counter and create it if necessary
in one step.



Template Usage
--------------

You can also enable counters inside of templates pretty easily.

In your templates, load the tag:

`{% load counter_tags %}`

Then you can render values like this:

<span>
{% counter_for_object "monthly_shack_visits" user as visits %}
I went to Shake Shack {{ visits }} times this month.`
</span>