Add docs for utils/history.py

docs/index.rst

@@ -8,25 +8,46 @@ Welcome! This is the documentation for programmers working on `gratipay.com`_
 .. _web API: https://github.com/gratipay/gratipay.com#api
 
 
+.. _db-schema:
+
 DB Schema
 ---------
 
-is_suspipicous on participant can be None, True or False. It represents unknown,
-blacklisted or whitelisted user.
+Users
+^^^^^
+
+``is_suspicious`` on a participant can be ``None`` (unknown), ``True``
+(blacklisted) or ``False`` (whitelisted)
 
     * whitelisted can transfer money out of gratipay
     * unknown can move money within gratipay
     * blacklisted cannot do anything
 
+Money
+^^^^^
+
+- ``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``).
 
-The exchanges table records movements of money into and out of Gratipay. The
-``amount`` column shows a positive amount for payins and a negative amount for
-payouts. The ``fee`` column is always positive. For both payins and payouts,
+- ``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 into and out of Gratipay. Every ``exchange`` is linked to a
+participant. The ``amount`` column shows a positive amount for money flowing
+into gratipay (payins), and a negative amount for money flowing out of Gratipay
+(payouts). The ``fee`` column is always positive. For both payins and payouts,
 the ``amount`` does not include the ``fee`` (e.g., a $10 payin would result in
 an ``amount`` of ``9.41`` and a ``fee`` of ``0.59``, and a $100 payout with a
 2% fee would result in an ``amount`` of ``-98.04`` and a fee of ``1.96``).
 
-
 Contents
 --------
 

gratipay/utils/history.py

@@ -1,3 +1,9 @@
+"""Helpers to fetch logs of payments made to/from a participant.
+
+Data is fetched from 3 tables: `transfers`, `payments` and `exchanges`. For
+details on what these tables represent, see :ref:`db-schema`.
+"""
+
 from datetime import datetime
 from decimal import Decimal
 
@@ -23,6 +29,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 +172,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