Add docs for utils/history.py

gratipay/utils/history.py

@@ -1,3 +1,19 @@
+"""Helpers to fetch logs of payments made to/from a participant.
+
+There are three different tables that we pull data from:
+
+- `transfers`: Used under Gratipay 1.0, when users were allowed to tip
+               each other (without having to setup a team). `transfers` models
+               money moving *within* Gratipay, from one participant (`tipper`)
+               to another (`tippee`).
+- `payments`:  The replacement for `transfers`, used in Gratipay 2.0. `payments`
+               are between a Team and a Participant, in either direction (`to-team`,
+               or `to-participant`)
+- `exchanges`: Records money moving in and out of Gratipay. Every `exchange` is linked
+               to a participant. The `amount` is +ve for money flowing *into* gratipay,
+               and -ve for money flowing *out* of Gratipay
+"""
+
 from datetime import datetime
 from decimal import Decimal
 
@@ -23,6 +39,8 @@ def get_end_of_year_balance(db, participant, year, current_year):
 
     username = participant.username
     start_balance = get_end_of_year_balance(db, participant, year-1, current_year)
+
+    # FIXME - delta from the `payments` table should be included too!
     delta = db.one("""
         SELECT (
                   SELECT COALESCE(sum(amount), 0) AS a
@@ -164,6 +182,8 @@ def export_history(participant, year, mode, key, back_as='namedtuple', require_k
     db = participant.db
     params = dict(username=participant.username, year=year)
     out = {}
+
+    # FIXME - values from the `payments` table should be included too!
     if mode == 'aggregate':
         out['given'] = lambda: db.all("""
             SELECT tippee, sum(amount) AS amount
@@ -212,6 +232,8 @@ def export_history(participant, year, mode, key, back_as='namedtuple', require_k
           ORDER BY timestamp ASC
         """, params, back_as=back_as)
 
+    import pdb; pdb.set_trace();
+
     if key:
         try:
             return out[key]()