beancount-importer 0.3.0

Installation

$ pipx install beancount-importers

Usage

beancount-importer expects to be run from within your ledger folder, with a config.toml file configured with your account details and your patterns. The file format accepts an optional beancount-importer.patterns list containing items in the following format:

[
    'narration' | 'payee' | 'either' | 'both',
    'Account:Name',
    '^regex$',
]

Note that if using the both target kind, the payee and narration will be concatendated with a semicolon (;) for the purpose of parsing, eg.:

['both', 'Income:Salary', '^My Company;Salary$'],

If beancount-importer.patterns is specified, all definitions in that list will be applied to all your accounts.

Any transaction which does not balance – for example, one whose payee and narration matched none of your patterns – has the remaining amount booked to a default account and flagged with a ! for review. Positive residuals go to Expenses:Unknown and negative residuals to Equity:Unknown by default. Override these with the optional default_expense_account and default_equity_account keys:

[beancount-importer]
default_expense_account = 'Expenses:TODO'
default_equity_account = 'Income:TODO'

In this file, you should also list each of your accounts, eg.

[[beancount-importer.paypal]]
account = 'Assets:Paypal'

[[beancount-importer.tangerine]]
account = 'Assets:Tangerine:Checking'
lastfour = '1234'

[[beancount-importer.tangerine]]
account = 'Liabilities:Tangerine:Mastercard'
lastfour = '5678'
patterns = [...]

You can specify any number of accounts, including multiple of the same kind, so long as they parse with separate filenames. This will be verified when you run identify – any ambiguous filenames will produce an error, in which case you’ll need to handle those accounts separately. The patterns list follows the same parsing as the above global patterns object and is optional on a per-account basis; if specified, those patterns will be appended to your global pattern list and apply only to this account.

$ cd /my-beancount/ledger
$ cat config.toml
[beancount-importer]
patterns = [
    ['payee', 'Income:Salary', '^My Employer.*$'],
]

[[beancount-importer.tangerine]]
account = 'Assets:Tangerine:Checking'
lastfour = '1234'
patterns = [
    ['payee', 'Income:Tangerine:Checking:Interest', '^Interest Paid$'],
]

# Check downloaded files for errors
$ bean-import identify -v ~/Downloads

# Reconcile issues, fix parsing, adjust patterns, etc
$ bean-import extract -xe index.beancount ~/Downloads
$ vim config.toml
$ # ...repeat until no errors...

# Actually import the new data
# Note that all new data will be emitted. If your ledger files are split by
account, the easiest way to manage this is to paste into files manually:
$ bean-import extract -e index.beancount ~/Downloads | pbcopy
$ vim relevant-account-file.beancount  # paste
# If you instead use a single ledger file or a new file for each
# reconciliation pass, you can use the `-o outputfile` flag to the
# `extract` # command.

# Archive parsed statements
$ bean-import archive -o docs ~/Downloads

# Verify everything reconciled properly (command provided by beancount)
$ bean-check index.beancount

# View your ledger (command provided by fava)
$ fava index.beancount