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: list[DateAndBalance]
label: str
type: Literal['balances'] = 'balances'
class fava.internal_api.BarChart(label, data, type='bar')

Data for a bar chart.

data: list[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: list[str]
base_url: str
currencies: list[str]
currency_names: dict[str, str]
errors: list[SerialisedError]
extensions: list[ExtensionDetails]
fava_options: FavaOptions
have_excel: bool
incognito: bool
options: dict[str, str | list[str]]
other_ledgers: list[tuple[str, str]]
payees: list[str]
precisions: dict[str, int]
tags: list[str]
upcoming_events_count: int
user_queries: list[Query]
years: list[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: dict[str, Decimal]
budget_children: dict[str, Decimal]
class fava.json_api.AccountReportJournal(charts, journal)

Data for the journal account report.

charts: list[BalancesChart | BarChart | HierarchyChart]
journal: str
class fava.json_api.AccountReportTree(charts, interval_balances, budgets, dates)

Data for the tree account reports.

budgets: dict[str, list[AccountBudget]]
charts: list[BalancesChart | BarChart | HierarchyChart]
dates: list[DateRange]
interval_balances: list[SerialisedTreeNode]
class fava.json_api.CommodityPairWithPrices(base, quote, prices)

A pair of commodities and prices for them.

base: str
prices: list[tuple[date, Decimal]]
quote: str
class fava.json_api.Context(entry, balances_before, balances_after, sha256sum, slice)

Context for an entry.

balances_after: dict[str, list[str]] | None
balances_before: dict[str, list[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
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: list[BalancesChart | BarChart | HierarchyChart]
date_range: DateRange | None
trees: list[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)

Register an API endpoint.

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:

list[CommodityPairWithPrices]

fava.json_api.get_context(entry_hash)

Entry context.

Return type:

Context

fava.json_api.get_documents()

Get all (filtered) documents.

Return type:

list[Document]

fava.json_api.get_events()

Get all (filtered) events.

Return type:

list[Event]

fava.json_api.get_extract(filename, importer)

Extract entries using the ingest framework.

Return type:

list[Any]

fava.json_api.get_imports()

Get a list of the importable files.

Return type:

list[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_payee_accounts(payee)

Rank accounts for the given payee.

Return type:

list[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:

dict[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