fava.beans

Types, functions and wrappers to deal with Beancount types.

fava.beans.abc

Abstract base classes for Beancount types.

class fava.beans.abc.Amount

An amount in some currency.

abstract property currency: str

Currency of the amount.

abstract property number: Decimal

Number of units in the amount.

class fava.beans.abc.Balance

A Beancount Balance directive.

abstract property account: str

Account of the directive.

abstract property diff_amount: Amount | None

Account of the directive.

class fava.beans.abc.Close

A Beancount Close directive.

abstract property account: str

Account of the directive.

class fava.beans.abc.Commodity

A Beancount Commodity directive.

abstract property currency: str

Currency.

class fava.beans.abc.Cost

A cost (basically an amount with date and label).

abstract property currency: str

Currency of the cost.

abstract property date: date

Date of the cost.

abstract property label: str | None

Label of the cost.

abstract property number: Decimal

Number of units in the cost.

class fava.beans.abc.Custom

A Beancount Custom directive.

abstract property type: str

Directive type.

abstract property values: Sequence[Any]

Custom values.

class fava.beans.abc.Directive

A Beancount directive.

abstract property date: date

Metadata of the directive.

abstract property meta: Mapping[str, str | int | bool | Decimal | date | Amount]

Metadata of the directive.

class fava.beans.abc.Document

A Beancount Document directive.

abstract property account: str

Account of the directive.

abstract property filename: str

Filename of the document.

Entry links.

abstract property tags: set[str] | frozenset[str]

Entry tags.

class fava.beans.abc.Event

A Beancount Event directive.

abstract property account: str

Account of the directive.

class fava.beans.abc.Note

A Beancount Note directive.

abstract property account: str

Account of the directive.

abstract property comment: str

Note comment.

class fava.beans.abc.Open

A Beancount Open directive.

abstract property account: str

Account of the directive.

abstract property booking: Booking | None

Booking method for the account.

abstract property currencies: Sequence[str]

Valid currencies for the account.

class fava.beans.abc.Pad

A Beancount Pad directive.

abstract property account: str

Account of the directive.

abstract property source_account: str

Source account of the pad.

class fava.beans.abc.Position

A Beancount position - just cost and units.

abstract property cost: Cost | None

Units of the position.

abstract property units: Amount

Units of the posting.

class fava.beans.abc.Posting

A Beancount posting.

abstract property account: str

Account of the posting.

abstract property cost: Cost | None

Units of the posting.

abstract property flag: str | None

Flag of the posting.

abstract property meta: Mapping[str, str | int | bool | Decimal | date | Amount] | None

Metadata of the posting.

abstract property price: Amount | None

Price of the posting.

abstract property units: Amount

Units of the posting.

class fava.beans.abc.Price

A Beancount Price directive.

abstract property amount: Amount

Price amount.

abstract property currency: str

Currency for which this is a price.

class fava.beans.abc.Query

A Beancount Query directive.

abstract property name: str

Name of this query.

abstract property query_string: str

BQL query.

class fava.beans.abc.Transaction

A Beancount Transaction directive.

abstract property flag: str

Flag of the transaction.

Entry links.

abstract property narration: str

Narration of the transaction.

abstract property payee: str

Payee of the transaction.

abstract property postings: Sequence[Posting]

Payee of the transaction.

abstract property tags: set[str] | frozenset[str]

Entry tags.

class fava.beans.abc.TxnPosting

A transaction and a posting.

abstract property posting: Posting

Posting.

abstract property txn: Transaction

Transaction.

fava.beans.account

Account name helpers.

fava.beans.account.account_tester(account, *, with_children)

Get a function to check if an account is equal to the account.

Parameters:

  • account (str) – An account name to check.

  • with_children (bool) – Whether to include all child accounts.

Return type:

Callable[[str], bool]

fava.beans.account.child_account_tester(account)

Get a function to check if an account is a descendant of the account.

Return type:

Callable[[str], bool]

fava.beans.account.get_entry_accounts(entry)

Accounts for an entry.

Parameters:

entry (Directive) – An entry.

Returns:

For transactions the posting accounts are listed in reverse order.

Return type:

A list with the entry’s accounts ordered by priority

fava.beans.account.parent(account)

Get the name of the parent of the given account.

Return type:

str | None

fava.beans.account.root(account)

Get root account of the given account.

Return type:

str

fava.beans.create

Helpers to create entries.

fava.beans.create.amount(amt, currency=None)

Amount from a string or tuple.

Return type:

Amount

fava.beans.create.balance(meta, date, account, amount, tolerance=None, diff_amount=None)

Create a Beancount Balance.

Return type:

Balance

fava.beans.create.close(meta, date, account)

Create a Beancount Open.

Return type:

Close

fava.beans.create.cost(number, currency, date, label=None)

Create a Cost.

Return type:

Cost

fava.beans.create.document(meta, date, account, filename, tags=None, links=None)

Create a Beancount Document.

Return type:

Document

fava.beans.create.note(meta, date, account, comment, tags=None, links=None)

Create a Beancount Note.

Return type:

Note

fava.beans.create.open(meta, date, account, currencies, booking=None)

Create a Beancount Open.

Return type:

Open

fava.beans.create.position(units, cost)

Create a Position.

Return type:

Position

fava.beans.create.posting(account, units, cost=None, price=None, flag=None, meta=None)

Create a Beancount Posting.

Return type:

Posting

fava.beans.create.transaction(meta, date, flag, payee, narration, tags=None, links=None, postings=None)

Create a Beancount Transaction.

Return type:

Transaction

fava.beans.flags

Beancount entry flags.

fava.beans.funcs

Various functions to deal with Beancount data.

fava.beans.funcs.get_position(entry)

Get the filename and position from the entry metadata.

Return type:

tuple[str, int]

fava.beans.funcs.hash_entry(entry)

Hash an entry.

Return type:

str

fava.beans.helpers

Helpers for Beancount entries.

fava.beans.helpers.replace(entry, **kwargs)

Create a copy of the given directive, replacing some arguments.

Return type:

TypeVar(T, bound= Directive | Posting)

fava.beans.ingest

Types for Beancount importers.

class fava.beans.ingest.BeanImporterProtocol(*args, **kwargs)

Interface for Beancount importers.

typing.Protocol version of beancount.ingest.importer.ImporterProtocol

Importers can subclass from this one instead of the Beancount one to get type checking for the methods.

extract(file, *, existing_entries=None)

Extract transactions from a file.

Return type:

list[Directive] | None

file_account(file)

Return an account associated with the given file.

Return type:

str

file_date(file)

Attempt to obtain a date that corresponds to the given file.

Return type:

date | None

file_name(file)

A filter that optionally renames a file before filing.

Return type:

str | None

identify(file)

Return true if this importer matches the given file.

Return type:

bool

name()

Return a unique id/name for this importer.

Return type:

str

class fava.beans.ingest.FileMemo(*args, **kwargs)

The file with caching support that is passed to importers.

contents()

Get the file contents.

Return type:

str

convert(converter_func)

Run a conversion function for the file.

Return type:

TypeVar(T)

mimetype()

Get the mimetype of the file.

Return type:

str

name: str

fava.beans.load

Load Beancount files and strings.

fava.beans.load.load_string(value)

Load a Beancoun string.

Return type:

tuple[list[Directive], list[BeancountError], BeancountOptions]

fava.beans.load.load_uncached(beancount_file_path, *, is_encrypted)

Load a Beancount file.

Return type:

tuple[list[Directive], list[BeancountError], BeancountOptions]

fava.beans.prices

Price helpers.

class fava.beans.prices.DateKeyWrapper(inner)

A class wrapping a list of prices for bisect.

This is needed before Python 3.10, which adds the key argument.

inner
class fava.beans.prices.FavaPriceMap(price_entries)

A Fava alternative to Beancount’s PriceMap.

By having some more methods on this class, fewer helper functions need to be imported. Also, this is fully typed and allows to more easily reproduce issues with the whole price logic.

This behaves slightly differently than Beancount. Beancount creates a list for each currency pair and then merges the inverse rates. We just create both the lists in tandem and count the directions that prices occur in.

Parameters:

price_entries (Iterable[Price]) – A sorted list of price entries.

commodity_pairs(operating_currencies)

List pairs of commodities.

Parameters:

operating_currencies (Sequence[str]) – A list of operating currencies.

Returns:

list[tuple[str, str]] – A list of pairs of commodities. Pairs of operating currencies will be given in both directions not just in the one most commonly found in the file.

get_all_prices(base_quote)

Get all prices for the given currency pair.

Return type:

list[tuple[date, Decimal]] | None

get_price(base_quote, date=None)

Get the price for the given currency pair.

Return type:

Decimal | None

get_price_point(base_quote, date=None)

Get the price point for the given currency pair.

Return type:

tuple[date, Decimal] | tuple[None, Decimal] | tuple[None, None]

fava.beans.protocols

Abstract base classes for Beancount types.

class fava.beans.protocols.Amount(*args, **kwargs)

An amount in some currency.

property currency: str

Currency of the amount.

property number: Decimal

Number of units in the amount.

class fava.beans.protocols.Cost(*args, **kwargs)

A cost (basically an amount with date and label).

property currency: str

Currency of the cost.

property date: date

Date of the cost.

property label: str | None

Label of the cost.

property number: Decimal

Number of units in the cost.

class fava.beans.protocols.Position(*args, **kwargs)

A Beancount position - just cost and units.

property cost: Cost | None

Units of the position.

property units: Amount

Units of the posting.

fava.beans.str

Convert Beancount types to string.

fava.beans.str.cost_to_string(cost)

Convert a cost to a string.

Return type:

str

fava.beans.str.to_string(obj, _currency_column=None, _indent=None)

Convert to a string.

Return type:

str

fava.beans.types

Typing helpers.

class fava.beans.types.BeancountOptions

Beancount options.

account_current_conversions: str
account_current_earnings: str
dcontext: DisplayContext
documents: Sequence[str]
filename: str
include: Sequence[str]
name_assets: str
name_equity: str
name_expenses: str
name_income: str
name_liabilities: str
operating_currency: Sequence[str]
render_commas: bool
title: str