Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

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

Installation

Get the latest stable release from PyPI

pip install django-souvenirs

Or the latest commit from GitHub

pip install -e git+git://github.com/appsembler/django-souvenirs.git#egg=souvenirs

Add to settings.py

INSTALLED_APPS += [
    'souvenirs',
]
MIDDLEWARE_CLASSES += [
    'souvenirs.middleware.SouvenirsMiddleware',
]

Migrate your database

./manage.py migrate souvenirs

Usage

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 = timezone.now()
>>> count_active_users(start=now - timedelta(days=1), end=now)
42

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(start=timezone.now() - timedelta(days=1))
42

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

>>> count_active_users()
1012

Reports

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),
                                    end=timezone.make_aware(end)):
...   print(d['labels']['calendar_year_month'],
            d['usage']['registered_users'],
            d['usage']['activated_users'],  # User.is_active
            d['usage']['active_users'])
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 reports.py for additional reporting functions, especially for starting subscriptions on arbitrary days (instead of calendar months).

Settings

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.

Contributing

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.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-souvenirs-1.0.2.tar.gz (16.3 kB) Copy SHA256 hash SHA256 Source None Apr 5, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page