Skip to main content

Django app for efficiently measuring usage

Project description

PyPI Build Status Coverage Report

How active are users on your Django site? Django can tell you when users registered (User.date_joined) and when they signed in (User.last_login). But sessions are long-lived so this doesn’t really answer the question.

Souvenirs is a Django app for efficiently measuring user activity over time, and making that information available through an API.

Souvenirs Album Cover


Get the latest stable release from PyPI

pip install django-souvenirs

Or the latest commit from GitHub

pip install -e git+git://

Add to


Migrate your database

./ migrate souvenirs


There are two core API calls: souvenez (“remember”) and count_active_users.

You can call souvenez(user) as often per user as you’d like, by default it will rate-limit DB entries to once per hour. If you use the provided middleware, then souvenez will be called automatically on each request.

Call count_active_users to find the number of unique users active for a given time period. For example:

>>> from souvenirs.control import count_active_users
>>> from django.utils import timezone
>>> from datetime import timedelta
>>> now =
>>> count_active_users(start=now - timedelta(days=1), end=now)

Either start or end can be omitted, which makes the query unbounded in that direction. The above call is effectively the same as omitting end:

>>> count_active_users( - timedelta(days=1))

and this counts the total number of users active for all time, or at least since you installed the middleware:

>>> count_active_users()


Souvenirs provides some functions for reporting registered users and activity over a period of time. For example, to see activity per calendar month for 2016:

>>> from datetime import datetime
>>> from django.utils import timezone
>>> from souvenirs.reports import calendar_monthly_usage
>>> start = datetime(2016, 1, 1)  # inclusive
>>> end = datetime(2017, 1, 1)    # exclusive
>>> for d in calendar_monthly_usage(start=timezone.make_aware(start),
...   print(d['labels']['calendar_year_month'],
            d['usage']['activated_users'],  # User.is_active
2016-01 12  10  9
2016-02 20  13  11
2016-03 38  16  10
2016-04 38  28  14
2016-05 38  29  20
2016-06 57  46  37
2016-07 62  58  43
2016-08 117 80  49
2016-09 175 300 75
2016-10 280 333 89
2016-11 420 360 99
2016-12 588 540 151

See for additional reporting functions, especially for starting subscriptions on arbitrary days (instead of calendar months).


Souvenirs uses hopefully sane defaults for all settings. Here’s what you can override if you want:

SOUVENIRS_RATELIMIT_SECONDS: how often to record an active user in the DB, default 3600

SOUVENIRS_CACHE_NAME: which cache to use for rate-limiting, default 'default'

SOUVENIRS_CACHE_PREFIX: how to prefix rate-limiting cache entries, default 'souvenirs.'

SOUVENIRS_USAGE_REPORTS_FUNCTION: all the reporting functions call a low-level function usage_for_periods. This can be overridden (probably wrapped) if you’d like to use the souvenirs reporting functions to generate richer data, for example incorporating some other data per time period.


To contribute to this project, fork to your own github user, make your changes on a branch, run the tests and open a pull request. If you have hub and tox installed, it’s like this:

hub clone appsembler/django-souvenirs
cd django-souvenirs
git checkout -b my-awesome-feature
# hack hack hack!
tox --skip-missing-interpreters
git commit -am "my awesome commit"
hub fork  # for example agriffis/django-souvenirs
git push --set-upstream agriffis  # insert your github user here
hub pull-request

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-souvenirs-1.0.2.tar.gz (16.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page