beancount-lalitm

Importers and plugins for Beancount plain-text accounting.

Disclaimer: I am not a tax professional or financial advisor. This code is provided as-is for personal use. The uk_cgt_lots plugin in particular implements my understanding of UK Capital Gains Tax rules, which may be incomplete or incorrect. Use at your own risk.

Installation

pip install beancount-lalitm

# With optional dependencies for specific importers
pip install beancount-lalitm[ib]      # Interactive Brokers (XML)
pip install beancount-lalitm[pdf]     # PDF-based importers
pip install beancount-lalitm[excel]   # Excel-based importers
pip install beancount-lalitm[all]     # All optional dependencies

Importers

Investment Accounts (Fully Automated)

Investment importers can run directly via beangulp since no categorization is needed.

Create an import.py:

#!/usr/bin/env python3
"""Beancount import configuration for investments."""
import beangulp
from beancount import loader
from beancount_lalitm.importers.account_lookup import AccountOracle
from beancount_lalitm.importers.ib import IbImporter

entries, errors, options = loader.load_file('main.beancount')

ib_oracle = AccountOracle(
    account='Lalit:US:IB:Brokerage',
    entries=entries,
    transfers_account='Assets:Lalit:US:IB:Transfers',
)

CONFIG = [
    IbImporter(account_currency='USD', account_oracle=ib_oracle),
]

if __name__ == '__main__':
    beangulp.Ingest(CONFIG)()

Run directly with beangulp:

python import.py extract ~/Downloads/ib-flex-query.xml >> investments.beancount

Bank Accounts (Semi-Automated)

Bank and credit card importers require categorization. Use beancount-import for a web UI that learns from your previous choices.

#!/usr/bin/env python3
"""Beancount import configuration for banks."""
from beancount_lalitm.importers.hsbc import HsbcImporter
from beancount_lalitm.importers.hsbc_uk_cc import HsbcUkCcImporter

CONFIG = [
    HsbcImporter(account='Assets:Lalit:UK:HSBC:Current'),
    HsbcUkCcImporter(account='Liabilities:Lalit:UK:HSBC:CreditCard'),
]

Run the beancount-import web UI:

python -m beancount_import.webserver \
    --journal journal.beancount \
    --ignored_path ignored.beancount \
    --account_filter '^Assets:Lalit:UK:HSBC'

Available Importers

Investment Platforms

Banks

Payroll

Plugins

Add plugins to your beancount file with the plugin directive.

ancillary_accounts

Auto-creates companion accounts for investment securities (commissions, dividends, capital gains, withholding tax).

plugin "beancount_lalitm.plugins.ancillary_accounts"

2024-01-01 open Assets:Broker:AAPL  AAPL
  ancillary_commission_currency: USD
  ancillary_distribution_currency: USD
  ancillary_capital_gains_currency: USD

stock_split

Adjusts historical transactions for stock splits.

plugin "beancount_lalitm.plugins.stock_split" "
  splits:
    - symbol: GOOG
      date: 2022-07-15
      ratio: 20
"

uk_cgt_lots

UK Capital Gains Tax lot matching using Section 104 pooling.

plugin "beancount_lalitm.plugins.uk_cgt_lots" "
  accounts:
    - name: Person:UK:Broker:GIA
      taxable: true
    - name: Person:UK:Broker:ISA
      taxable: false
"

License

Apache 2.0 - see LICENSE for details.