beancount.ingest.importers

beancount.ingest.importers.config

Mixin to add support for configuring importers with multiple accounts.

This importer implements some simple common functionality to create importers which accept a long number of account names or regular expressions on the set of account names. This is inspired by functionality in the importers in the previous iteration of the ingest code, which used to be its own project.

class beancount.ingest.importers.config.ConfigImporterMixin(config)

A mixin class which supports configuration of account names.

Mix this into the implementation of a importer.ImporterProtocol.

REQUIRED_CONFIG = {'FILE': 'Account for filing imported files to'}
file_account(_)

beancount.ingest.importers.csv

CSV importer.

class beancount.ingest.importers.csv.Col

An enumeration.

ACCOUNT = '[ACCOUNT]'
AMOUNT = '[AMOUNT]'
AMOUNT_CREDIT = '[CREDIT]'
AMOUNT_DEBIT = '[DEBIT]'
BALANCE = '[BALANCE]'
DATE = '[DATE]'
DRCR = '[DRCR]'
LAST4 = '[LAST4]'
NARRATION = '[NARRATION1]'
NARRATION1 = '[NARRATION1]'
NARRATION2 = '[NARRATION2]'
NARRATION3 = '[NARRATION3]'
PAYEE = '[PAYEE]'
TAG = '[TAG]'
TXN_DATE = '[TXN_DATE]'
TXN_TIME = '[TXN_TIME]'
class beancount.ingest.importers.csv.Importer(config, account, currency, regexps=None, skip_lines=0, last4_map=None, categorizer=None, institution=None, debug=False, csv_dialect='excel', dateutil_kwds=None, narration_sep='; ', **kwds)

Importer for CSV files.

extract(file, existing_entries=None)

Extract transactions from a file.

If the importer would like to flag a returned transaction as a known duplicate, it may opt to set the special flag “__duplicate__” to True, and the transaction should be treated as a duplicate by the extraction code. This is a way to let the importer use particular information about previously imported transactions in order to flag them as duplicates. For example, if an importer has a way to get a persistent unique id for each of the imported transactions. (See this discussion for context: https://groups.google.com/d/msg/beancount/0iV-ipBJb8g/-uk4wsH2AgAJ)

Parameters
  • file – A cache.FileMemo instance.

  • existing_entries – An optional list of existing directives loaded from the ledger which is intended to contain the extracted entries. This is only provided if the user provides them via a flag in the extractor program.

Returns

A list of new, imported directives (usually mostly Transactions) extracted from the file.

file_date(file)

Get the maximum date from the file.

beancount.ingest.importers.csv.get_amounts(iconfig, row, allow_zero_amounts=False)

Get the amount columns of a row.

Parameters
  • iconfig – A dict of Col to row index.

  • row – A row array containing the values of the given row.

  • allow_zero_amounts – Is a transaction with amount D(‘0.00’) okay? If not, return (None, None).

Returns

A pair of (debit-amount, credit-amount), both of which are either an instance of Decimal or None, or not available.

beancount.ingest.importers.csv.normalize_config(config, head, dialect='excel')

Using the header line, convert the configuration field name lookups to int indexes.

Parameters
  • config – A dict of Col types to string or indexes.

  • head – A string, some decent number of bytes of the head of the file.

  • dialect – A dialect definition to parse the header

Returns

A pair of

A dict of Col types to integer indexes of the fields, and a boolean, true if the file has a header.

Raises

ValueError – If there is no header and the configuration does not consist entirely of integer indexes.

beancount.ingest.importers.fileonly

A simplistic importer that can be used just to file away some download.

Sometimes you just want to save and accumulate data

class beancount.ingest.importers.fileonly.Importer(**kwds)

An importer that supports only matching (identification) and filing.

beancount.ingest.importers.ofx

OFX file format importer for bank and credit card statements.

https://en.wikipedia.org/wiki/Open_Financial_Exchange

This importer will parse a single account in the OFX file. Instantiate it multiple times with different accounts if it has many accounts. It makes more sense to do it this way so that you can define your importer configuration account by account.

Note that this importer is provided as an example and with no guarantees. It’s not really super great. On the other hand, I’ve been using it for more than five years over multiple accounts, so it has been useful to me (it works, by some measure of “works”). If you need a more powerful or compliant OFX importer please consider either writing one or contributing changes. Also, this importer does its own very basic parsing; a better one would probably use (and depend on) the ofxparse module (see https://sites.google.com/site/ofxparse/).

class beancount.ingest.importers.ofx.BalanceType

Type of Balance directive to be inserted.

DECLARED = 1
LAST = 2
NONE = 0
class beancount.ingest.importers.ofx.Importer(acctid_regexp, account, basename=None, balance_type=<BalanceType.DECLARED: 1>)

An importer for Open Financial Exchange files.

extract(file, existing_entries=None)

Extract a list of partially complete transactions from the file.

file_account(_)

Return the account against which we post transactions.

file_date(file)

Return the optional renamed account filename.

file_name(file)

Return the optional renamed account filename.

identify(file)

Return true if this importer matches the given file.

Parameters

file – A cache.FileMemo instance.

Returns

A boolean, true if this importer can handle this file.

name()

Include the filing account in the name.

beancount.ingest.importers.ofx.build_transaction(stmttrn, flag, account, currency)

Build a single transaction.

Parameters
  • stmttrn – A <STMTTRN> bs4.element.Tag.

  • flag – A single-character string.

  • account – An account string, the account to insert.

  • currency – A currency string.

Returns

A Transaction instance.

beancount.ingest.importers.ofx.extract(soup, filename, acctid_regexp, account, flag, balance_type)

Extract transactions from an OFX file.

Parameters
  • soup – A BeautifulSoup root node.

  • acctid_regexp – A regular expression string matching the account we’re interested in.

  • account – An account string onto which to post the amounts found in the file.

  • flag – A single-character string.

  • balance_type – An enum of type BalanceType.

Returns

A sorted list of entries.

beancount.ingest.importers.ofx.find_acctids(contents)

Find the list of <ACCTID> tags.

Parameters

contents – A string, the contents of the OFX file.

Returns

A list of strings, the contents of the <ACCTID> tags.

beancount.ingest.importers.ofx.find_child(node, name, conversion=None)

Find a child under the given node and return its value.

Parameters
  • node – A <STMTTRN> bs4.element.Tag.

  • name – A string, the name of the child node.

  • conversion – A callable object used to convert the value to a new data type.

Returns

A string, or None.

beancount.ingest.importers.ofx.find_currency(soup)

Find the first currency in the XML tree.

Parameters

soup – A BeautifulSoup root node.

Returns

A string, the first currency found in the file. Returns None if no currency is found.

beancount.ingest.importers.ofx.find_max_date(contents)

Extract the report date from the file.

beancount.ingest.importers.ofx.find_statement_transactions(soup)

Find the statement transaction sections in the file.

Parameters

soup – A BeautifulSoup root node.

Yields
A trip of

An account id string, A currency string, A list of transaction nodes (<STMTTRN> BeautifulSoup tags), and A (date, balanace amount) for the <LEDGERBAL>.

beancount.ingest.importers.ofx.parse_ofx_time(date_str)

Parse an OFX time string and return a datetime object.

Parameters

date_str – A string, the date to be parsed.

Returns

A datetime.datetime instance.