django-timeseries 1.0.1

Requirements

Django versions 1.8+ are supported for projects running on PostgreSQL.

Installation

pip install django-timeseries

Usage

from datetime import timedelta
from django.db import models
from timeseries.utils import TimeSeriesModel, TimeSeriesManager


class Ad(models.Model):

    objects = TimeSeriesManager()


class RawAdData(TimeSeriesModel):

    TIMESERIES_INTERVAL = timedelta(days=1)  # update daily N.B integers in seconds also work

    NOT_AVAILABLE = -1

    ad = models.ForeignKey(Ad, related_name='rawdata')

    views = models.BigIntegerField(default=NOT_AVAILABLE)
    clicks = models.BigIntegerField(default=NOT_AVAILABLE)


class MonthlyAdReport(TimeSeriesModel):

    TIMESERIES_INTERVAL = timedelta(days=28)

    ad = models.ForeignKey(Ad, related_name='monthlyreports')

    avg_view_growth = models.FloatField()
    avg_click_growth = models.FloatField()


def ad_data_collector(queryset):
    """
        should return an iterable that yields dictionaries of data
        needed to successfully create a RawAdData instance
    """
    return ...


def report_data_collector(queryset):
    """
        should return an iterable that yields dictionaries of data
        needed to successfully create a MonthlyAdReport instance
    """
    return ...


# in a shell
>>> Ad.objects.update_timeseries('rawdata', ad_data_collector)
# this return the results of a bulk_create call from the RawAdData manager
# for ads that hadn't been updated in the last day

>>> Ad.objects.update_timeseries('monthlyreports', report_data_collector)
# this return the results of a bulk_create call from the MonthlyAdReport
# manager for ads that hadn't had a report generated in the last 28 days

>>> ad = Ad.objects.prefetch_latest('rawdata', 'monthlyreports').first()
>>> print ad.latest_rawaddata, ad.latest_monthlyreports

TimeSeries QuerySet Methods

timeseries.utils.TimeSeriesQuerySet

Adds 4 main methods to the Django QuerySet API that can be used to update and maintain timeseries data. These methods include:

• prefetch_latest

• filter_outdated

• last_updated

• update_timeseries

ad = Ad.objects.last_updated('rawdata').first()
# assuming there's data related to ad
print ad.rawdata_last_updated
# this will print the timestamp of when the associated data was
# last updated

ad = Ad.objects.prefetch_latest('rawdata', 'monthlyreports').first()
print ad.latest_rawaddata, ad.latest_monthlyreports
# this will print the reprs of the latest associated data
# instances

Other Utilities

LatestQ

timeseries.utils

Inputs: related_name, **kwargs

Returns: django.db.models.Q instance

Constructs a django.db.models.Q instance that allows queries to be executed against the latest associated reverse relation.

N.B. this method is designed to be used in conjunction with timeseries.utils.TimeSeriesQuerySet.last_updated.

Usage:

Ad.objects.last_updated('rawdata').filter(
    LatestQ('rawdata', views__gt=1000)
)