NPO-Accounting/conservancy_beancount
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

reconciler: Re-wrap module docstring at 80 chars

Browse source
This commit is contained in:
Ben Sturmfels 2023-02-11 14:51:13 +11:00
parent 3acc097d32
commit 93d102539a
Signed by: bsturmfels
GPG key ID: 023C05E2C9C068F0
1 changed files with 55 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
conservancy_beancount/reconcile/statement_reconciler.py
View file

@ -1,22 +1,19 @@
"""Compare a bank CSV statement with the books. """Compare a bank CSV statement with the books.
This tool takes an AMEX or First Republic CSV statement file and This tool takes an AMEX or First Republic CSV statement file and compares it
compares it line-by-line with the Beancount books to make sure that line-by-line with the Beancount books to make sure that everything matches. This
everything matches. This is designed for situations where transactions is designed for situations where transactions are entered into the books
are entered into the books directly, rather than being imported from a directly, rather than being imported from a statement after the fact.
statement after the fact.
The reconciler will attempt to match transactions based on date, The reconciler will attempt to match transactions based on date, amount, check
amount, check number and payee, but is forgiving to differences in number and payee, but is forgiving to differences in dates, the absensce of
dates, the absensce of check number and inexact matches on check number and inexact matches on payee. Matches are ranked, so where there is
payee. Matches are ranked, so where there is only one decent match for only one decent match for an amount/date this is accepted, but if there are
an amount/date this is accepted, but if there are multiple similar multiple similar candidates it will refuse to guess.
candidates it will refuse to guess.
The reconciler will also attempt to identify where a single statement The reconciler will also attempt to identify where a single statement entry has
entry has been split out into multiple Beancount postings, such as a been split out into multiple Beancount postings, such as a single bank transfer
single bank transfer representing health insurance for multiple representing health insurance for multiple employees.
employees.
Run it like this: Run it like this:
@ -28,71 +25,74 @@ $ statement_reconciler \
Background: Background:
Beancount users often write importers to create bookkeeping entries Regular Beancount users often write automated importers to create bookkeeping
direct from a bank statement or similar. That approach automates data entries direct from a bank statement or similar. That combines data entry and
entry and reconciliation in one step. In some cases though, it's reconciliation in one step. Conservancy uses a different approach; they manually
useful to manually enter transactions and reconcile them later entering transactions and reconciling them later on. This workflow is helpful in
on. This workflow helpful in cases like writing a paper check when cases like writing checks (see below). This is the workflow implented by this
there's a time lag between committing to making a payment and the tool.
funds being debited. That's the workflow we're using here.
Conservancy currently enter data by hand rather than using Beancount That said, this tool *is* still somewhat like an importer in that it needs to
importers. This tool is still somewhat like an importer in that it extract transaction details from a third-party statement. Instead of creating
needs to extract transaction details from a third-party directives, it just checks to see that similar directives are already
statement. Instead of creating directives, it just checks to see that present. This is a bit like diff-ing a statement with the books (though we're
similar directives are already present. This is a bit like diff-ing a only interested in the presence of lines, not so much their order).
statement with the books (though we're only interested in the presence
of lines, not so much their order).
Paper checks are entered in the books when written (a.k.a. "posted"), Paper checks are entered into the books when written (a.k.a. "posted"), but may
but may not be cashed until months later sometimes causing not be cashed until months later sometimes causing reconciliation differences
reconciliation differences that live beyond a month. It's worth noting that live beyond a month. It's worth noting that there are really two dates here
that there are really two dates here - the posting date and the - the posting date and the cleared date. Beancount only allows us to model one,
cleared date. Beancount only allows us to model one, which is why which is why carrying these reconciliation differences between months feels a
carrying these reconciliation differences between months feels a bit bit awkward.
awkward.
Problems in scope: Problems in scope:
- errors in the books take hours to find during reconciliation, - errors in the books take hours to find during reconciliation, requiring
requiring manually comparing statements and the books and are manually comparing statements and the books and are succeptible to mistakes,
succeptible to mistakes, such as not noticing when there are two such as not noticing when there are two payments for the same amount on the
payments for the same amount on the statement, but not in the books statement, but not in the books (as Bradley likes to quote, "you're entering
(as Bradley likes to quote, "you're entering a world of pain") a world of pain")
- adding statement/reconciliation metadata to books is/was manual and - adding statement/reconciliation metadata to books is/was manual and prone to
prone to mistakes mistakes
- jumping to an individual transaction in a large ledger isn't - jumping to an individual transaction in a large ledger isn't trivial - Emacs
trivial - Emacs grep mode is the current best option grep mode is the current best option
- Pam and other staff don't use Emacs - not all staff use Emacs
- auditors would prefer Bradley didn't perform reconciliation, - auditors would prefer Bradley didn't perform reconciliation, ideally not
ideally not Rosanne either Rosanne either
- reconciliation reports are created by hand when there are mismatches - reconciliation reports are created by hand when there are mismatches
Other related problems we're not dealing with here: Other related problems we're not dealing with here:
- after updates to the books files, beancount must be restarted to - after updates to the books files, beancount must be restarted to reflect
reflect updates updates
- updates also invalidate the cache meaning restart takes several - updates also invalidate the cache meaning restart takes several minutes
minutes
- balance checks are manually updated in - balance checks are manually updated in
svn/Financial/Ledger/sanity-check-balances.yaml svn/Financial/Ledger/sanity-check-balances.yaml
- transactions are entered manually and reconciled after the fact, - transactions are entered manually and reconciled after the fact, but
but importing from statements may be useful in some cases importing from statements may be useful in some cases
Future possibilities:
- allow the reconciler to respect manually-applied metadata - not clear how
this would work exactly
- allow interactive matching where the user can specifiy a match
- consider combining this with helper.py into one more complete tool that both
reconciles and summarises the unreconciled transactions
""" """
# TODO: # TODO:
# - entry_point seems to swallow errors # - entry_point seems to swallow errors
# - extract the magic numbers # - extract the magic numbers
# - consider merging in helper.py
import argparse import argparse
import collections import collections