beancount.web

Web server reporting front-end.

beancount.web.bottle_utils

Bottle utilities, mostly helpers to do mounts on top of dynamic routes.

class beancount.web.bottle_utils.AttrMapper(mapper_function)

A URL mapper that allows attribute access for view-links. This is used in templates.

build(*args, **kwargs)
beancount.web.bottle_utils.internal_redirect(app, path_depth)

A version of bottle’s mountpoint_wrapper() that we call explicitly.

Bottle supports a mount() method that allows on to install an application on a subpath of the main application. However, it does this on a fixed path. We want to manually intercept the lazy creation or fetching of a view and call for a redirect explicitly (via bottle’s mountpoint_wrapper() function). However, this function is hidden within the scope of a the Bottle.mount() method; if it were defined globally we would just use it, but it is not. So we copy if here. This is directly lifted from Bottle.mount() and edited minimally.

Parameters
  • app – A Bottle instance.

  • path_depth – The number of request path components to skip for the mount. For example, if our subapplication is mount on /view/all, then the path depth is 2.

Returns

A Bottle HTTPResponse objet.

Raises

Exception – Any exception, depending on the callback.

beancount.web.scrape

Find links targets in HTML text.

This deals with both absolute and relative links, and it external links to external sites.

Parameters
  • html – An lxml document node.

  • html_path – The URL of the document node.

Yields

URL strings, where found.

beancount.web.scrape.scrape_urls(url_format, callback, ignore_regexp=None)

Recursively scrape pages from a web address.

Parameters
  • url_format – The pattern for building links from relative paths.

  • callback – A callback function to invoke on each page to validate it. The function is called with the response and the url as arguments. This function should trigger an error on failure (via an exception).

  • ignore_regexp – A regular expression string, the urls to ignore.

Returns

A set of all the processed URLs and a set of all the skipped URLs.

Open and parse the given HTML filename and verify all local targets exist.

This checks that all the files pointed to by the file we’re processing are files that exist on disk. This can be used to validate that a baked output does not have links to files that do not exist, that all the links are valid.

Parameters

filename – A string, the name of the HTML file to process.

Returns

missing: A set of strings, the names of links to files that do not exist. empty: A boolean, true if this file is empty.

Return type

A pair of

Find all the files under the given directory and validate all their links.

Parameters

directory – A string, the root directory whose files to process.

Returns

files: A list of all the filenames found and processed. missing: A set of strings, the names of links to files that do not exist. empty: A boolean, true if this file is empty.

Return type

A tuple of

beancount.web.views

Views are filters on the global list of entries, which produces a subset of entries.

class beancount.web.views.AllView(all_entries, options_map, title)

A view that includes all the entries, unmodified.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.ComponentView(entries, options_map, title, component)

A view that includes transactions with at least one posting with an account that includes a given component.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.EmptyView(entries, options_map, title, *args, **kw)

An empty view, for testing.

apply_filter(_, __)

Return the list of entries unmodified.

class beancount.web.views.MonthNavigation

An enumeration.

COMPACT = 1
FULL = 2
NONE = 0
class beancount.web.views.MonthView(entries, options_map, title, year, month)

A view of the entries for a single month.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.PayeeView(entries, options_map, title, payee)

A view that includes entries with some specific payee.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.TagView(entries, options_map, title, tags)

A view that includes only entries some specific tags.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.View(all_entries, options_map, title)

A container for filtering a subset of entries and realizing that for display.

apply_filter(entries)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

class beancount.web.views.YearView(entries, options_map, title, year, first_month=1)

A view of the entries for a single year.

apply_filter(entries, options_map)

Filter the list of entries.

This is used to obtain the filtered list of entries.

Parameters

entries – A list of directives to filter.

Returns

A pair of
  1. a list of filtered entries, and

  2. an integer, the index at which the beginning of the entries for

the period begin, one directive past the opening balances/initialization entries.

  1. a datetime.date instance, the date at which to evaluate the value

of assets held at cost.

beancount.web.web

Web server for Beancount ledgers. This uses the Bottle single-file micro web framework (with no plugins).

class beancount.web.web.HTMLFormatter(dcontext, build_url, leaf_only, account_xform, view_links=True)

A formatter object that can be used to render accounts links.

build_url

A function used to render links to a Bottle application.

leafonly

a boolean, if true, render only the name of the leaf nodes.

EMS_PER_COMPONENT = 1.5
build_global(*args, **kwds)

Render to global application.

render_account(account_name)

See base class.

render_commodity(base_quote)

See base class.

render_context(entry)

See base class.

render_doc(filename)

See base class.

render_event_type(event)

See base class.

render_inventory(inv)

Override this formatter to convert the inventory to units only.

See base class.

render_source(source)

See base class.

beancount.web.web.activity()

Render the update activity.

beancount.web.web.add_web_arguments(argparser)
beancount.web.web.all(*args, **kwargs)
beancount.web.web.approot()
beancount.web.web.auto_reload_input_file(callback)

A plugin that automatically reloads the input file if it changed since the last page was loaded.

beancount.web.web.balsheet()

Balance sheet.

beancount.web.web.commodities()

Render a list commodities with list their prices page.

beancount.web.web.component(*args, **kwargs)
beancount.web.web.context_(ehash=None)

Render the before & after context around a transaction entry.

beancount.web.web.conversions_()

Render the list of transactions with conversions.

beancount.web.web.doc(filename=None)

Serve static filenames for documents directives.

beancount.web.web.doc__view(filename=None)
beancount.web.web.documents()

Render a tree with all the documents found.

beancount.web.web.errors()

Report error encountered during parsing, checking and realization.

beancount.web.web.event(event=None)

Render all values of a particular event.

beancount.web.web.event_index()

Render the latest values of all events and an index.

beancount.web.web.favicon()
beancount.web.web.get_all_view(app)

Return a view of all transactions.

Returns

An instance of AllView, that covers all transactions.

beancount.web.web.handle_view(path_depth)

A decorator for handlers which create views lazily. If you decorate a method with this, the wrapper does the redirect handling and your method is just a factory for a View instance, which is cached.

Parameters

path_depth – An integer, the number of components that form the view id.

Returns

A decorator function, used to wrap view handlers.

beancount.web.web.holdings_()

Render a detailed table of all holdings.

beancount.web.web.holdings_byaccount()

Render a table of holdings by account.

beancount.web.web.holdings_bycommodity()

Render a table of holdings by commodity.

beancount.web.web.holdings_bycurrency()

Render a table of holdings by currency.

beancount.web.web.holdings_byrootaccount()

Render a table of holdings by account.

beancount.web.web.incognito(callback)

A plugin that converts all numbers rendered into X’s, in order to hide the actual values in the ledger. This is used for doing public demos using my real ledger, where I don’t necessarily want to share the detail of my financial life with the viewers but when I still want an interesting ledger, with enough detail that looks realistic.

beancount.web.web.income()

Income statement.

beancount.web.web.index()

Index of all pages, so that navigation need not have all links.

beancount.web.web.journal_(account_name=None)

A list of all the entries for this account realization.

beancount.web.web.journal_all()

A list of all the entries in this realization.

Serve journals for links.

beancount.web.web.main()

Main web service runner. This runs the event loop and blocks indefinitely.

beancount.web.web.month(*args, **kwargs)
beancount.web.web.month_request(year, month)

Render a URL to a particular month of the context’s request.

beancount.web.web.networth()

Render a table of the net worth for this filter.

beancount.web.web.openbal()

Opening balances.

beancount.web.web.payee(*args, **kwargs)
beancount.web.web.populate_view(callback)

A plugin that will populate the request with the current view instance.

Parameters

callback – A continuation function to call to handle the request.

Returns

A function to call to install view-specific parameters on the request.

beancount.web.web.prices_values(base=None, quote=None)

Render all the values for a particular price pair.

beancount.web.web.render_global(*args, **kw)

Render the title and contents in our standard template for a global page.

Parameters
  • *args – A tuple of values for the HTML template.

  • *kw – A dict of optional values for the HTML template.

Returns

An HTML string of the rendered template.

beancount.web.web.render_overlay(contents)

Render an overlay of the navigation with the current errors.

This is used to bring up new errors on any page when they occur.

Returns

A string of HTML for the contents of the errors overlay.

beancount.web.web.render_real_report(report_class, real_root, price_map, price_date, args=None, leaf_only=False)

Instantiate a report and rendering it to a string.

This is intended to be called in the context of a Bottle view app request (it uses ‘request’).

Parameters
  • report_class – A class, the type of the report to render.

  • real_root – An instance of RealAccount to render.

  • price_map – A price map as built by build_price_map().

  • price_date – The date at which to evaluate the prices.

  • args – A list of strings, the arguments to initialize the report with.

  • leaf_only – A boolean, whether to render the leaf names only.

Returns

A string, the rendered report.

beancount.web.web.render_report(report_class, entries, args=None, css_id=None, css_class=None, center=False, leaf_only=True)

Instantiate a report and rendering it to a string.

Parameters
  • report_class – A class, the type of the report to render.

  • real_root – An instance of RealAccount to render.

  • args – A list of strings, the arguments to initialize the report with.

  • css_id – An optional string, the CSS id for the div to render.

  • css_class – An optional string, the CSS class for the div to render.

  • center – A boolean flag, if true, wrap the results in a <center> tag.

  • leaf_only – A boolean, whether to render the leaf names only.

Returns

A string, the rendered report.

beancount.web.web.render_view(*args, **kw)

Render the title and contents in our standard template for a view page.

Parameters
  • *args – A tuple of values for the HTML template.

  • *kw – A dict of optional values for the HTML template.

Returns

An HTML string of the rendered template.

beancount.web.web.root()

Redirect the root page to the home page.

beancount.web.web.run_app(args, quiet=None)
beancount.web.web.scrape_webapp(filename, callback, port, ignore_regexp, quiet=True, no_colons=False, extra_args=None)

Run a web server on a Beancount file and scrape it.

This is the main entry point of this module.

Parameters
  • filename – A string, the name of the file to parse.

  • callback – A callback function to invoke on each page to validate it. The function is called with the response and the url as arguments. This function should trigger an error on failure (via an exception).

  • port – An integer, a free port to use for serving the pages.

  • ignore_regexp – A regular expression string, the urls to ignore.

  • quiet – True if we shouldn’t log the web server pages.

  • no_colons – True if we should avoid rendering colons in URLs (for Windows).

  • extra_args – Extra arguments to bean-web that we want to start the server with.

Returns

A set of all the processed URLs and a set of all the skipped URLs.

beancount.web.web.setup_monkey_patch_for_server_shutdown()

Setup globals to steal access to the server reference. This is required to initiate shutdown, unfortunately. (Bottle could easily remedy that.)

beancount.web.web.shutdown()

Request for the server to shutdown.

beancount.web.web.source()

Render the source file, allowing scrolling at a specific line.

beancount.web.web.stats_postings()

Compute and render statistics about the input file.

beancount.web.web.stats_types()

Compute and render statistics about the input file.

beancount.web.web.style()

Stylesheet for the entire document.

beancount.web.web.tag(*args, **kwargs)
beancount.web.web.third_party(filename=None)
beancount.web.web.thread_server_shutdown(thread)

Shutdown the server running in the given thread.

Unfortauntely, in the meantime this has a side-effect on all servers. This returns after waiting that the thread has stopped.

Parameters

thread – A threading.Thread instance.

beancount.web.web.thread_server_start(web_args, **kwargs)

Start a server in a new thread.

Parameters

argparse_args – An argparse parsed options object, with all the options from add_web_arguments().

Returns

A new Thread instance.

beancount.web.web.toc()
beancount.web.web.trial()

Trial balance / Chart of Accounts.

beancount.web.web.url_restrict_generator(url_prefix)

Restrict to only a single prefix.

Parameters
  • url_prefix – A string, a URL prefix to restrict to.

  • callback – The function to wrap.

Returns

A handler decorator.

beancount.web.web.wait_ready()

Wait until the ‘server’ global has been set. This tells us the server is running.

beancount.web.web.year(*args, **kwargs)