Merge pull request #4 from gratipay/tool-tweaks

constrain to a declared list of accounts

README.md

@@ -16,15 +16,15 @@ money—and then we have **escrow**—*other people's* money. Never the
 twain shall meet (more or less). Beyond the basic accounting principle that
 assets must equal liabilities plus equity, nearly as important for Gratipay is
 that escrow assets must always equal escrow liability: when people think we're
-holding their money, we better be holding their money!
+holding their money, we'd better be holding their money!
 
-Actually, though, our income from processing fees comes to us from our upstream
-processors commingled with escrow, *and* we want to keep our fee *income* as
-close to our fee *expenses* as possible (our *operating* income, of course,
-comes [through Gratipay](https://gratipay.com/Gratipay/) just like any other
-Gratipay Team).  To deal with this dual reality, we use a **fee buffer**.
-Ideally the balance in the fee buffer is zero, though of course it varies in
-practice.
+Actually, though, our operating income from processing fees comes to us from
+our upstream processors commingled with escrow, *and* we want to keep our fee
+*income* as close to our fee *expenses* as possible (our true operating income,
+of course, comes [through Gratipay](https://gratipay.com/Gratipay/) just like
+any other Gratipay Team). To deal with this dual reality, we use a **fee
+buffer**. Ideally the balance in the fee buffer is zero, though of course it
+fluctuates in practice.
 
 You'll see, then, that the assets on our balance sheet, as well as our income
 and expenses on our income statement, are broken down according to these three
@@ -48,21 +48,30 @@ First, you'll need [Ledger](http://ledger-cli.org/) (v3),
 [Python](https://www.python.org/) (v2.7), a [text
 editor](https://en.wikipedia.org/wiki/Text_editor), and a [command
 line](https://en.wikipedia.org/wiki/Command-line_interface). Then basically
-what you're gonna do is edit the dat file for the month you're working on, and
-then, from the root of your clone of this repo, run:
+what you're gonna do is edit the `dat` file for the month you're working on,
+and then, from the root of your clone of this repo, run (with
+[`bin`](https://github.com/gratipay/finances/blob/master/bin/) on your `PATH`):
 
-```
+```bash
 clear && test.py && balance-sheet.py && income-statement.py
 ```
 
 That'll check for errors (we also have CI set up [at
 Travis](https://travis-ci.org/gratipay/finances)) and then show you a balance
-sheet and income statement.
+sheet and income statement. If you need to add accounts or currencies you can
+do so in
+[`declarations.dat`](https://github.com/gratipay/finances/blob/master/declarations.dat).
+If you want to run arbitrary Ledger commands, we provide a wrapper that points
+`ledger` to our `dat` files for your convenience:
+
+```bash
+wledger.py register
+```
 
 
 ### Style
 
-Here are some style notes for the dat files:
+Here are some style notes for the `dat` files:
 
  1. Group transactions together conceptually.
 
@@ -79,8 +88,9 @@ Here are some style notes for the dat files:
 ### Access
 
 Many accounting tasks require access to Gratipay's bank and payment processor
-statements. If you're interested in helping out with such tasks, read [Inside
-Gratipay](http://inside.gratipay.com/) and then introduce yourself on [the
+statements. If you're interested in helping out with such tasks and would like
+access to our statements, read [Inside Gratipay](http://inside.gratipay.com/)
+and then introduce yourself on [the
 Radar](http://inside.gratipay.com/howto/sweep-the-radar).
 
 

bin/balance-sheet.py

@@ -24,13 +24,14 @@
 # Each year opens with a carryover balance, so we don't have to go further back than that.
 start = [year, None]
 end = [year, month]
-for datfile in reporting.list_datfiles(start, end):
-    cmd.append('-f {}'.format(datfile))
+
+cmd += reporting.list_datfiles(start, end)
 
 print()
 print("BALANCE SHEET".center(42))
 print("as of {} {}, {}".format( calendar.month_name[int(end[1])]
                               , calendar.monthrange(int(end[0]), int(end[1]))[1]
                               , end[0]
                                ).center(42))
+print()
 reporting.report(cmd)

bin/income-statement.py

@@ -23,8 +23,7 @@
 cmd += sys.argv[1:]
 
 start, end = reporting.parse(sys.argv[1:])
-for datfile in reporting.list_datfiles(start, end):
-    cmd.append('-f {}'.format(datfile))
+cmd += reporting.list_datfiles(start, end)
 
 print()
 print("INCOME STATEMENT".center(42))
@@ -41,4 +40,5 @@
                                             , calendar.month_name[int(end[1])]
                                             , end[0]
                                              ).center(42))
+print()
 reporting.report(cmd)

bin/reporting.py

@@ -4,12 +4,9 @@
 
 import argparse
 import subprocess
-import os
 import re
 import sys
-from os import path
-
-root = path.realpath(path.join(path.dirname(__file__), '..'))
+from os import chdir, getcwd, listdir, path
 
 
 def parse(argv):
@@ -37,17 +34,17 @@ def parse_one(arg):
             }[len(arg)]
 
 
-def list_datfiles(start=None, end=None):
-    """Given two (year, month) tuples, yield filepaths.
+def list_datfiles(start=None, end=None, root='.'):
+    """Given two (year, month) tuples, return a list of ['-f', filepath].
 
     Raises SystemExit if we don't have a datfile for a month in the
-    range specified.
+    range specified. May mutate start and/or end.
 
     """
     start = start or [None, None]
     end = end or start
 
-    years = [y for y in sorted(os.listdir(root)) if y.isdigit()]
+    years = [y for y in sorted(listdir(root)) if y.isdigit()]
     if start[0] is None: start[0] = years[-1]
     if end[0] is None: end[0] = start[0]
 
@@ -60,7 +57,7 @@ def list_datfiles(start=None, end=None):
         if year < start[0]: continue
         elif year > end[0]: break
 
-        months = [f[:2] for f in sorted(os.listdir(path.join(root, year))) if f.endswith('.dat')]
+        months = [f[:2] for f in sorted(listdir(path.join(root, year))) if f.endswith('.dat')]
 
         def check(month):
             if month[1] not in months:
@@ -82,11 +79,16 @@ def check(month):
     if end < start:
         sys.exit('Error: {}-{} comes before {}-{}.'.format(*(end + start)))
 
-    return filtered
+    return ['-f ' + f for f in filtered]
 
 
 def report(cmd):
-    print()
-    retcode = subprocess.call(' '.join(cmd), shell=True)
-    if retcode != 0:
-        raise SystemExit(retcode)
+    cwd = getcwd()
+    try:
+        chdir(path.realpath(path.join(path.dirname(__file__), '..')))
+        cmd += ['-f', 'declarations.dat']
+        retcode = subprocess.call(' '.join(cmd), shell=True)
+        if retcode != 0:
+            raise SystemExit(retcode)
+    finally:
+        chdir(cwd)

bin/wledger.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python2.7
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+import sys
+from os import path
+
+ourdir = path.realpath(path.dirname(__file__))
+sys.path.insert(0, ourdir)
+
+import reporting
+
+argv = sys.argv[1:]
+start, end = reporting.parse(argv)
+cmd = ['ledger'] + argv + reporting.list_datfiles(start, end)
+
+reporting.report(cmd)

declarations.dat

@@ -0,0 +1,29 @@
+commodity $
+account Assets:Escrow:Cash
+account Assets:Escrow:New Alliance
+account Assets:Escrow:Samurai
+account Assets:Escrow:Stripe
+account Assets:Fee Buffer:Cash
+account Assets:Fee Buffer:New Alliance
+account Assets:Fee Buffer:Samurai
+account Assets:Fee Buffer:Stripe
+account Assets:Operations:New Alliance
+account Assets:Operations:Samurai
+account Assets:Operations:Stripe
+account Equity:Owners:Chad Whitacre
+account Equity:Retained Earnings
+account Expenses:Escrow:Cash
+account Expenses:Fee Buffer:Cash
+account Expenses:Fee Buffer:Samurai
+account Expenses:Fee Buffer:Stripe
+account Expenses:Operations:Errors:Samurai
+account Expenses:Operations:Processing:Stripe
+account Income:Escrow:Samurai
+account Income:Escrow:Stripe
+account Income:Fee Buffer:Cash
+account Income:Fee Buffer:Samurai
+account Income:Fee Buffer:Stripe
+account Income:Operations:Errors:Samurai
+account Income:Operations:IHasAMoney.com
+account Income:Operations:Verification & Testing
+account Liabilities:Escrow