fava¶

Fava - A web interface for Beancount.

fava._ctx_globals_class¶

Specify types for the flask application context.

class fava._ctx_globals_class.Context¶

The context values - this is used for flask.g.

beancount_file_slug: str | None¶: Slug for the active Beancount file.

property conv: Conversion¶: Conversion to apply (parsed).

property conversion: str¶: Conversion to apply (raw string).

extension: FavaExtensionBase | None¶: The current extension, if this is an extension endpoint

property filtered: FilteredLedger¶: The filtered ledger.

property interval: Interval¶: Interval to group by.

ledger: FavaLedger¶: The ledger

fava.application¶

Fava’s main WSGI application.

you can use create_app to create a Fava WSGI app for a given list of files. To start a simple server:

from fava.application import create_app

app = create_app(['/path/to/file.beancount'])
app.run('localhost', 5000)

fava.application.app(environ, start_response) = <Flask 'fava'>¶: This is still provided for compatibility but will be removed at some point.

fava.application.create_app(files, *, load=False, incognito=False, read_only=False, poll_watcher=False)¶

Create a Fava Flask application.

Parameters:

files (Iterable[Path | str]) – The list of Beancount files (paths).
load (bool) – Whether to load the Beancount files directly.
incognito (bool) – Whether to run in incognito mode.
read_only (bool) – Whether to run in read-only mode.
poll_watcher (bool) – Whether to use old poll watcher

Return type:

Flask

fava.application.static_url(filename)¶

Return a static url with an mtime query string for cache busting.

Return type:: str

fava.application.translations()¶

Get translations catalog.

Return type:: dict[str, str]

fava.application.url_for(endpoint, **values)¶

Wrap flask.url_for using a cache.

Return type:: str

fava.cli¶

The command-line interface for Fava.

exception fava.cli.AddressInUse(port)¶

exception fava.cli.NoFileSpecifiedError¶

exception fava.cli.NonAbsolutePathError(path)¶

fava.context¶

Specify types for the flask application context.

fava.helpers¶

Exceptions and module base class.

class fava.helpers.BeancountError(source: Meta | None, message: str, entry: Directive | None)¶: NamedTuple base for a Beancount-style error.

exception fava.helpers.FavaAPIError(message)¶: Fava’s base exception class.

fava.internal_api¶

Internal API.

This is used to pre-process some data that is used in the templates, allowing this part of the functionality to be tested and allowing some end-to-end tests for the frontend data validation.

class fava.internal_api.BalancesChart(label, data, type='balances')¶

Data for a balances chart.

data: Sequence[DateAndBalance]¶

label: str¶

type: Literal['balances'] = 'balances'¶

class fava.internal_api.BarChart(label, data, type='bar')¶

Data for a bar chart.

data: Sequence[DateAndBalanceWithBudget]¶

label: str¶

type: Literal['bar'] = 'bar'¶

class fava.internal_api.ChartApi¶

Functions to generate chart data.

static account_balance(account_name)¶

Generate data for an account balances chart.

Return type:: BalancesChart | BarChart | HierarchyChart

static hierarchy(account_name, begin_date=None, end_date=None, label=None)¶

Generate data for an account hierarchy chart.

Return type:: BalancesChart | BarChart | HierarchyChart

static interval_totals(interval, account_name, label=None, *, invert=False)¶

Generate data for an account per interval chart.

Return type:: BalancesChart | BarChart | HierarchyChart

static net_worth()¶

Generate data for net worth chart.

Return type:: BalancesChart | BarChart | HierarchyChart

class fava.internal_api.HierarchyChart(label, data, type='hierarchy')¶

Data for a hierarchy chart.

data: SerialisedTreeNode¶

label: str¶

type: Literal['hierarchy'] = 'hierarchy'¶

class fava.internal_api.LedgerData(accounts, account_details, base_url, currencies, currency_names, errors, fava_options, incognito, have_excel, links, options, payees, precisions, tags, years, user_queries, upcoming_events_count, extensions, sidebar_links, other_ledgers)¶

This is used as report-independent data in the frontend.

account_details: AccountDict¶

accounts: Sequence[str]¶

base_url: str¶

currencies: Sequence[str]¶

currency_names: dict[str, str]¶

errors: Sequence[SerialisedError]¶

extensions: Sequence[ExtensionDetails]¶

fava_options: FavaOptions¶

have_excel: bool¶

incognito: bool¶

links: Sequence[str]¶

options: dict[str, str | Sequence[str]]¶

other_ledgers: Sequence[tuple[str, str]]¶

payees: Sequence[str]¶

precisions: dict[str, int]¶

sidebar_links: Sequence[tuple[str, str]]¶

tags: Sequence[str]¶

upcoming_events_count: int¶

user_queries: Sequence[Query]¶

years: Sequence[str]¶

class fava.internal_api.SerialisedError(type, source, message)¶

A Beancount error, as passed to the frontend.

static from_beancount_error(err)¶

Get a serialisable error from a Beancount error.

Return type:: SerialisedError

message: str¶

source: Mapping[str, str | int | bool | Decimal | date | Amount] | None¶

type: str¶

fava.internal_api.get_errors()¶

Serialise errors (do not pass entry as that might fail serialisation.

Return type:: list[SerialisedError]

fava.internal_api.get_ledger_data()¶

Get the report-independent ledger data.

Return type:: LedgerData

fava.json_api¶

JSON API.

This module contains the url endpoints of the JSON API that is used by the web interface for asynchronous functionality.

class fava.json_api.AccountBudget(budget, budget_children)¶

Budgets for an account.

budget: Mapping[str, Decimal]¶

budget_children: Mapping[str, Decimal]¶

class fava.json_api.AccountReportJournal(charts, journal)¶

Data for the journal account report.

charts: Sequence[BalancesChart | BarChart | HierarchyChart]¶

journal: str¶

class fava.json_api.AccountReportTree(charts, interval_balances, budgets, dates)¶

Data for the tree account reports.

budgets: Mapping[str, Sequence[AccountBudget]]¶

charts: Sequence[BalancesChart | BarChart | HierarchyChart]¶

dates: Sequence[DateRange]¶

interval_balances: Sequence[SerialisedTreeNode]¶

class fava.json_api.CommodityPairWithPrices(base, quote, prices)¶

A pair of commodities and prices for them.

base: str¶

prices: Sequence[tuple[date, Decimal]]¶

quote: str¶

class fava.json_api.Context(entry, balances_before, balances_after, sha256sum, slice)¶

Context for an entry.

balances_after: Mapping[str, Sequence[str]] | None¶

balances_before: Mapping[str, Sequence[str]] | None¶

entry: Any¶

sha256sum: str¶

slice: str¶

exception fava.json_api.DocumentDirectoryMissingError¶

No document directory was specified.

status = 422¶

exception fava.json_api.FavaJSONAPIError(message)¶

An error with a HTTPStatus.

abstract property status: HTTPStatus¶: HTTP status that should be used for the response.

exception fava.json_api.FileDoesNotExistError(filename)¶: The given file does not exist.

exception fava.json_api.IncorrectTypeValidationError(param, expected)¶: Validation failed due to incorrect type of parameter.

exception fava.json_api.MissingParameterValidationError(param)¶: Validation failed due to missing parameter.

exception fava.json_api.NoFileUploadedError¶

No file uploaded.

status = 400¶

exception fava.json_api.NotAFileError(filename)¶

Not a file.

status = 422¶

exception fava.json_api.NotAValidDocumentOrImportFileError(filename)¶

Not valid document or import file.

status = 400¶

class fava.json_api.Options(fava_options, beancount_options)¶

Fava and Beancount options as strings.

beancount_options: Mapping[str, str]¶

fava_options: Mapping[str, str]¶

exception fava.json_api.TargetPathAlreadyExistsError(path)¶

The given path already exists.

status = 409¶

class fava.json_api.TreeReport(date_range, charts, trees)¶

Data for the tree reports.

charts: Sequence[BalancesChart | BarChart | HierarchyChart]¶

date_range: DateRange | None¶

trees: Sequence[SerialisedTreeNode]¶

exception fava.json_api.UploadedFileIsMissingFilenameError¶

Uploaded file is missing filename.

status = 400¶

exception fava.json_api.ValidationError¶: Validation of data failed.

fava.json_api.api_endpoint(func)¶

The part of the function name up to the first underscore determines the accepted HTTP method. For GET and DELETE endpoints, the function parameters are extracted from the URL query string and passed to the decorated endpoint handler.

Return type:: Callable[[], Response]

fava.json_api.delete_document(filename)¶

Delete a document.

Return type:: str

fava.json_api.delete_source_slice(entry_hash, sha256sum)¶

Delete an entry source slice.

Return type:: str

fava.json_api.get_account_report()¶

Get the data for the account report.

Return type:: AccountReportJournal | AccountReportTree

fava.json_api.get_balance_sheet()¶

Get the data for the balance sheet.

Return type:: TreeReport

fava.json_api.get_changed()¶

Check for file changes.

Return type:: bool

fava.json_api.get_commodities()¶

Get the prices for all commodity pairs.

Return type:: Sequence[CommodityPairWithPrices]

fava.json_api.get_context(entry_hash)¶

Entry context.

Return type:: Context

fava.json_api.get_documents()¶

Get all (filtered) documents.

Return type:: Sequence[Document]

fava.json_api.get_events()¶

Get all (filtered) events.

Return type:: Sequence[Event]

fava.json_api.get_extract(filename, importer)¶

Extract entries using the ingest framework.

Return type:: Sequence[Any]

fava.json_api.get_imports()¶

Get a list of the importable files.

Return type:: Sequence[FileImporters]

fava.json_api.get_income_statement()¶

Get the data for the income statement.

Return type:: TreeReport

fava.json_api.get_move(account, new_name, filename)¶

Move a file.

Return type:: str

fava.json_api.get_options()¶

Get all options, rendered to strings for displaying in the frontend.

Return type:: Options

fava.json_api.get_payee_accounts(payee)¶

Rank accounts for the given payee.

Return type:: Sequence[str]

fava.json_api.get_payee_transaction(payee)¶

Last transaction for the given payee.

Return type:: Any

fava.json_api.get_query(query_string)¶

Run a Beancount query.

Return type:: QueryResultTable | QueryResultText

fava.json_api.get_source(filename)¶

Load one of the source files.

Return type:: Mapping[str, str]

fava.json_api.get_trial_balance()¶

Get the data for the trial balance.

Return type:: TreeReport

fava.json_api.json_err(msg, status)¶

Jsonify the error message.

Return type:: Response

fava.json_api.json_success(data)¶

Jsonify the response.

Return type:: Response

fava.json_api.put_add_document()¶

Upload a document.

Return type:: str

fava.json_api.put_add_entries(entries)¶

Add multiple entries.

Return type:: str

fava.json_api.put_attach_document(filename, entry_hash)¶

Attach a document to an entry.

Return type:: str

fava.json_api.put_format_source(source)¶

Format beancount file.

Return type:: str

fava.json_api.put_source(file_path, source, sha256sum)¶

Write one of the source files and return the updated sha256sum.

Return type:: str

fava.json_api.put_source_slice(entry_hash, source, sha256sum)¶

Write an entry source slice and return the updated sha256sum.

Return type:: str

fava.json_api.put_upload_import_file()¶

Upload a file for importing.

Return type:: str

fava.json_api.validate_func_arguments(func)¶

Validate arguments for a function.

This currently only works for strings and lists (but only does a shallow validation for lists).

Parameters:: func (Callable[..., Any]) – The function to check parameters for.
Returns:: Optional[Callable[[Mapping[str, str]], list[str]]] – A function, which takes a Mapping and tries to construct a list of positional parameters for the given function or None if the function has no parameters.

fava.serialisation¶

(De)serialisation of entries.

When adding entries, these are saved via the JSON API - using the functionality of this module to obtain the appropriate data structures from beancount.core.data. Similarly, for the full entry completion, a JSON representation of the entry is provided.

This is not intended to work well enough for full roundtrips yet.

exception fava.serialisation.InvalidAmountError(amount)¶: Invalid amount.

fava.serialisation.deserialise(json_entry)¶

Parse JSON to a Beancount entry.

Parameters:

json_entry (Any) – The entry.

Raises:

KeyError – if one of the required entry fields is missing.
FavaAPIError – if the type of the given entry is not supported.

Return type:

Directive

fava.serialisation.deserialise_posting(posting)¶

Parse JSON to a Beancount Posting.

Return type:: Posting

fava.serialisation.serialise(entry)¶

Serialise an entry or posting.

Return type:: Any

fava.template_filters¶

Template filters for Fava.

All functions in this module will be automatically added as template filters.

fava.template_filters.basename(file_path)¶

Return the basename of a filepath.

Return type:: str

fava.template_filters.flag_to_type(flag)¶

Names for entry flags.

Return type:: str

fava.template_filters.format_currency(value, currency=None, *, show_if_zero=False)¶

Format a value using the derived precision for a specified currency.

Return type:: str

fava.template_filters.meta_items(meta)¶

Remove keys from a dictionary.

Return type:: list[tuple[str, str | int | bool | Decimal | date | Amount]]

fava.template_filters.passthrough_numbers(value)¶

Pass through value unchanged.

Return type:: TypeVar(T)

fava.template_filters.replace_numbers(value)¶

Replace numbers, to be used in incognito mode.

Return type:: str | None