beancount

Beancount, a double-entry bookkeeping software.

This is v2, a complete rewrite of Beancount v1, simplified and improved drastically.

beancount.loader

Loader code. This is the main entry point to load up a file.

class beancount.loader.LoadError(source, message, entry)
beancount.loader.aggregate_options_map(options_map, src_options_map)

Aggregate some of the attributes of options map.

Parameters
  • options_map – The target map in which we want to aggregate attributes. Note: This value is mutated in-place.

  • src_options_map – A source map whose values we’d like to see aggregated.

beancount.loader.combine_plugins(*plugin_modules)

Combine the plugins from the given plugin modules.

This is used to create plugins of plugins. :param *plugins_modules: A sequence of module objects.

Returns

A list that can be assigned to the new module’s __plugins__ attribute.

beancount.loader.compute_input_hash(filenames)

Compute a hash of the input data.

Parameters

filenames – A list of input files. Order is not relevant.

beancount.loader.initialize()

Initialize the loader.

beancount.loader.load_doc(expect_errors=False)

A factory of decorators that loads the docstring and calls the function with entries.

This is an incredibly convenient tool to write lots of tests. Write a unittest using the standard TestCase class and put the input entries in the function’s docstring.

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.

Returns

A wrapped method that accepts a single ‘self’ argument.

beancount.loader.load_encrypted_file(filename, log_timings=None, log_errors=None, extra_validations=None, dedent=False, encoding=None)

Load an encrypted Beancount input file.

Parameters
  • filename – The name of an encrypted file to be parsed.

  • log_timings – See load_string().

  • log_errors – See load_string().

  • extra_validations – See load_string().

  • dedent – See load_string().

  • encoding – See load_string().

Returns

A triple of (entries, errors, option_map) where “entries” is a date-sorted list of entries from the file, “errors” a list of error objects generated while parsing and validating the file, and “options_map”, a dict of the options parsed from the file.

beancount.loader.load_file(filename, log_timings=None, log_errors=None, extra_validations=None, encoding=None)

Open a Beancount input file, parse it, run transformations and validate.

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

  • log_timings – A file object or function to write timings to, or None, if it should remain quiet.

  • log_errors – A file object or function to write errors to, or None, if it should remain quiet.

  • extra_validations – A list of extra validation functions to run after loading this list of entries.

  • encoding – A string or None, the encoding to decode the input filename with.

Returns

A triple of (entries, errors, option_map) where “entries” is a date-sorted list of entries from the file, “errors” a list of error objects generated while parsing and validating the file, and “options_map”, a dict of the options parsed from the file.

beancount.loader.load_string(string, log_timings=None, log_errors=None, extra_validations=None, dedent=False, encoding=None)

Open a Beancount input string, parse it, run transformations and validate.

Parameters
  • string – A Beancount input string.

  • log_timings – A file object or function to write timings to, or None, if it should remain quiet.

  • log_errors – A file object or function to write errors to, or None, if it should remain quiet.

  • extra_validations – A list of extra validation functions to run after loading this list of entries.

  • dedent – A boolean, if set, remove the whitespace in front of the lines.

  • encoding – A string or None, the encoding to decode the input string with.

Returns

A triple of (entries, errors, option_map) where “entries” is a date-sorted list of entries from the string, “errors” a list of error objects generated while parsing and validating the string, and “options_map”, a dict of the options parsed from the string.

beancount.loader.needs_refresh(options_map)

Predicate that returns true if at least one of the input files may have changed.

Parameters
  • options_map – An options dict as per the parser.

  • mtime – A modified time, to check if it covers the include files in the options_map.

Returns

A boolean, true if the input is obsoleted by changes in the input files.

beancount.loader.pickle_cache_function(pattern, time_threshold, function)

Decorate a loader function to make it loads its result from a pickle cache.

This considers the first argument as a top-level filename and assumes the function to be cached returns an (entries, errors, options_map) triple. We use the ‘include’ option value in order to check whether any of the included files has changed. It’s essentially a special case for an on-disk memoizer. If any of the included files are more recent than the cache, the function is recomputed and the cache refreshed.

Parameters
  • pattern – A string, the filename pattern for the pickled cache file. A {filename} in it gets replaced by the basename of the input filename.

  • time_threshold – A float, the number of seconds below which we don’t bother caching.

  • function – A function object to decorate for caching.

Returns

A decorated function which will pull its result from a cache file if it is available.

beancount.loader.run_transformations(entries, parse_errors, options_map, log_timings)

Run the various transformations on the entries.

This is where entries are being synthesized, checked, plugins are run, etc.

Parameters
  • entries – A list of directives as read from the parser.

  • parse_errors – A list of errors so far.

  • options_map – An options dict as read from the parser.

  • log_timings – A function to write timing log entries to, or None, if it should be quiet.

Returns

A list of modified entries, and a list of errors, also possibly modified.