django-generic-counter 0.0.6

[](https://travis-ci.org/0x07Ltd/django-generic-counter) [](https://coveralls.io/github/0x07Ltd/django-generic-counter?branch=master)
django-generic-counter
======================

This small Django app provides a simple `Counter` model which consists of a `name` and an integer
`count`. It can be used any time you need to keep a tally of something, or store an arbitrary number
in the database.

For example, when using a [CouchDB change listener](http://guide.couchdb.org/draft/notifications.html)
it may be useful to keep a track of the `seq` number you've reached in the database in order to
continue from the point at which you left off.

Usage
-----

Include `django_generic_counter` in your `INSTALLED_APPS`, then use the Counter like so:

```python
from django_generic_counter import Counter

c = Counter(name="Green bottles hanging on the wall", count=10)
assert int(c) == 10, "Ten green bottles hanging on the wall"
assert c.count == 10, "Ten green bottles hanging on the wall"
c -= 1 # And if one green bottle should accidentally fall
assert int(c) == 9, "There'll be nine green bottles hanging on the wall"
```

The following are features of the Counter object:
- Assignment addition `c += 10`
- Assignment subtraction `c -= 10`
- Cast to int `int(c)`
- Set count to absolute value immediately locally and in database `c.set_count(1337)`

Usage with South
----------------

The migrations for this project in the `migrations` directory have been made using Django 1.8. This means that if you're using South you must tell it to look in the `south_migrations` directory for its migrations by putting the following in your settings file:

```python
SOUTH_MIGRATION_MODULES = {
'django_generic_counter': 'django_generic_counter.south_migrations'
}
```

Example
-------------
The following is a concrete example of the usage of a `Counter` when applied to keep track of the
`seq` number of a CouchDB change listener.

```python
class ChangeListener:

def __init__(self, db_name, seq_counter_name, change_handler):
self.db_name = db_name
self.seq_counter_name = seq_counter_name
self.change_handler = change_handler

@property
def seq(self):
"""
Gets the seq counter for this change listener and returns its count. If no counter is
found, returns 0.
"""
try:
return int(Counter.objects.get(name=self.seq_counter_name))
except Counter.DoesNotExist:
return 0

@seq.setter
def seq(self, seq):
"""
Gets or creates the seq counter for this change listener and sets its count to 'seq'.
"""
counter, _ = Counter.objects.get_or_create(name=self.seq_counter_name)
counter.set_count(seq)

def run(self):
"""
Wait for changes and pass them to `self.change_handler` as they occur.
"""
db = get_db(self.db_name)
changes_stream = ChangesStream(db, feed="continuous", heartbeat=True, since=self.seq)
for change in changes_stream:
if self.change_handler(db, change):
self.seq = change["seq"]
```