beancount.parser

Parser module for beancount input files.

beancount.parser._parser

Beancount parser extension module

beancount.parser._parser.get_yyfilename()
beancount.parser._parser.get_yylineno()
beancount.parser._parser.lexer_finalize()
beancount.parser._parser.lexer_initialize()
beancount.parser._parser.lexer_next()
beancount.parser._parser.parse_file()

Parse the filename, calling back methods on the builder. Your builder is responsible to accumulating results. If you pass in ‘-‘ for filename, stdin is parsed.

beancount.parser._parser.parse_string()

Parse the given string, calling back methods on the builder. Your builder is responsible to accumulating results.

beancount.parser.booking

Algorithms for ‘booking’ inventory, that is, the process of finding a matching lot when reducing the content of an inventory.

class beancount.parser.booking.BookingError(source, message, entry)
beancount.parser.booking.book(incomplete_entries, options_map)

Book inventory lots and complete all positions with incomplete numbers.

Parameters
  • incomplete_entries – A list of directives, with some postings possibly left with incomplete amounts as produced by the parser.

  • options_map – An options dict as produced by the parser.

Returns

A pair of

entries: A list of completed entries with all their postings completed. errors: New errors produced during interpolation.

beancount.parser.booking.validate_inventory_booking(entries, unused_options_map, booking_methods)

Validate that no position at cost is allowed to go negative.

This routine checks that when a posting reduces a position, existing or not, that the subsequent inventory does not result in a position with a negative number of units. A negative number of units would only be required for short trades of trading spreads on futures, and right now this is not supported. It would not be difficult to support this, however, but we want to be strict about it, because being pedantic about this is otherwise a great way to detect user data entry mistakes.

Parameters
  • entries – A list of directives.

  • unused_options_map – An options map.

  • booking_methods – A mapping of account name to booking method, accumulated in the main loop.

Returns

A list of errors.

beancount.parser.booking.validate_missing_eliminated(entries, unused_options_map)

Validate that all the missing bits of postings have been eliminated.

Parameters
  • entries – A list of directives.

  • unused_options_map – An options map.

Returns

A list of errors.

beancount.parser.booking_full

Full (new) booking implementation.

Problem description:

Interpolation and booking feed on each other, that is, numbers filled in from interpolation might affect the booking process, and numbers derived from the booking process may help carry out interpolation that would otherwise be under-defined. Here’s an example of interpolation helping the booking process:

Assume the ante-inventory of Assets:Investments contains two lots of shares of HOOL, one at 100.00 USD and the other at 101.00 USD and apply this transaction:

2015-09-30 *

Assets:Investments -10 HOOL {USD} Assets:Cash 1000 USD Income:Gains -200 USD

Interpolation is unambiguously able to back out a cost of 100 USD / HOOL, which would then result in an unambiguous booking result.

On the other hand, consider this transaction:

2015-09-30 *

Assets:Investments -10 HOOL {USD} Assets:Cash 1000 USD Income:Gains

Now the interpolation cannot succeed. If the Assets:Investments account is configured to use the FIFO method, the 10 oldest shares would be selected for the cost, and we could then interpolate the capital gains correctly.

First observation: The second case is much more frequent than the first, and the first is easily resolved manually by requiring a particular cost be specified. Moreover, in many cases there isn’t just a single lot of shares to be reduced from and figuring out the correct set of shares given a target cost is an underspecified problem.

Second observation: Booking can only be achieved for inventory reductions, not for augmentations. Therefore, we should carry out booking on inventory reductions and fail early if reduction is undefined there, and leave inventory augmentations with missing numbers undefined, so that interpolation can fill them in at a later stage.

Note that one case we’d like to but may not be able to handle is of a reduction with interpolated price, like this:

2015-09-30 *

Assets:Investments -10 HOOL {100.00 # USD} Expenses:Commission 9.95 USD Assets:Cash 990.05 USD

Therefore we choose to

  1. Carry out booking first, on inventory reductions only, and leave inventory augmentations as they are, possibly undefined. The ‘cost’ attributed of booked postings are converted from CostSpec to Cost. Augmented postings with missing amounts are left as CostSpec instances in order to allow for interpolation of total vs. per-unit amount.

  2. Compute interpolations on the resulting postings. Undefined costs for inventory augmentations may be filled in by interpolations at this stage (if possible).

  3. Finally, convert the interpolated CostSpec instances to Cost instances.

Improving on this algorithm would require running a loop over the booking and interpolation steps until all numbers are resolved or no more inference can occur. We may consider that for later, as an experimental feature. My hunch is that there are so few cases for which this would be useful that we won’t bother improving on the algorithm above.

class beancount.parser.booking_full.CategorizationError(source, message, entry)
class beancount.parser.booking_full.InterpolationError(source, message, entry)
class beancount.parser.booking_full.MissingType

The type of missing number.

COST_PER = 2
COST_TOTAL = 3
PRICE = 4
UNITS = 1
class beancount.parser.booking_full.ReductionError(source, message, entry)
class beancount.parser.booking_full.Refer(index, units_currency, cost_currency, price_currency)
class beancount.parser.booking_full.SelfReduxError(source, message, entry)
beancount.parser.booking_full.book(entries, options_map, methods)

Interpolate missing data from the entries using the full historical algorithm. See the internal implementation _book() for details. This method only stripes some of the return values.

See _book() for arguments and return values.

beancount.parser.booking_full.book_reductions(entry, group_postings, balances, methods)

Book inventory reductions against the ante-balances.

This function accepts a dict of (account, Inventory balance) and for each posting that is a reduction against its inventory, attempts to find a corresponding lot or list of lots to reduce the balance with.

  • For reducing lots, the CostSpec instance of the posting is replaced by a Cost instance.

  • For augmenting lots, the CostSpec instance of the posting is left alone, except for its date, which is inherited from the parent Transaction.

Parameters
  • entry – An instance of Transaction. This is only used to refer to when logging errors.

  • group_postings – A list of Posting instances for the group.

  • balances – A dict of account name to inventory contents.

  • methods – A mapping of account name to their corresponding booking method enum.

Returns

A pair of
booked_postings: A list of booked postings, with reducing lots resolved

against specific position in the corresponding accounts’ ante-inventory balances. Note single reducing posting in the input may result in multiple postings in the output. Also note that augmenting postings held-at-cost will still refer to ‘cost’ instances of CostSpec, left to be interpolated later.

errors: A list of errors, if there were any.

beancount.parser.booking_full.categorize_by_currency(entry, balances)

Group the postings by the currency they declare.

This is used to prepare the postings for the next stages: Interpolation and booking will then be carried out separately on each currency group. At the outset of this routine, we should have distinct groups of currencies without any ambiguities regarding which currency they need to balance against.

Here’s how this works.

  • First we apply the constraint that cost-currency and price-currency must match, if there is both a cost and a price. This reduces the space of possibilities somewahte.

  • If the currency is explicitly specified, we put the posting in that currency’s bucket.

  • If not, we have a few methods left to disambiguate the currency:

    1. We look at the remaining postings… if they are all of a single currency, the posting must be in that currency too.

    2. If we cannot do that, we inspect the contents of the inventory of the account for the posting. If all the contents are of a single currency, we use that one.

Parameters
  • postings – A list of incomplete postings to categorize.

  • balances – A dict of currency to inventory contents before the transaction is applied.

Returns

A list of (currency string, list of tuples) items describing each postings and its interpolated currencies, and a list of generated errors for currency interpolation. The entry’s original postings are left unmodified. Each tuple in the value-list contains:

index: The posting index in the original entry. units_currency: The interpolated currency for units. cost_currency: The interpolated currency for cost. price_currency: The interpolated currency for price.

beancount.parser.booking_full.compute_cost_number(costspec, units)

Given a CostSpec, return the cost number, if possible to compute.

Parameters
  • costspec – A parsed instance of CostSpec.

  • units – An instance of Amount for the units of the position.

Returns

If it is not possible to calculate the cost, return None. Otherwise, returns a Decimal instance, the per-unit cost.

beancount.parser.booking_full.convert_costspec_to_cost(posting)

Convert an instance of CostSpec to Cost, if present on the posting.

If the posting has no cost, it itself is just returned.

Parameters

posting – An instance of Posting.

Returns

An instance of Posting with a possibly replaced ‘cost’ attribute.

beancount.parser.booking_full.get_bucket_currency(refer)

Given currency references for a posting, return the bucket currency.

Parameters

refer – An instance of Refer.

Returns

A currency string.

beancount.parser.booking_full.has_self_reduction(postings, methods)

Return true if the postings potentially reduce each other at cost.

Parameters
  • postings – A list of postings with uninterpolated CostSpec cost instances.

  • methods – A mapping of account name to their corresponding booking method.

Returns

A boolean, true if there’s a potential for self-reduction.

beancount.parser.booking_full.interpolate_group(postings, balances, currency, tolerances)

Interpolate missing numbers in the set of postings.

Parameters
  • postings – A list of Posting instances.

  • balances – A dict of account to its ante-inventory.

  • currency – The weight currency of this group, used for reporting errors.

  • tolerances – A dict of currency to tolerance values.

Returns

A tuple of

postings: A lit of new posting instances. errors: A list of errors generated during interpolation. interpolated: A boolean, true if we did have to interpolate.

In the case of an error, this returns the original list of postings, which is still incomplete. If an error is returned, you should probably skip the transaction altogether, or just not include the postings in it. (An alternative behaviour would be to return only the list of valid postings, but that would likely result in an unbalanced transaction. We do it this way by choice.)

beancount.parser.booking_full.replace_currencies(postings, refer_groups)

Replace resolved currencies in the entry’s Postings.

This essentially applies the findings of categorize_by_currency() to produce new postings with all currencies resolved.

Parameters
  • postings – A list of Posting instances to replace.

  • refer_groups – A list of (currency, list of posting references) items as returned by categorize_by_currency().

Returns

A new list of items of (currency, list of Postings), postings for which the currencies have been replaced by their interpolated currency values.

beancount.parser.booking_method

Implementations of all the particular booking methods. This code is used by the full booking algorithm.

class beancount.parser.booking_method.AmbiguousMatchError(source, message, entry)
beancount.parser.booking_method.booking_method_AVERAGE(entry, posting, matches)

AVERAGE booking method implementation.

beancount.parser.booking_method.booking_method_FIFO(entry, posting, matches)

FIFO booking method implementation.

beancount.parser.booking_method.booking_method_LIFO(entry, posting, matches)

LIFO booking method implementation.

beancount.parser.booking_method.booking_method_NONE(entry, posting, matches)

NONE booking method implementation.

beancount.parser.booking_method.booking_method_STRICT(entry, posting, matches)

Strict booking method.

Parameters
  • entry – The parent Transaction instance.

  • posting – An instance of Posting, the reducing posting which we’re attempting to match.

  • matches – A list of matching Position instances from the ante-inventory. Those positions are known to already match the ‘posting’ spec.

Returns

A triple of
booked_postings: A list of matched Posting instances, whose ‘cost’

attributes are ensured to be of type Cost.

errors: A list of errors to be generated. insufficient: A boolean, true if we could not find enough matches

to fulfill the reduction.

beancount.parser.booking_method.handle_ambiguous_matches(entry, posting, matches, method)

Handle ambiguous matches by dispatching to a particular method.

Parameters
  • entry – The parent Transaction instance.

  • posting – An instance of Posting, the reducing posting which we’re attempting to match.

  • matches – A list of matching Position instances from the ante-inventory. Those positions are known to already match the ‘posting’ spec.

  • methods – A mapping of account name to their corresponding booking method.

Returns

A pair of
booked_postings: A list of matched Posting instances, whose ‘cost’

attributes are ensured to be of type Cost.

errors: A list of errors to be generated.

beancount.parser.cmptest

Support utillities for testing scripts.

class beancount.parser.cmptest.TestCase(methodName='runTest')
assertEqualEntries(expected_entries, actual_entries)
assertExcludesEntries(subset_entries, entries)
assertIncludesEntries(subset_entries, entries)
exception beancount.parser.cmptest.TestError

Errors within the test implementation itself. These should never occur.

beancount.parser.cmptest.assertEqualEntries(expected_entries, actual_entries, failfunc=<function fail>, allow_incomplete=False)

Compare two lists of entries exactly and print missing entries verbosely if they occur.

Parameters
  • expected_entries – Either a list of directives or a string, in which case the string is run through beancount.parser.parse_string() and the resulting list is used.

  • actual_entries – Same treatment as expected_entries, the other list of directives to compare to.

  • failfunc – A function to call on failure.

  • allow_incomplete – A boolean, true if we allow incomplete inputs and perform light-weight booking.

Raises

AssertionError – If the exception fails.

beancount.parser.cmptest.assertExcludesEntries(subset_entries, entries, failfunc=<function fail>, allow_incomplete=False)

Check that subset_entries is not included in entries and print extra entries.

Parameters
  • subset_entries – Either a list of directives or a string, in which case the string is run through beancount.parser.parse_string() and the resulting list is used.

  • entries – Same treatment as subset_entries, the other list of directives to compare to.

  • failfunc – A function to call on failure.

  • allow_incomplete – A boolean, true if we allow incomplete inputs and perform light-weight booking.

Raises

AssertionError – If the exception fails.

beancount.parser.cmptest.assertIncludesEntries(subset_entries, entries, failfunc=<function fail>, allow_incomplete=False)

Check that subset_entries is included in entries and print missing entries.

Parameters
  • subset_entries – Either a list of directives or a string, in which case the string is run through beancount.parser.parse_string() and the resulting list is used.

  • entries – Same treatment as subset_entries, the other list of directives to compare to.

  • failfunc – A function to call on failure.

  • allow_incomplete – A boolean, true if we allow incomplete inputs and perform light-weight booking.

Raises

AssertionError – If the exception fails.

beancount.parser.cmptest.read_string_or_entries(entries_or_str, allow_incomplete=False)

Read a string of entries or just entries.

Parameters
  • entries_or_str – Either a list of directives, or a string containing directives.

  • allow_incomplete – A boolean, true if we allow incomplete inputs and perform light-weight booking.

Returns

A list of directives.

beancount.parser.grammar

Builder for Beancount grammar.

class beancount.parser.grammar.Builder(filename)

A builder used by the lexer and grammar parser as callbacks to create the data objects corresponding to rules parsed from the input file.

amount(number, currency)

Process an amount grammar rule.

Parameters
  • number – a Decimal instance, the number of the amount.

  • currency – a currency object (a str, really, see CURRENCY above)

Returns

An instance of Amount.

balance(filename, lineno, date, account, amount, tolerance, kvlist)

Process an assertion directive.

We produce no errors here by default. We replace the failing ones in the routine that does the verification later one, that these have succeeded or failed.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the account to balance.

  • amount – The expected amount, to be checked.

  • tolerance – The tolerance number.

  • kvlist – a list of KeyValue instances.

Returns

A new Balance object.

build_grammar_error(filename, lineno, exc_value, exc_type=None, exc_traceback=None)

Build a grammar error and appends it to the list of pending errors.

Parameters
  • filename – The current filename

  • lineno – The current line number

  • excvalue – The exception value, or a str, the message of the error.

  • exc_type – An exception type, if an exception occurred.

  • exc_traceback – A traceback object.

close(filename, lineno, date, account, kvlist)

Process a close directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the name of the account.

  • kvlist – a list of KeyValue instances.

Returns

A new Close object.

commodity(filename, lineno, date, currency, kvlist)

Process a close directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • currency – A string, the commodity being declared.

  • kvlist – a list of KeyValue instances.

Returns

A new Close object.

compound_amount(number_per, number_total, currency)

Process an amount grammar rule.

Parameters
  • number_per – a Decimal instance, the number of the cost per share.

  • number_total – a Decimal instance, the number of the cost over all shares.

  • currency – a currency object (a str, really, see CURRENCY above)

Returns

A triple of (Decimal, Decimal, currency string) to be processed further when creating the final per-unit cost number.

cost_merge(_)

Create a ‘merge cost’ token.

cost_spec(cost_comp_list, is_total)

Process a cost_spec grammar rule.

Parameters
  • cost_comp_list – A list of CompoundAmount, a datetime.date, or label ID strings.

  • is_total – Assume only the total cost is specified; reject the <number> # <number> syntax, that is, no compound amounts may be specified. This is used to support the {{…}} syntax.

Returns

A cost-info tuple of CompoundAmount, lot date and label string. Any of these may be set to a sentinel indicating “unset”.

custom(filename, lineno, date, dir_type, custom_values, kvlist)

Process a custom directive.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • dir_type – A string, a type for the custom directive being parsed.

  • custom_values – A list of the various tokens seen on the same line.

  • kvlist – a list of KeyValue instances.

Returns

A new Custom object.

custom_value(value, dtype=None)

Create a custom value object, along with its type.

Parameters

value – One of the accepted custom values.

Returns

A pair of (value, dtype) where ‘dtype’ is the datatype is that of the value.

dcupdate(number, currency)

Update the display context.

document(filename, lineno, date, account, document_filename, tags_links, kvlist)

Process a document directive.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • account – an Account instance.

  • document_filename – a str, the name of the document file.

  • tags_links – The current TagsLinks accumulator.

  • kvlist – a list of KeyValue instances.

Returns

A new Document object.

event(filename, lineno, date, event_type, description, kvlist)

Process an event directive.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • event_type – a str, the name of the event type.

  • description – a str, the event value, the contents.

  • kvlist – a list of KeyValue instances.

Returns

A new Event object.

finalize()

Finalize the parser, check for final errors and return the triple.

Returns

A triple of

entries: A list of parsed directives, which may need completion. errors: A list of errors, hopefully empty. options_map: A dict of options.

Finally amend tags and links and return final objects to be inserted.

Parameters
  • tags – A set of tag strings (warning: this gets mutated in-place).

  • links – A set of link strings.

Returns

A sanitized pair of (tags, links).

get_entries()

Return the accumulated entries.

Returns

A list of sorted directives.

get_invalid_account()

See base class.

get_long_string_maxlines()

See base class.

get_options()

Return the final options map.

Returns

A dict of option names to options.

handle_list(object_list, new_object)

Handle a recursive list grammar rule, generically.

Parameters
  • object_list – the current list of objects.

  • new_object – the new object to be added.

Returns

The new, updated list of objects.

include(filename, lineno, include_filename)

Process an include directive.

Parameters
  • filename – current filename.

  • lineno – current line number.

  • include_name – A string, the name of the file to include.

key_value(key, value)

Process a document directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the account the document relates to.

  • document_filename – A str, the name of the document file.

Returns

A new KeyValue object.

note(filename, lineno, date, account, comment, kvlist)

Process a note directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the account to attach the note to.

  • comment – A str, the note’s comments contents.

  • kvlist – a list of KeyValue instances.

Returns

A new Note object.

open(filename, lineno, date, account, currencies, booking_str, kvlist)

Process an open directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the name of the account.

  • currencies – A list of constraint currencies.

  • booking_str – A string, the booking method, or None if none was specified.

  • kvlist – a list of KeyValue instances.

Returns

A new Open object.

option(filename, lineno, key, value)

Process an option directive.

Parameters
  • filename – current filename.

  • lineno – current line number.

  • key – option’s key (str)

  • value – option’s value

pad(filename, lineno, date, account, source_account, kvlist)

Process a pad directive.

Parameters
  • filename – The current filename.

  • lineno – The current line number.

  • date – A datetime object.

  • account – A string, the account to be padded.

  • source_account – A string, the account to pad from.

  • kvlist – a list of KeyValue instances.

Returns

A new Pad object.

pipe_deprecated_error(filename, lineno)

Issue a ‘Pipe deprecated’ error.

Parameters
  • filename – The current filename

  • lineno – The current line number

plugin(filename, lineno, plugin_name, plugin_config)

Process a plugin directive.

Parameters
  • filename – current filename.

  • lineno – current line number.

  • plugin_name – A string, the name of the plugin module to import.

  • plugin_config – A string or None, an optional configuration string to pass in to the plugin module.

popmeta(key)

Removed a key off the current set of stacks.

Parameters

key – A string, a key to be removed from the meta dict.

poptag(tag)

Pop a tag off the current set of stacks.

Parameters

tag – A string, a tag to be removed from the current set of tags.

posting(filename, lineno, account, units, cost, price, istotal, flag)

Process a posting grammar rule.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • account – A string, the account of the posting.

  • units – An instance of Amount for the units.

  • cost – An instance of CostSpec for the cost.

  • price – Either None, or an instance of Amount that is the cost of the position.

  • istotal – A bool, True if the price is for the total amount being parsed, or False if the price is for each lot of the position.

  • flag – A string, one-character, the flag associated with this posting.

Returns

A new Posting object, with no parent entry.

price(filename, lineno, date, currency, amount, kvlist)

Process a price directive.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • currency – the currency to be priced.

  • amount – an instance of Amount, that is the price of the currency.

  • kvlist – a list of KeyValue instances.

Returns

A new Price object.

pushmeta(key, value)

Set a metadata field on the current key-value pairs to be added to transactions.

Parameters

key_value – A KeyValue instance, to be added to the dict of metadata.

pushtag(tag)

Push a tag on the current set of tags.

Note that this does not need to be stack ordered.

Parameters

tag – A string, a tag to be added.

query(filename, lineno, date, query_name, query_string, kvlist)

Process a document directive.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • query_name – a str, the name of the query.

  • query_string – a str, the SQL query itself.

  • kvlist – a list of KeyValue instances.

Returns

A new Query object.

store_result(entries)

Start rule stores the final result here.

Parameters

entries – A list of entries to store.

Add a link to the TagsLinks accumulator.

Parameters
  • tags_links – The current TagsLinks accumulator.

  • link – A string, the new link to insert.

Returns

An updated TagsLinks instance.

Add a string to the TagsLinks accumulator.

Parameters
  • tags_links – The current TagsLinks accumulator.

  • string – A string, the new string to insert in the list.

Returns

An updated TagsLinks instance.

Add a tag to the TagsLinks accumulator.

Parameters
  • tags_links – The current TagsLinks accumulator.

  • tag – A string, the new tag to insert.

Returns

An updated TagsLinks instance.

Create a new TagsLinks instance.

Returns

An instance of TagsLinks, initialized with expected attributes.

transaction(filename, lineno, date, flag, txn_strings, tags_links, posting_or_kv_list)

Process a transaction directive.

All the postings of the transaction are available at this point, and so the the transaction is balanced here, incomplete postings are completed with the appropriate position, and errors are being accumulated on the builder to be reported later on.

This is the main routine that takes up most of the parsing time; be very careful with modifications here, they have an impact on performance.

Parameters
  • filename – the current filename.

  • lineno – the current line number.

  • date – a datetime object.

  • flag – a str, one-character, the flag associated with this transaction.

  • txn_strings – A list of strings, possibly empty, possibly longer.

  • tags_links – A TagsLinks namedtuple of tags, and/or links.

  • posting_or_kv_list – a list of Posting or KeyValue instances, to be inserted in this transaction, or None, if no postings have been declared.

Returns

A new Transaction object.

unpack_txn_strings(txn_strings, meta)

Unpack a tags_links accumulator to its payee and narration fields.

Parameters
  • txn_strings – A list of strings.

  • meta – A metadata dict for errors generated in this routine.

Returns

A pair of (payee, narration) strings or None objects, or None, if there was an error.

class beancount.parser.grammar.CompoundAmount(number_per, number_total, currency)
class beancount.parser.grammar.DeprecatedError(source, message, entry)
class beancount.parser.grammar.KeyValue(key, value)
class beancount.parser.grammar.ParserError(source, message, entry)
class beancount.parser.grammar.ParserSyntaxError(source, message, entry)
class beancount.parser.grammar.ValueType(value, dtype)
beancount.parser.grammar.valid_account_regexp(options)

Build a regexp to validate account names from the options.

Parameters

options – A dict of options, as per beancount.parser.options.

Returns

A string, a regular expression that will match all account names.

beancount.parser.hashsrc

Compute a hash of the source files in order to warn when the source goes out of date.

beancount.parser.hashsrc.check_parser_source_files()

Check the extension module’s source hash and issue a warning if the current source differs from that of the module.

If the source files aren’t located in the Python source directory, ignore the warning, we’re probably running this from an installed based, in which case we don’t need to check anything (this check is useful only for people running directly from source).

beancount.parser.hashsrc.hash_parser_source_files()

Compute a unique hash of the parser’s Python code in order to bake that into the extension module. This is used at load-time to verify that the extension module and the corresponding Python codes match each other. If not, it issues a warning that you should rebuild your extension module.

Returns

A string, the hexadecimal unique hash of relevant source code that should trigger a recompilation.

beancount.parser.lexer

Beancount syntax lexer.

class beancount.parser.lexer.LexBuilder

A builder used only for building lexer objects.

long_string_maxlines_default

Number of lines for a string to trigger a warning. This is meant to help users detecting dangling quotes in their source.

ACCOUNT(account_name)

Process an ACCOUNT token.

This function attempts to reuse an existing account if one exists, otherwise creates one on-demand.

Parameters

account_name – a str, the valid name of an account.

Returns

A string, the name of the account.

CURRENCY(currency_name)

Process a CURRENCY token.

Parameters

currency_name – the name of the currency.

Returns

A new currency object; for now, these are simply represented as the currency name.

DATE(year, month, day)

Process a DATE token.

Parameters
  • year – integer year.

  • month – integer month.

  • day – integer day

Returns

A new datetime object.

KEY(ident)

Process an identifier token.

Parameters

ident – a str, the name of the key string.

Returns

The link string itself. For now we don’t need to represent this by an object.

Process a LINK token.

Parameters

link – a str, the name of the string.

Returns

The link string itself. For now we don’t need to represent this by an object.

NUMBER(number)

Process a NUMBER token. Convert into Decimal.

Parameters

number – a str, the number to be converted.

Returns

A Decimal instance built of the number string.

STRING(string)

Process a STRING token.

Parameters

string – the string to process.

Returns

The string. Nothing to be done or cleaned up. Eventually we might do some decoding here.

TAG(tag)

Process a TAG token.

Parameters

tag – a str, the tag to be processed.

Returns

The tag string itself. For now we don’t need an object to represent those; keeping it simple.

build_lexer_error(message, exc_type=None)

Build a lexer error and appends it to the list of pending errors.

Parameters
  • message – The message of the error.

  • exc_type – An exception type, if an exception occurred.

get_invalid_account()

Return the name of an invalid account placeholder.

When an account name is not deemed a valid one, replace it by this account name. This can be overridden by the parser to take into account the options.

Returns

A string, the name of the root/type for invalid account names.

get_lexer_location()
class beancount.parser.lexer.LexerError(source, message, entry)
beancount.parser.lexer.lex_iter(file, builder=None, encoding=None)

An iterator that yields all the tokens in the given file.

Parameters
  • file – A string, the filename to run the lexer on, or a file object.

  • builder – A builder of your choice. If not specified, a LexBuilder is used and discarded (along with its errors).

  • encoding – A string (or None), the default encoding to use for strings.

Yields

Tuples of the token (a string), the matched text (a string), and the line no (an integer).

beancount.parser.lexer.lex_iter_string(string, builder=None, encoding=None)

Parse an input string and print the tokens to an output file.

Parameters
  • input_string – a str or bytes, the contents of the ledger to be parsed.

  • builder – A builder of your choice. If not specified, a LexBuilder is used and discarded (along with its errors).

  • encoding – A string (or None), the default encoding to use for strings.

Returns

A iterator on the string. See lex_iter() for details.

beancount.parser.options

Declaration of options and their default values.

beancount.parser.options.Opt(name, default_value, example_value=<object object>, converter=None, deprecated=False, alias=None)

Alternative constructor for OptDesc, with default values.

Parameters
  • name – See OptDesc.

  • default_value – See OptDesc.

  • example_value – See OptDesc.

  • converter – See OptDesc.

  • deprecated – See OptDesc.

  • alias – See OptDesc.

Returns

An instance of OptDesc.

class beancount.parser.options.OptDesc(name, default_value, example_value, converter, deprecated, alias)
class beancount.parser.options.OptGroup(description, options)
beancount.parser.options.get_account_types(options)

Extract the account type names from the parser’s options.

Parameters

options – a dict of ledger options.

Returns

An instance of AccountTypes, that contains all the prefixes.

beancount.parser.options.get_current_accounts(options)

Return account names for the current earnings and conversion accounts.

Parameters

options – a dict of ledger options.

Returns

A tuple of 2 account objects, one for booking current earnings, and one for current conversions.

beancount.parser.options.get_previous_accounts(options)

Return account names for the previous earnings, balances and conversion accounts.

Parameters

options – a dict of ledger options.

Returns

A tuple of 3 account objects, for booking previous earnings, previous balances, and previous conversions.

beancount.parser.options.list_options()

Produce a formatted text of the available options and their description.

Returns

A string, formatted nicely to be printed in 80 columns.

beancount.parser.options.options_validate_booking_method(value)

Validate a booking method name.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.options.options_validate_boolean(value)

Validate a boolean option.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.options.options_validate_plugin(value)

Validate the plugin option.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.options.options_validate_processing_mode(value)

Validate the options processing mode.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.options.options_validate_tolerance(value)

Validate the tolerance option.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.options.options_validate_tolerance_map(value)

Validate an option with a map of currency/tolerance pairs in a string.

Parameters

value – A string, the value provided as option.

Returns

The new value, converted, if the conversion is successful.

Raises

ValueError – If the value is invalid.

beancount.parser.parser

Beancount syntax parser.

IMPORTANT: The parser (and its grammar builder) produces “incomplete” Transaction objects. This means that some of the data can be found missing from the output of the parser and some of the data types vary slightly. Missing components are replaced not by None, but by a special constant ‘NA’ which helps diagnose problems if a user inadvertently attempts to work on an incomplete posting instead of a complete one. Those incomplete entries are then run through the “booking” routines which do two things simultaneously:

  1. They find matching lots for reducing inventory positions, and

  2. They interpolate missing numbers.

In doing so they normalize the entries to “complete” entries by converting a position/lot’s “cost” attribute from a CostSpec to a Cost. A Cost is similar to an Amount in that it shares “number” and “currency” attributes, but also has a label and a lot date. A CostSpec is similar to a Cost, but has all optional data; it consists in a specification for matching against a particular inventory lot.

Other parts of a posting may also be missing, not just parts of the cost. Leaving out some parts of the input is used to invoke interpolation, to tell Beancount to automatically compute the missing numbers (if possible).

Missing components will be set to the special value “beancount.core.number.MISSING” until inventory booking and number interpolation has been completed. The “MISSING” value should never appear in completed, loaded transaction postings.

For instance, all of the units may be missing:

INPUT: Assets:Account posting.units = MISSING

Or just the number of the units:

INPUT: Assets:Account USD posting.units = Amount(MISSING, “USD”)

You must always specify the currency.

If a price annotation is simply absent, it appears as None:

INPUT: Assets:Account 2 MXN posting.price = None

However, you may indicate that there is a price but have Beancount compute it automatically:

INPUT: Assets:Account 2 MXN @ posting.price = Amount(MISSING, MISSING)

Indicating the conversion currency is also possible (and recommended):

INPUT: Assets:Account 2 MXN @ USD posting.price = Amount(MISSING, “USD”)

If a cost specification is provided, a “cost” attribute it set but it does not refer to a Cost instance (as in complete entries) but rather to a CostSpec instance. Some of the fields of a CostSpec may be MISSING if they were not specified in the input. For exammple:

INPUT: Assets:Account 1 HOOL {100 # 5 USD} posting.cost = CostSpec(Decimal(“100”), Decimal(“5”), “USD”, None, None, False))

Note how we never consider the label of date override to be MISSING; this is because those inputs are optional: A missing label is simply left unset in the computed Cost, and a missing date override uses the date of the transaction that contains the posting.

You can indicate that there is a total number to be filled in like this:

INPUT: Assets:Account 1 HOOL {100 # USD} posting.cost = CostSpec(Decimal(“100”), MISSING, “USD”, None, None, False))

This is in contrast to the total value simple not being used:

INPUT: Assets:Account 1 HOOL {100 USD} posting.cost = CostSpec(Decimal(“100”), None, “USD”, None, None, False))

Both per-unit and total numbers may be omitted as well, in which case, only the number-per-unit portion of the CostSpec will appear as MISSING:

INPUT: Assets:Account 1 HOOL {USD} posting.cost = CostSpec(MISSING, None, “USD”, None, None, False))

And furthermore, all the cost basis may be missing:

INPUT: Assets:Account 1 HOOL {} posting.cost = CostSpec(MISSING, None, MISSING, None, None, False))

If you ask for the lots to be merged, you get this:

INPUT: Assets:Account 1 HOOL {*} posting.cost = CostSpec(MISSING, None, MISSING, None, None, True))

The numbers have to be computed by Beancount, so we output this with MISSING values.

Of course, you can provide only the non-basis informations, like just the date or label:

INPUT: Assets:Account 1 HOOL {2015-09-21} posting.cost = CostSpec(MISSING, None, MISSING, date(2015, 9, 21), None, True)

See the test beancount.parser.grammar_test.TestIncompleteInputs for examples and corresponding expected values.

beancount.parser.parser.is_entry_incomplete(entry)

Detect the presence of elided amounts in Transactions.

Parameters

entries – A directive.

Returns

A boolean, true if there are some missing portions of any postings found.

beancount.parser.parser.is_posting_incomplete(posting)

Detect the presence of any elided amounts in a Posting.

If any of the possible amounts are missing, this returns True.

Parameters

entries – A directive.

Returns

A boolean, true if there are some missing portions of any postings found.

beancount.parser.parser.parse_doc(expect_errors=False, allow_incomplete=False)

Factory of decorators that parse the function’s docstring as an argument.

Note that the decorators thus generated only run the parser on the tests, not the loader, so is no validation, balance checks, nor plugins applied to the parsed text.

Parameters
  • expect_errors – A boolean or None, with the following semantics, True: Expect errors and fail if there are none. False: Expect no errors and fail if there are some. None: Do nothing, no check.

  • allow_incomplete – A boolean, if true, allow incomplete input. Otherwise barf if the input would require interpolation. The default value is set not to allow it because we want to minimize the features tests depend on.

Returns

A decorator for test functions.

beancount.parser.parser.parse_file(filename, **kw)

Parse a beancount input file and return Ledger with the list of transactions and tree of accounts.

Parameters
  • filename – the name of the file to be parsed.

  • kw – a dict of keywords to be applied to the C parser.

Returns

A tuple of (

list of entries parsed in the file, list of errors that were encountered during parsing, and a dict of the option values that were parsed from the file.)

beancount.parser.parser.parse_many(string, level=0)

Parse a string with a snippet of Beancount input and replace vars from caller.

Parameters
  • string – A string with some Beancount input.

  • level – The number of extra stacks to ignore.

Returns

A list of entries.

Raises

AssertionError – If there are any errors.

beancount.parser.parser.parse_one(string)

Parse a string with single Beancount directive and replace vars from caller.

Parameters
  • string – A string with some Beancount input.

  • level – The number of extra stacks to ignore.

Returns

A list of entries.

Raises

AssertionError – If there are any errors.

beancount.parser.parser.parse_string(string, report_filename=None, **kw)

Parse a beancount input file and return Ledger with the list of transactions and tree of accounts.

Parameters
  • string – A string, the contents to be parsed instead of a file’s.

  • report_filename – A string, the source filename from which this string has been extracted, if any. This is stored in the metadata of the parsed entries.

  • **kw – See parse.c. This function parses out ‘dedent’ which removes whitespace from the front of the text (default is False).

Returns

Same as the output of parse_file().

beancount.parser.printer

Conversion from internal data structures to text.

class beancount.parser.printer.EntryPrinter(dcontext=None, render_weight=False, min_width_account=None)

A multi-method interface for printing all directive types.

Atributes:

dcontext: An instance of DisplayContext with which to render all the numbers. render_weight: A boolean, true if we should render the weight of the postings

as a comment, for debugging.

min_width_account: An integer, the minimum width to leave for the account name.

Balance(entry, oss)
Close(entry, oss)
Commodity(entry, oss)
Custom(entry, oss)
Document(entry, oss)
Event(entry, oss)
META_IGNORE = {'__automatic__', 'filename', 'lineno'}
Note(entry, oss)
Open(entry, oss)
Pad(entry, oss)
Posting(posting, oss)
Price(entry, oss)
Query(entry, oss)
Transaction(entry, oss)
render_posting_strings(posting)

This renders the three components of a posting: the account and its optional posting flag, the position, and finally, the weight of the position. The purpose is to align these in the caller.

Parameters

posting – An instance of Posting, the posting to render.

Returns

A tuple of

flag_account: A string, the account name including the flag. position_str: A string, the rendered position string. weight_str: A string, the rendered weight of the posting.

write_metadata(meta, oss, prefix=' ')

Write metadata to the file object, excluding filename and line number.

Parameters
  • meta – A dict that contains the metadata for this directive.

  • oss – A file object to write to.

beancount.parser.printer.align_position_strings(strings)

A helper used to align rendered amounts positions to their first currency character (an uppercase letter). This class accepts a list of rendered positions and calculates the necessary width to render them stacked in a column so that the first currency word aligns. It does not go beyond that (further currencies, e.g. for the price or cost, are not aligned).

This is perhaps best explained with an example. The following positions will be aligned around the column marked with ‘^’:

45 HOOL {504.30 USD}

4 HOOL {504.30 USD, 2014-11-11}

9.95 USD

-22473.32 CAD @ 1.10 USD

^

Strings without a currency character will be rendered flush left.

Parameters

strings – A list of rendered position or amount strings.

Returns

A pair of a list of aligned strings and the width of the aligned strings.

beancount.parser.printer.format_entry(entry, dcontext=None, render_weights=False)

Format an entry into a string in the same input syntax the parser accepts.

Parameters
  • entry – An entry instance.

  • dcontext – An instance of DisplayContext used to format the numbers.

  • render_weights – A boolean, true to render the weights for debugging.

Returns

A string, the formatted entry.

beancount.parser.printer.format_error(error)

Given an error objects, return a formatted string for it.

Parameters

error – a namedtuple objects representing an error. It has to have an ‘entry’ attribute that may be either a single directive object or a list of directive objects.

Returns

A string, the errors rendered.

beancount.parser.printer.print_entries(entries, dcontext=None, render_weights=False, file=None, prefix=None)

A convenience function that prints a list of entries to a file.

Parameters
  • entries – A list of directives.

  • dcontext – An instance of DisplayContext used to format the numbers.

  • render_weights – A boolean, true to render the weights for debugging.

  • file – An optional file object to write the entries to.

beancount.parser.printer.print_entry(entry, dcontext=None, render_weights=False, file=None)

A convenience function that prints a single entry to a file.

Parameters
  • entry – A directive entry.

  • dcontext – An instance of DisplayContext used to format the numbers.

  • render_weights – A boolean, true to render the weights for debugging.

  • file – An optional file object to write the entries to.

beancount.parser.printer.print_error(error, file=None)

A convenience function that prints a single error to a file.

Parameters
  • error – An error object.

  • file – An optional file object to write the errors to.

beancount.parser.printer.print_errors(errors, file=None, prefix=None)

A convenience function that prints a list of errors to a file.

Parameters
  • errors – A list of errors.

  • file – An optional file object to write the errors to.

beancount.parser.printer.render_source(meta)

Render the source for errors in a way that it will be both detected by Emacs and align and rendered nicely.

Parameters

meta – A dict with the metadata.

Returns

A string, rendered to be interpretable as a message location for Emacs or other editors.