Django prepaid
==============

Django-prepaid is a low-level Django application to support prepaid
service functionality. User can purchase a pack of `units' (it is up
to project to define meaning of units, but think prepaid phone service
and calling minutes to see the desired meaning). Every pack has an
expiry date, defaulting to `settings.PREPAID_DEFAULT_EXPIRY_PERIOD'
days, if set. Units are available until the expiry date, and user can
have multiple unit packs with different number of units and expiry
dates at the same time. Units can be consumed; they are substracted
from valid (not expired) packs' quantities, starting from pack that
has nearest expiry date.

This application is designed to be purely back-end, i.e. defines no
views or URLs, uses no templates.

Table of Contents
=================
1 Installation
2 Settings
3 Model
    3.1 Managers
    3.2 Methods
    3.3 Class methods
4 License


1 Installation
~~~~~~~~~~~~~~
  Copy or symlink `prepaid/' subdirectory to Python path (`setup.py'
  script for automated installation will be supplied later on). Module
  contents are available in the `prepaid' module.

  In order to use application, add `prepaid' to INSTALLED_APPS in
  Django project `settings.py' file,

2 Settings
~~~~~~~~~~
  `PREPAID_DEFAULT_EXPIRY_PERIOD' defines default value for
  `UnitPack.expires' field; is set, default for `UnitPack.expires' is
  today + `PREPAID_DEFAULT_EXPIRY_PERIOD' days.  If not set, `expires'
  field has no default.

3 Model
~~~~~~~
  The `prepaid.models.UnitPack' class is only model defined by the
  application.  It has following fields:
  - `user' is ForeignKey to `auth.User' model. It specifies user who
    owns the pack's units;
  - `quantity' is IntegerField containing current amount of units
    contained in pack.  It is decreased when units are consumed;
  - `expires' is `DateField' containing pack's expiry date. If
    `PREPAID_DEFAULT_EXPIRY_PERIOD' setting is set, default value is
    today + `PREPAID_DEFAULT_EXPIRY_PERIOD' days; otherwise, there is
    no default value and expiry date has to be explicitly specified.
  - `timestamp' is a DateTimeField containing timestamp of pack's
    creation.  It should be used for bookkeeping purposes only.
  - `initial_quantity' is the initial value of `quantity' field. It
    should be used for bookkeeping purposes only.

3.1 Managers
============
   Default manager, `objects', adds filter to make only valid (see
   `is_valid()' method below) instances visible.  Additional manager,
   `all_objects', is provided, that provides access to all instances,
   including invalid ones.

3.2 Methods
===========
   `is_valid()' method returns True if pack is valid, i.e. `quantity'
   is greater than 0, and `expires' date is in the future.

3.3 Class methods
=================
   Three class methods are provided for convenience:
   - `UnitPack.get_user_packs(user)' returns QuerySet of all valid
     `UserPack' instances belonging to `user';
   - `UnitPack.get_user_credits(user)' returns sum of `quantity'
     instance of `UnitPack.get_user_packs(user)', i.e. sum of all
     units available to `user';
   - `UnitPack.consume(user, amount=1)' consumes `amount' units from
     `user''s credit.  If `amount' is greater than
     `UnitPack.get_user_credits(user)', `ValueError' is raised.
     Otherwise, `amount' is subsctracted from `quantity' fields of
     user's valid UnitPacks, starting from pack with nearest expiry
     date.

4 License
~~~~~~~~~
  This project is licensed on terms of GPL (GPL-LICENSE.txt) licenses