{"@attributes":{"version":"2.0"},"channel":{"title":"\u2124\u2192\u2124","link":"https:\/\/ztoz.blog\/","description":"Recent content on \u2124\u2192\u2124","generator":"Hugo -- gohugo.io","language":"en-us","lastBuildDate":"Wed, 15 Apr 2026 11:55:22 -0600","item":[{"title":"Plain Text Accounting & Financial Reporting","link":"https:\/\/ztoz.blog\/posts\/plaintext-accounting-reporting\/","pubDate":"Wed, 15 Apr 2026 11:55:22 -0600","guid":"https:\/\/ztoz.blog\/posts\/plaintext-accounting-reporting\/","description":"

Over the past year, I’ve been acting as the treasurer for a small publishing company. I converted our books from a collection of spreadsheets to a plain text accounting ledger and wrote programs to automate balance, income, and sales reporting using a tool called Beancount. These recipes may be useful to others running businesses, particularly if they have some programming talent.<\/p>\n

Plain Text Accounting<\/h2>\n

Plain Text Accounting<\/a> is an approach to accounting that has helped us minimize costs, maximize transparency, and automate reporting. Practitioners record transactions within “plain text” files that can be easily shared and stored in version control systems (such as git<\/code>). Since the format of the transactions is well-defined, tools can process the files to provide auditing, translation, and reporting. For example, a program can translate a credit card statement into a plain text format to facilitate importing.<\/p>\n

For our tooling, I chose Beancount v3<\/a>, partially due to its Python API, but competitor programs ledger<\/a> or hledger<\/a> may work better for you. Since you control the data, there is very little “lock-in” between any of the tools although they define the ledger format differently.<\/p>\n

Situational Context<\/h2>\n

Our business sells products through various online storefronts. We are a purely internet-based business. Individual products are developed by ad-hoc product teams who earn royalties based on their individual contributions and team agreements, so the royalty structures are unique per product.<\/p>\n

Since we are bootstrapping the business and building revenue takes time, we try to minimize overhead cash expenditures. When we reviewed commercial accounting\/bookkeeping tools, we found that they were either priced outside our budget or did not support tracking cost of goods sold and royalties sufficient to our needs. Spreadsheets were sufficient early on, but they were error-prone and, as the number of products grew, were becoming increasingly complex and fragile.<\/p>\n

Double Entry Accounting and the Ledger<\/h2>\n

Double entry accounting is a practice where transactions are recorded (at least twice): one or more source accounts and one or more destination accounts. Since the sum of the sources and destinations must equal zero, the practice has a built-in way to verify its correctness.<\/p>\n

All transactions can be recorded in a single ledger. For us, we have a data\/ledger.txt<\/code> file within our financial git repository. Access to the repository is controlled by our software forge and all changes automatically have an audit trail.<\/p>\n

The ledger has five accounts<\/a> at the top level: Assets, Liabilities, Income, Expenses, and Equity. Each ledger will define an account hierarchy under these five accounts. Using the beancount syntax, our (anonymized) accounts are:<\/p>\n

2025-01-01 open Assets:BankName:Checking USD\n2025-01-01 open Assets:StoreFront USD\n2025-01-01 open Liabilities:Royalties:Member1 USD\n2025-01-01 open Liabilities:Royalties:Member2 USD\n2025-01-01 open Income:BankName:Interest USD\n2025-01-01 open Expenses:StoreFront:Overhead USD\n2025-01-01 open Expenses:Govt:TaxFees USD\n2025-01-01 open Expenses:Operations USD\n2025-01-01 open Expenses:UnpaidRoyalties USD  ; for balancing out royalty liabilities\n2025-01-01 open Equity:Member1 USD\n2025-01-01 open Equity:Member2 USD\n\n; Do not allow fake accounts to be used after initialization\n2025-01-01 open Equity:Opening-Balances\n2025-01-02 close Equity:Opening-Balances\n\n; Project specific accounts\n\n2025-01-01 open Income:StoreFront:Prod01 USD\n2025-01-01 open Income:StoreFront:Prod02 USD\n2025-01-01 open Expenses:Prod02 USD\n<\/code><\/pre>
In Beancount, all entries in the ledger are marked with a date. Accounts must be opened on a certain date and can be closed. If an entry is marked against a closed account, it will be reported as an error. We use the Equity:Opening-Balances<\/code> account to handle initialization of values (since the business was already on-going by the time we started the ledger) and close it the day after to prevent using it accidentally.<\/p>\n
We have two assets, a checking account at a bank and the account at our storefront since transfers from the storefront are not automatic. Unpaid royalties are liabilities and we group each member under the general Royalties category. Income comes from product sales, which we group under the store, and interest from the bank. There are a variety of sources of expenses, some general, some product specific, and we record equity per member.<\/p>\n
As you will see later, we later added an attribute to accounts to differentiate between operational (core business related) and non-operational income and expenses. Instead of adding the attribute, we could have used a hierarchical element (e.g. Income:Op:StoreFront:Prod01<\/code> and Income:NonOp:BankName:Interest<\/code>) which would have aligned better with Beancount’s query functionality.<\/p>\n
A sales transaction demonstrates the double-entry method. A customer purchases Prod02 and pays $3.<\/p>\n
2025-12-23 txn "StoreFront" "Prod02 Sale"\n        Income:StoreFront:Prod02        -3.00 USD       ; Total (Gross) Sale\n        Expenses:StoreFront:Overhead     0.90 USD       ; Storefront cut\n        Assets:StoreFront                2.10 USD       ; Earnings\n        Liabilities:Royalties:Member1   -0.55 USD       ; Royalty\n        Liabilities:Royalties:Member2   -0.05 USD       ; Royalty\n        Expenses:UnpaidRoyalties         0.60 USD       ; Royalty Float\n<\/code><\/pre>
The sum of these six changes to accounts is zero. The signs used on the values may initially seem counter-intuitive but they do make sense. The gross sales value, the Income for the sale, is recorded as a negative number. The storefront takes a portion of the sale, in this case $0.90, so that is recorded as an Expense (or cost of goods sold). (In this example, sales tax and payment processor expenses are part of the overhead.) That leaves $2.10 to be stored in our “account” with the storefront. Due to royalties, we cannot claim full ownership of that $2.10 so we need to account for our liabilities. We record two Royalty liabilities and balance their sum with an Expenses line for tracking overall UnpaidRoyalties.<\/p>\n
When we pay out royalties, we debit the asset where we are drawing money from and credit our liabilities:<\/p>\n
2025-01-12 txn "Company" "Member1 Royalty Payment 2024Q4"\n    Assets:BankName:Checking        -17.00 USD         ; Payment\n    Liabilities:Royalties:Member1    17.00 USD         ; Reduction of liability\n<\/code><\/pre>
Notably, we do not change the Expenses:UnpaidRoyalties<\/code> value. Assets and Liabilities have a value at given time (similar to a Gauge in telemetry), while Income and Expenses are deltas<\/em> between two time values (similar to a Counter in telemetry). It makes sense to discuss a bank balance at the start or end of a quarter, but a balance is not defined over a three month period. In contrast, we can discuss sales over a quarter, but not sales at a specific point of time.<\/p>\n
Beancount includes a tool bean-check<\/code> which can verify the balancing of accounts. We call bean-check<\/code> as part of our git merge pipeline. In our ledger, we include balance<\/code> checks to verify our accounts match those of the banks and storefronts, e.g.:<\/p>\n
2025-08-01 balance Assets:BankName:Checking 1670.06 USD\n<\/code><\/pre>
For populating the ledger, we have Python scripts that translate exported monthly CSV reports into the beancount format. It is also easy to write entries by hand, which is necessary because human judgment is often needed to properly categorize expenses.<\/p>\n
Reporting using Beancount<\/h2>\n
The members of the company board expect monthly balance statements, income statements by the month, quarter, and year, and reports of sales by product. So far, I haven’t been asked to produce any custom reports, but I expect that will come.<\/p>\n
To generate the reports, I use Python, the jinja2 templating library, and beancount’s beanquery library. On a merge to the main branch, we update a website (via Gitlab Pages) with the latest set of reports. We use Gitlab’s authentication system to control access to the website.<\/p>\n
beanquery<\/code> provides a SQL-like interface to the ledger that implements the Python database interface. Creating a connection is straight-forward:<\/p>\n
\tconn: beanquery.<\/span>Connection =<\/span> beanquery.<\/span>connect('beancount:data\/ledger.txt'<\/span>)\n<\/code><\/pre><\/div>
I pass around a Context instance to store the various run-time objects and configuration:<\/p>\n
\t@dataclass<\/span>\n\tclass<\/span> RenderContext<\/span>:\n\t    conn: beanquery.<\/span>Connection\n\t    env: jinja2.<\/span>Environment\n\t    dst: pathlib.<\/span>Path\n\t    earliest_ledger: datetime.<\/span>date  # inclusive transaction date<\/span>\n\t    latest_ledger: datetime.<\/span>date  # inclusive transaction date<\/span>\n<\/code><\/pre><\/div>
The earliest and latest ledger date values are retrieved via beanquery:<\/p>\n
    earliest =<\/span> fetch_one_row(conn, 'SELECT date ORDER BY date ASC LIMIT 1'<\/span>)[0<\/span>]\n    latest =<\/span> fetch_one_row(conn, 'SELECT date ORDER BY date DESC LIMIT 1'<\/span>)[0<\/span>]\n<\/code><\/pre><\/div>
Beanquery returns rich Python objects from queries, which can be unexpected, but also means you will write fewer type conversion functions.<\/p>\n
Balance Sheets<\/h3>\n
A balance sheet reports assets, liabilities, and equity on the close of a financial period. In our case, we report monthly. The function render_balance_sheets<\/code> generates a monthly report for every month in our ledger with recorded transactions. Beanquery does not support parameterized queries, so we use string interpolation via .format<\/code> instead.<\/p>\n
\tdef<\/span> render_balance_sheets<\/span>(ctx: RenderContext):\n\t    template =<\/span> ctx.<\/span>env.<\/span>get_template('balance.html'<\/span>)\n\t\n\t    for<\/span> start_inc, end_exc in<\/span> month_pair_iter(ctx.<\/span>earliest_ledger, ctx.<\/span>latest_ledger):\n\t        query =<\/span> "SELECT account, SUM(position) FROM CLOSE ON <\/span>{0}<\/span> CLEAR "<\/span> \\\n\t        \t"WHERE account~'Assets|Liabilities|Equity' ORDER BY account"<\/span>.<\/span>format(end_exc.<\/span>isoformat())\n\t        out =<\/span> _render_positions(ctx, template, query, (start_inc, end_exc))\n\t        ctx.<\/span>dst.<\/span>joinpath(f<\/span>'balance-<\/span>{<\/span>start_inc.<\/span>year}<\/span>-<\/span>{<\/span>str(start_inc.<\/span>month).<\/span>rjust(2<\/span>, "0"<\/span>)}<\/span>.html'<\/span>) \\\n\t        \t.<\/span>write_text(out, encoding=<\/span>'utf-8'<\/span>)\n<\/code><\/pre><\/div>
The function _render_positions<\/code> renders the Jinja2 template with the results from the query. We also translate the raw query results into an AccountPosition<\/code> which breaks out the top-level account type as the field account_type<\/code> and flatten’s beancount’s complex Inventory<\/code> type into a number. (Although we are explicit with our currencies in the ledger, we only handle USD.)<\/p>\n
AccountPosition<\/code> is a dataclass defined as:<\/p>\n
\t@dataclass<\/span>\n\tclass<\/span> AccountPosition<\/span>:\n\t    account_type: str  # Assets, Liabilities, Equity, Income, Expense<\/span>\n\t    account: str  # e.g. StoreFront, Royalties:Member1<\/span>\n\t    usd: Decimal\n\t\n\t\t# @property is_operational described under Income Sheets<\/span>\n\t\n\t    @staticmethod<\/span>\n\t    def<\/span> from_tuple<\/span>(record: Tuple[str, Inventory]) -><\/span> 'AccountPosition'<\/span>:\n\t        """\n<\/span>\t        From a bean-query balance record, return an AccountPosition\n<\/span>\t\n<\/span>\t        Example:\n<\/span>\t        > AccountPosition.from_tuple(("'Assets:BankName:Checking'", "(1055.00 USD)"))\n<\/span>\t        AccountPosition('Assets', 'BankNameChecking', Decimal('1055.00'))\n<\/span>\t\n<\/span>\t        :param record:\n<\/span>\t        :return:\n<\/span>\t        """<\/span>\n\t        account_type, account =<\/span> record[0<\/span>].<\/span>split(':'<\/span>, maxsplit=<\/span>1<\/span>)\n\t        inventory: Inventory =<\/span> record[1<\/span>]\n\t        amt: Amount =<\/span> inventory.<\/span>get_currency_units('USD'<\/span>)\n\t        return<\/span> AccountPosition(account_type, account, amt.<\/span>number)\n<\/code><\/pre><\/div>
We excerpt the liabilities table from balance.html<\/code> below. In the report, this would preceded by the assets table and followed by the equity table. For ease of reading, we exclude from the table accounts with a zero balance and represent liabilities as positive values. In the table footer, Jinja2 pipes are a good way to compute filtered sums. Since numbers are stored as Decimals, we do not need to worry about floating point errors.<\/p>\n
    <table<\/span> id<\/span>=<\/span>"liabilities"<\/span> class<\/span>=<\/span>"table-4in"<\/span>>\n        <thead<\/span>>\n\t    <tr<\/span>>\n\t        <th<\/span> class<\/span>=<\/span>"align-left"<\/span>>Liability<\/th<\/span>>\n\t        <th<\/span> class<\/span>=<\/span>"align-right"<\/span>>Value ($)<\/th<\/span>>\n\t    <\/tr<\/span>>\n        <\/thead<\/span>>\n    \t<tbody<\/span>>\n        {% for balance in balances if balance.account_type == 'Liabilities' \n        \t\t\t\t\t\t\tand not balance.usd.is_zero() %}\n        <tr<\/span>>\n            <td<\/span>>{{ balance.account }}<\/td<\/span>>\n            <td<\/span> class<\/span>=<\/span>"align-right currency"<\/span>>{{ balance.usd * -1|round(2) }}<\/td<\/span>>\n        <\/tr<\/span>>\n        {% endfor %}\n        <\/tbody<\/span>>\n        <tfoot<\/span>>\n        <tr<\/span>>\n            <td<\/span>><em<\/span>>Total<\/em<\/span>><\/dt<\/span>>\n            <dt<\/span> class<\/span>=<\/span>"align-right currency"<\/span>>{{ balances\n \t\t           |selectattr('account_type', 'eq', 'Liabilities')\n \t\t           |sum(attribute='usd') * -1|round(2) }}<\/dt<\/span>>\n        <\/tr<\/span>>\n        <\/tfoot<\/span>>\n    <\/table<\/span>>\n<\/code><\/pre><\/div>
Income Sheets<\/h3>\n
An income sheet reports income and expenses within a period of time. The function render_income_sheets<\/code> creates files for each month and quarter in our ledger’s horizon. Since the data represents flows rather than instances in time, the queries include both an OPEN ON<\/code> and a CLOSE ON<\/code>.<\/p>\n
def<\/span> render_income_sheets<\/span>(ctx: RenderContext):\n    template =<\/span> ctx.<\/span>env.<\/span>get_template('income.html'<\/span>)\n\n    for<\/span> start_inc, end_exc in<\/span> month_pair_iter(ctx.<\/span>earliest_ledger, ctx.<\/span>latest_ledger):\n        query =<\/span> "SELECT account, SUM(position) FROM OPEN ON <\/span>{0}<\/span> CLOSE ON <\/span>{1}<\/span> "<\/span> \\\n        \t"WHERE account~'Income|Expenses' GROUP BY 1 ORDER BY 1"<\/span> \\\n        \t.<\/span>format(start_inc.<\/span>isoformat(), end_exc.<\/span>isoformat())\n        out =<\/span> _render_positions(ctx, template, query, (start_inc, end_exc))\n        ctx.<\/span>dst.<\/span>joinpath(f<\/span>'income-<\/span>{<\/span>start_inc.<\/span>year}<\/span>-<\/span>{<\/span>str(start_inc.<\/span>month).<\/span>rjust(2<\/span>, "0"<\/span>)}<\/span>.html'<\/span>) \\\n        \t.<\/span>write_text(out, encoding=<\/span>'utf-8'<\/span>)\n\n    for<\/span> quarter_inc, quarter_exc in<\/span> quarter_iter(ctx.<\/span>earliest_ledger, ctx.<\/span>latest_ledger):\n        query =<\/span> "SELECT account, SUM(position) FROM OPEN ON <\/span>{0}<\/span> CLOSE ON <\/span>{1}<\/span>"<\/span> \\ \n        \t"WHERE account~'Income|Expenses' GROUP BY 1 ORDER BY 1"<\/span> \\\n        \t.<\/span>format(quarter_inc.<\/span>isoformat(), quarter_exc.<\/span>isoformat())\n        out =<\/span> _render_positions(ctx, template, query, (quarter_inc, quarter_exc))\n        ctx.<\/span>dst.<\/span>joinpath(f<\/span>'income-<\/span>{<\/span>quarter_inc.<\/span>year}<\/span>-Q<\/span>{<\/span>str((quarter_inc.<\/span>month -<\/span> 1<\/span>) \/\/<\/span> 3<\/span> +<\/span> 1<\/span>)}<\/span>.html'<\/span>) \\\n        \t.<\/span>write_text(out, encoding=<\/span>'utf-8'<\/span>)\n<\/code><\/pre><\/div>
The operational income portion of the income sheet is generated via:<\/p>\n
    {% for balance in balances if balance.account_type == 'Income' and balance.is_operational %}\n        <tr<\/span>>\n            <dt<\/span> class<\/span>=<\/span>"align-left indent-1"<\/span>>{{ balance.account }}<\/dt<\/span>>\n            <dt<\/span> class<\/span>=<\/span>"align-right currency"<\/span>>{{ balance.usd|abs|round(2) }}<\/dt<\/span>>\n        <\/tr<\/span>>\n    {% endfor %}\n    <tr<\/span>>\n        <dt<\/span> class<\/span>=<\/span>"align-left indent-1"<\/span>><em<\/span>>Total<\/em<\/span>><\/dt<\/span>>\n        <dt<\/span> class<\/span>=<\/span>"align-right currency"<\/span>>{{ balances\n\t\t\t|selectattr('account_type', 'eq', 'Income')\n\t          |selectattr('is_operational')\n\t          |sum('usd')|round(2)|abs }}<\/dt<\/span>>\n    <\/tr<\/span>>\n<\/code><\/pre><\/div>
The is_operational<\/code> method is coded as:<\/p>\n
    @property<\/span>\n    def<\/span> is_operational<\/span>(self):\n        """\n<\/span>        :return: true if Income\/Expense is part of normal business operations\n<\/span>        """<\/span>\n        if<\/span> self.<\/span>account_type ==<\/span> 'Income'<\/span>:\n            return<\/span> self.<\/span>account !=<\/span> 'BankName:Checking'<\/span>\n        elif<\/span> self.<\/span>account_type ==<\/span> 'Expenses'<\/span>:\n            return<\/span> self.<\/span>account !=<\/span> 'Govt:TaxFees'<\/span>\n        else<\/span>:\n            return<\/span> False<\/span>\n<\/code><\/pre><\/div>
Jinja2 templates are not allowed to call methods on objects, so we use @property<\/code> so the template can retrieve the boolean value.<\/p>\n
From a maintability perspective, this implementation is fragile if we define new accounts. Fortunately, we rarely define new accounts. Representing the operational nature of the account in the hierarchy would solve the problem.)<\/p>\n
Sales by Product<\/h3>\n
For sales, we provide a table with rows for each product, columns for months within a year, and totals for each row and month.<\/p>\n
The table is generated by the template:<\/p>\n
\t<table<\/span> id<\/span>=<\/span>"gross-sales"<\/span> class<\/span>=<\/span>"table-dense"<\/span>>\n\t    <thead<\/span>>\n\t        <tr<\/span>>\n\t            <th<\/span> class<\/span>=<\/span>"align-left"<\/span>>Product<\/th<\/span>>\n\t            <th<\/span>>01<\/th<\/span>>\n\t            <th<\/span>>02<\/th<\/span>>\n\t            <th<\/span>>03<\/th<\/span>>\n\t            <th<\/span>>04<\/th<\/span>>\n\t            <th<\/span>>05<\/th<\/span>>\n\t            <th<\/span>>06<\/th<\/span>>\n\t            <th<\/span>>07<\/th<\/span>>\n\t            <th<\/span>>08<\/th<\/span>>\n\t            <th<\/span>>09<\/th<\/span>>\n\t            <th<\/span>>10<\/th<\/span>>\n\t            <th<\/span>>11<\/th<\/span>>\n\t            <th<\/span>>12<\/th<\/span>>\n\t            <th<\/span>>Total<\/th<\/span>>\n\t        <\/tr<\/span>>\n\t    <\/thead<\/span>>\n\t    <tbody<\/span>>\n\t    {% for sale in sales %}\n\t        <tr<\/span>>\n\t            <dt<\/span> class<\/span>=<\/span>"align-left"<\/span>>{{ sale.positions[0].account }}<\/dt<\/span>>\n\t            {% for position in sale.positions %}\n\t                {% if position.usd.is_zero() %}\n\t                <dt<\/span> class<\/span>=<\/span>"align-right"<\/span>><\/dt<\/span>>\n\t                {% else %}\n\t                <dt<\/span> class<\/span>=<\/span>"align-right"<\/span>>{{ position.usd|abs|round(0) }}<\/dt<\/span>>\n\t                {% endif %}\n\t            {% end for %}\n\t            <dt<\/span> class<\/span>=<\/span>"align-right"<\/span>>{{ sale.positions|sum('usd')|round(0)|abs }}<\/dt<\/span>>\n\t        <\/tr<\/span>>\n\t    {% end for %}\n\t    <\/tbody<\/span>>\n\t    <tfoot<\/span>>\n\t        <tr<\/span>>\n\t            <dt<\/span>><em<\/span>>Total<\/em<\/span>><\/dt<\/span>>\n\t            {% for month in range(1, 13) %}\n\t            <dt<\/span> class<\/span>=<\/span>"align-right"<\/span>>{{ (monthly_sums[month]) }}<\/dt<\/span>>\n\t            {% end for %}\n\t            <dt<\/span> class<\/span>=<\/span>"align-right"<\/span>>{{ monthly_sums.values()|sum }}<\/dt<\/span>>\n\t        <\/tr<\/span>>\n\t    <\/tfoot<\/span>>\n\t<\/table<\/span>>\n<\/code><\/pre><\/div>
We leverage beancount’s PIVOT<\/code> capability:<\/p>\n
def<\/span> render_gross_sales<\/span>(ctx: RenderContext):\n    """\n<\/span>    Gross sales by year and month for operational income accounts\n<\/span>\n<\/span>    :param ctx:\n<\/span>    :return:\n<\/span>    """<\/span>\n    template =<\/span> ctx.<\/span>env.<\/span>get_template('sales.html'<\/span>)\n\n    for<\/span> year in<\/span> range(ctx.<\/span>earliest_ledger.<\/span>year, ctx.<\/span>latest_ledger.<\/span>year +<\/span> 1<\/span>):\n        query =<\/span> "SELECT account, month(date) as d, SUM(position)"<\/span> \\ \n        \t"WHERE account~'Income' and year(date)=<\/span>{0}<\/span> GROUP BY 1, 2 ORDER BY 1 PIVOT BY 1, 2"<\/span> \\\n        \t.<\/span>format(year)\n        now =<\/span> datetime.<\/span>date.<\/span>today().<\/span>isoformat()\n\n        incomes =<\/span> fetch_all_rows(ctx.<\/span>conn, query)\n        sales =<\/span> [MonthAccountPositionPivot.<\/span>from_tuple(i) for<\/span> i in<\/span> incomes]\n        sales =<\/span> list(filter(lambda<\/span> s: s.<\/span>positions[0<\/span>].<\/span>is_operational, sales))\n\n        # jinja2 is ignoring a round(0) filter, so we pre-round the monthly sums before the template<\/span>\n        monthly_sums =<\/span> defaultdict(Decimal)\n        for<\/span> sale in<\/span> sales:\n            for<\/span> i, position in<\/span> enumerate(sale.<\/span>positions):\n               monthly_sums[i+<\/span>1<\/span>] =<\/span> monthly_sums[i+<\/span>1<\/span>] +<\/span> position.<\/span>usd\n        for<\/span> month in<\/span> range(1<\/span>, 13<\/span>):\n            monthly_sums[month] =<\/span> round(abs(monthly_sums[month]), 0<\/span>)\n\n        out =<\/span> template.<\/span>render(now=<\/span>now, year=<\/span>year, sales=<\/span>sales, monthly_sums=<\/span>monthly_sums)\n        ctx.<\/span>dst.<\/span>joinpath(f<\/span>'sales-<\/span>{<\/span>year}<\/span>.html'<\/span>).<\/span>write_text(out, encoding=<\/span>'utf-8'<\/span>)\n<\/code><\/pre><\/div>
MonthAccountPositionPivot<\/code> generates a rectangular grid of values from the query results like so:<\/p>\n
\t@dataclass<\/span>\n\tclass<\/span> MonthAccountPositionPivot<\/span>:\n\t    positions: Sequence[AccountPosition]\n\t\n\t    @staticmethod<\/span>\n\t    def<\/span> from_tuple<\/span>(record: Tuple[str, ...<\/span>]) -><\/span> 'MonthAccountPositionPivot'<\/span>:\n\t        positions =<\/span> []\n\t        acct =<\/span> record[0<\/span>]\n\t        for<\/span> m in<\/span> range(1<\/span>, len(record)):\n\t            inv =<\/span> record[m]\n\t            if<\/span> inv is<\/span> None<\/span>:\n\t                inv =<\/span> ZERO_INVENTORY\n\t            positions.<\/span>append(AccountPosition.<\/span>from_tuple((acct, inv)))\n\t        for<\/span> zero_months in<\/span> range(13<\/span> -<\/span> len(record)):\n\t            positions.<\/span>append(AccountPosition.<\/span>from_tuple((acct, ZERO_INVENTORY)))\n\t\n\t        assert<\/span> len(positions) ==<\/span> 12<\/span>, f<\/span>"len(positions) must be 12, is <\/span>{<\/span>len(positions)}<\/span>"<\/span>\n\t        return<\/span> MonthAccountPositionPivot(positions)\n<\/code><\/pre><\/div>
Conclusion<\/h2>\n
I’ve been pleased with adopting plain text accounting and beancount. I have more confidence that the data is correct since the ledger is verified against a history of monthly balances. Maintaining royalties is also easier because the logic is stored in one place and it is transparent how they are calculated for each transaction.<\/p>"},{"title":"README: A Bookish History of Computing (Review)","link":"https:\/\/ztoz.blog\/posts\/readme-bookish-history-review\/","pubDate":"Tue, 14 Apr 2026 10:10:27 -0600","guid":"https:\/\/ztoz.blog\/posts\/readme-bookish-history-review\/","description":"
While the study of textbooks has proven fruitful in the study of the history of mathematics, there has been little attention to computing books and their role on the development of computer science, the computer industry, and public understanding. Working to close this gap, W. Patrick McCray has written README<\/em>, a “book about books about computing.” (pg 3) The scope is “a history of computing writ large as seen through the histories of a limited but well-chosen selection of books […] and their authors, editors, publishers, and readers.” (ibid).  McCray selects non-fiction works that influenced the understanding and direction of computing in the latter half of the 20th century.<\/p>\n
\n\t\n\t
Cover of README<\/em><\/figcaption>\n<\/figure>\n
README: A Bookish History of Computing from Electronic Brains to Everything Machines<\/em>. W. Patrick McCray. The MIT Press. (2025) Publisher Link<\/a><\/p>\n
Organized largely chronologically, the book begins with Edmund Berkeley’s Giant Brains<\/em> (1949), an early description of computers for the masses, and ends with Esther Dyson’s Release 2.0<\/em> (1997), a volume about the Internet and implications of a digital age. McCray’s analysis has a broad scope and each chapter covers the social context that the authors and publishers worked under and how that influenced their works. Many chapters cover multiple works, particularly the final chapter which expounds on popular public works such as the For Dummies<\/em> series and the rise of computing magazines. Two chapters focus on more technical works: TeXbook<\/em> and Introduction to VLSI Systems<\/em> and their professional impact. Most of the works he describes are more policy or philosophically-oriented, such as Weizenbaum’s (ELIZA) God & Golem, Inc.<\/em> and Theodor Nelson’s (hypertext) Computer Lib\/Dream Machines<\/em>. Those interested in computers and society-type questions or the debates on the nature of automation and articial intelligence will find the content rich and a source of further reading.<\/p>\n
Positively, README<\/em> places the books into a greater narrative and connects computing into greater social trends. McCray is able to supply much insight into the individual authors and their backgrounds and how that influenced their work. He also avoids retreading familiar business history.<\/p>\n
Of his chosen list of books, we are most familiar with the TeXbook<\/em> and Knuth’s writings on layout and typography. We find it strange that the account does not mention Adobe at all (for either Postscript or Type 1 fonts) and barely mentions Xerox. In our opinion, the impact of TeX and METAFONT should be placed in the broader context of the desktop publishing revolution and its competitors. In general, evaluating the impact of books is difficult, particularly in fields such as engineering which often ignore history. As an example, consider the continuing debate over the impact of Liber Abaci<\/em>. McCray makes the best case for the impact of Introduction to VLSI Systems<\/em>, but his is not the last word on which books should be included in the list.<\/p>\n
We recommend this book to those interested in computer ethics, the history of practice in computing, and the on-going debate on human labor, automation, the concept of deceit in artificial intelligence, and our relation to machines. The book would be an excellent companion volume to a computers and society course. The book is accessible to non-specialists.<\/p>\n
\n
The Computer History Museum interviewed McCray about the book during a live event in January 2026:<\/p>\n