fava.core

此模块提供 Fava 报表所需的数据。

exception fava.core.EntryNotFoundForHashError(entry_hash)

未找到哈希值对应的条目。

class fava.core.FavaLedger(path, *, poll_watcher=False)

创建一个 Beancount 账本的接口。

参数：

path (str) – 主 Beancount 文件的路径。

account_journal(filtered, account_name, conversion, *, with_children)

某个账户的日记账。

参数：

  • filtered (FilteredLedger) – 当前过滤后的账本。

  • account_name (str) – 账户名称。

  • conversion (str | Conversion) – 要使用的转换方式。

  • with_children (bool) – 是否包含该账户的子账户的过账记录。

生成：

由(索引, 条目, 变动, 余额)组成的元组。

返回类型：

可迭代对象[元组[int, Directive, SimpleCounterInventory, SimpleCounterInventory]]

账户

一个AccountDict模块 - 账户的详细信息。

all_entries: 序列[Directive]

所有（未过滤）条目的列表。

all_entries_by_type: EntriesByType

按类型分组的所有（未过滤）条目的字典。

attributes

一个AttributesModule实例。

beancount_file_path

主 Beancount 文件的路径。

预算

一个BudgetModule实例。

changed()

检查文件是否需要重新加载。

返回：

bool - 如果检测到任一包含文件或文档文件夹发生更改，并且文件已重新加载，则为 True。

charts

一个ChartModule实例。

commodities

一个CommoditiesModule实例。

commodity_pairs()

列出商品对。

返回：

Sequence[元组[str, str]] - 一组货币对列表。操作货币的组合将双向列出，而不仅限于文件中发现的顺序。

context(entry_hash)

条目的上下文信息。

参数：

entry_hash (str) - 条目的哈希值。

返回：

tuple[Directive, Mapping[str, Sequence[str]] | None, Mapping[str, Sequence[str]] | None, str, str] — 一个包含给定 entry_hash 的（唯一）条目的元组 (entry, before, after, source_slice, sha256sum)。如果该条目是余额或交易，则 before 和 after 分别包含受影响账户在该条目前后的余额。

属性 错误: 序列[BeancountError]

Beancount 加载过程中以及 Fava 模块产生的错误。

扩展

一个 ExtensionModule 实例。

Fava 选项: FavaOptions

包含 Fava 所有选项值的字典。

fava_options_errors: 序列[BeancountError]

解析自定义选项时产生的所有错误列表。

file

一个 FileModule 实例。

format_decimal

一个 DecimalFormatModule 实例。

get_entry(entry_hash)

查找一个条目。

参数：

entry_hash (str) — 条目的哈希值。

返回：

Directive — 具有给定哈希值的条目。

抛出：

EntryNotFoundForHashError — 如果不存在具有该哈希值的条目。

get_filtered
静态 group_entries_by_type()

按类型对条目进行分组。

参数：

entries (Sequence[Directive]) — 需要分组的条目列表。

返回：

EntriesByType – 一个包含分组条目列表的命名元组。

导入

一个 IngestModule 实例。

interval_balances(filtered, interval, account_name, *, accumulate=False)

按区间划分的余额。

参数：

  • filtered (FilteredLedger) – 当前过滤后的账本。

  • interval (Interval) – 一个区间。

  • account_name (str) – 账户名称。

  • accumulate (bool) – 一个布尔值，若为 True，则表示某个区间的余额应包含截至该区间末尾的所有条目。

返回：

tuple[Sequence[Tree], Sequence[DateRange]] – 一个由 Tree 实例列表和区间组成的元组。

join_path(*args)

相对于账本目录的路径。

返回类型：

Path

load_errors: 序列[BeancountError]

Beancount 报告的所有错误的列表。

load_file()

加载主文件及所有包含文件，并设置属性。

返回类型：

None

misc

一个 FavaMisc 实例。

属性 mtime: 整数

底层文件最新更改的时间戳。

options: BeancountOptions

Beancount 选项映射。

paths_to_watch()

获取包含文件和文档目录的路径。

返回：

tuple[Sequence[Path], Sequence[Path]] – 一个元组 (files, directories)。

价格: FavaPriceMap

价格映射。

query_shell

QueryShell 实例。

属性 root_accounts: 元组[str, str, str, str, str]

五个根账户。

statement_path(entry_hash, metadata_key)

获取指定条目中语句的路径。

我们查找的条目应包含指向文档的路径（绝对路径或相对于条目文件名的相对路径），或仅包含其基本名称。我们将遍历所有文档，并根据完整路径进行匹配，或如果某个具有匹配账户的文档具有匹配的文件基本名称，则进行匹配。

参数：

  • entry_hash (str) – 包含元数据中路径的条目的哈希值。

  • metadata_key (str) – 路径所在的键。

返回：

str – 匹配的文档条目的文件名。

抛出：
watcher
class fava.core.FilteredLedger(ledger, *, account=None, filter=None, time=None)

过滤后的 Beancount 账本。

account_is_closed(account_name)

检查账户是否已关闭。

参数：

account_name (str) – 账户名称。

返回：

bool – 如果账户在当前时间过滤器的结束日期之前关闭，则为 True。

日期范围: DateRange | None
属性 end_date: date | None

用于价格的日期。

entries
属性 entries_with_all_prices: 序列[Directive]

过滤后的条目，并为查询重新添加所有价格。

interval_ranges(interval)

生成与区间边界对应的收益日期范围。

返回类型：

Sequence[DateRange]

ledger
paginate_journal(page, per_page=1000)

获取带有分页信息的日记账页面条目。

参数：

  • page (int) – 页码（从 1 开始计数）。

  • per_page (int) – 每页的条目数量。

返回：

tuple[Sequence[tuple[int, Directive]], int] – 包含按倒序时间排列的（全局索引, 指令）元组的日记账页面条目，以及总页数。

prices(base, quote)

列出所有价格。

返回类型：

Sequence[tuple[date, Decimal]]

属性 root_tree: Tree

根树。

属性 root_tree_closed: Tree

用于资产负债表的根树。

exception fava.core.StatementMetadataInvalidError(key)

未找到或无效的报表元数据。

exception fava.core.StatementNotFoundError

未找到报表。

fava.core.accounts

账户关闭日期和元数据。

class fava.core.accounts.AccountData(close_date=None, meta=<factory>, uptodate_status=None, balance_string=None, last_entry=None)

保存有关账户的信息。

balance_string: str | None = None

如果该账户状态为最新，则为余额指令。

close_date: date | None = None

该账户关闭的日期（或 datetime.date.max）。

last_entry: LastEntry | None = None

该账户的最后一条记录（除非是关闭记录）。

meta: Mapping[str, str | 整数 | 布尔值 | Decimal | date | 金额]

此账户的 Open 记录的元数据。

uptodate_status: 可选[Literal['green', 'yellow', 'red']] = None

最新状态。仅当账户具有“fava-uptodate-indication”元属性时才会计算。

类 fava.core.accounts.AccountDict(ledger)

账户信息字典。

EMPTY = AccountData(close_date=None, meta={}, uptodate_status=None, balance_string=None, last_entry=None)
所有余额指令()

所有账户的余额指令。

返回类型：

str

load_file()

在文件被（重新）加载时运行。

返回类型：

None

setdefault(key, _=None)

获取指定名称的账户，如果不存在则插入一个。

返回类型：

AccountData

class fava.core.accounts.LastEntry(date, entry_hash)

账户最后一条记录的日期和哈希值。

date: date

记录的日期。

entry_hash: str

条目哈希。

fava.core.accounts.balance_string(tree_node)

今日指定账户的平衡指令。

返回类型：

str

fava.core.accounts.get_last_entry(txn_postings)

最后一条条目。

返回类型：

指令 | 无

fava.core.accounts.uptodate_status(txn_postings)

最后一条余额或交易的状态。

参数：

txn_postings (序列[指令 | 交易条目]) – 该账户的交易条目。

返回：

可选[字面量['green', 'yellow', 'red']] – 该账户最后一条余额或交易的状态字符串。

  • ’green’：通过的余额检查。

  • ’red’：失败的余额检查。

  • ’yellow’：非余额检查。

fava.core.attributes

用于自动补全的属性。

类 fava.core.attributes.AttributesModule(ledger)

账本的一些属性（主要用于自动补全）。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

narration_transaction(narration)

根据摘要获取最后一条交易。

返回类型：

交易 | 无

属性 narrations: 序列[str]

获取所有交易的摘要。

payee_accounts(payee)

为给定收款方对账户进行排序。

返回类型：

Sequence[str]

payee_transaction(payee)

根据收款人获取最后一条交易。

返回类型：

交易 | 无

fava.core.attributes.get_active_years(条目, 财年结束日)

返回活跃年份，支持财年。

参数：
返回：

列表[字符串] – 按逆序排列的在条目中出现的年份或财年列表。

fava.core.budgets

解析和计算预算。

类 fava.core.budgets.Budget(account: str, date_start: datetime.date, period: Interval, number: Decimal, currency: str)

一个预算条目。

fava.core.budgets.BudgetDict

账户名称到预算条目列表的映射。

别名，dict[str, list[Budget]]

class fava.core.budgets.BudgetError(source: Meta | None, message: str, entry: Directive | None)

预算错误。

类 fava.core.budgets.BudgetModule(ledger)

解析预算条目。

calculate(account, begin_date, end_date)

计算指定时间段内账户的预算。

返回类型：

Mapping[str, Decimal]

calculate_children(account, begin_date, end_date)

计算账户及其子账户的预算。

返回类型：

Mapping[str, Decimal]

load_file()

在文件被（重新）加载时运行。

返回类型：

None

fava.core.budgets.calculate_budget(budgets, account, date_from, date_to)

计算账户的预算。

参数：

  • budgets (dict[str, list[Budget]]) – 一组 Budget 条目。

  • account (str) – 账户名称。

  • date_from (date) – 开始日期。

  • date_to (date) – 结束日期（不包含）。

返回：

Mapping[str, Decimal] – 一个字典，键为货币，值为指定账户和期间的预算（Decimal 类型）。

fava.core.budgets.calculate_budget_children(budgets, account, date_from, date_to)

计算账户及其子账户的预算。

参数：

  • budgets (dict[str, list[Budget]]) – 一组 Budget 条目。

  • account (str) – 账户名称。

  • date_from (date) – 开始日期。

  • date_to (date) – 结束日期（不包含）。

返回：

Mapping[str, Decimal] – 一个字典，键为货币，值为指定账户和期间的预算（Decimal 类型）。

fava.core.budgets.parse_budgets(custom_entries)

从自定义条目中解析预算指令。

参数：

custom_entries (Sequence[Custom]) – 需要从中解析预算的自定义条目。

返回：

元组[字典[字符串, 列表[预算]], 序列[预算错误]] – 账户到预算列表的字典。

示例

2015-04-09 custom “budget” Expenses:Books “monthly” 20.00 EUR

fava.core.charts

提供适用于 Fava 图表的数据。

类 fava.core.charts.ChartModule(ledger)

返回 Fava 中各种图表所需的数据。

层级结构(筛选后的, 账户名称, 转换)

渲染账户树。

返回类型：

SerialisedTreeNode

区间总计(已过滤的账本, 区间, 账户, 转换方式, *, 反转=假)

在指定区间内渲染账户（或多个账户）的总计。

参数：

  • 已过滤的账本 (已过滤账本) – 已过滤的账本。

  • interval (Interval) – 一个区间。

  • accounts (str | tuple[str, ...]) — 单个账户（str）或账户元组。

  • conversion (str | Conversion) – 要使用的转换方式。

  • invert (bool) — 反转所有数字。

生成：

各时间段的余额和预算。

返回类型：

Iterable[DateAndBalanceWithBudget]

linechart(filtered, account_name, conversion)

以折线图形式获取账户余额。

参数：

  • 已过滤的账本 (已过滤账本) – 已过滤的账本。

  • account_name (str) — 一个字符串。

  • conversion (str | Conversion) – 要使用的转换方式。

生成：

包含指定账户余额发生变更的所有日期的字典，每个字典记录该日期账户的余额（以单位计）。

返回类型：

Iterable[DateAndBalance]

net_worth(filtered, interval, conversion)

计算净资产。

参数：

  • 已过滤的账本 (已过滤账本) – 已过滤的账本。

  • interval (Interval) — 表示时间段的字符串。

  • conversion (str | Conversion) – 要使用的转换方式。

生成：

包含指定时间段末尾的所有字典，每个字典分别将净资产（资产 + 负债）转换为所有运营货币。

返回类型：

Iterable[DateAndBalance]

class fava.core.charts.DateAndBalance(date, balance)

某日期的余额。

余额: SimpleCounterInventory
date: date
class fava.core.charts.DateAndBalanceWithBudget(date, balance, account_balances, budgets)

带预算的日期余额。

account_balances: Mapping[str, SimpleCounterInventory]
余额: SimpleCounterInventory
预算: Mapping[str, Decimal]
date: date
类 fava.core.charts.FavaJSONProvider(app)

使用自定义的 JSON 编码器和解码器。

dumps(obj, **_kwargs)

将数据序列化为 JSON。

参数：

  • obj (Any) – 要序列化的数据。

  • kwargs – 可传递给底层 JSON 库。

返回类型：

str

loads(s, **_kwargs)

将数据反序列化为 JSON。

参数：

  • s (str | bytes) – 文本或 UTF-8 字节。

  • kwargs – 可传递给底层 JSON 库。

返回类型：

任意类型

fava.core.charts.dumps(obj, **_kwargs)

以 JSON 字符串形式输出。

返回类型：

str

fava.core.charts.loads(s)

加载一个 JSON 字符串。

返回类型：

任意类型

fava.core.commodities

用于自动补全的属性。

类 fava.core.commodities.CommoditiesModule(ledger)

有关货币和商品的详细信息。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

名称(commodity)

获取商品的名称（如果未设置，则返回商品本身）。

返回类型：

str

fava.core.conversion

Fava 的商品转换辅助工具。

本模块中的所有函数将自动作为模板过滤器添加。

fava.core.conversion.AT_COST = <fava.core.conversion._AtCostConversion object>

将持仓转换为其总成本。

fava.core.conversion.AT_VALUE = <fava.core.conversion._AtValueConversion object>

将头寸转换为其市场价值。

类 fava.core.conversion.Conversion

转换。

abstractmethod apply(inventory, prices, date=None)

将转换应用于库存（CounterInventory）。

返回类型：

SimpleCounterInventory

fava.core.conversion.单位 = <fava.core.conversion._UnitsConversion object>

将头寸转换为其单位。

fava.core.conversion.conversion_from_str(value)

解析转换字符串。

返回类型：

Conversion

fava.core.conversion.convert_position(pos, target_currency, prices, date=None)

获取头寸在特定货币下的价值。

参数：

  • pos (Position) – 一个头寸。

  • target_currency (str) – 目标货币，用于转换。

  • prices (FavaPriceMap) – 一个 FavaPriceMap。

  • date (date | None) – 用于评估价值的 datetime.date 实例，或为 None。

返回：

Amount – 一个 Amount，其值已转换；若转换失败，则返回成本值（若头寸无成本，则返回单位）。

fava.core.conversion.cost_or_value(inventory, conversion, prices, date=None)

获取库存的成本或价值。

返回类型：

SimpleCounterInventory

fava.core.conversion.get_cost(pos)

返回一个头寸的总成本。

返回类型：

金额

fava.core.conversion.get_market_value(pos, prices, date=None)

获取一个头寸的市场价值。

这与 Beancount 中的 convert.get_value 函数不同，当找不到价格时，它会返回成本值。

参数：

  • pos (Position) – 一个头寸。

  • prices (FavaPriceMap) – 一个 FavaPriceMap。

  • date (date | None) – 用于评估价值的 datetime.date 实例，或为 None。

返回：

Amount – 一个 Amount，其值已转换；若转换失败，则返回成本值（若头寸无成本，则返回单位）。

fava.core.documents

与文档路径相关的辅助函数。

exception fava.core.documents.NotADocumentsFolderError(folder)

不是文档文件夹。

exception fava.core.documents.NotAValidAccountError(账户)

不是有效的账户。

fava.core.documents.filepath_in_document_folder(documents_folder, account, filename, ledger)

账户文件夹中文档的文件路径。

参数：

  • documents_folder (str) – 文档文件夹。

  • account (str) – 用于选择子文件夹的账户。

  • filename (str) – 文档的文件名。

  • ledger (FavaLedger) – FavaLedger。

返回：

Path – 文档应保存的路径。

fava.core.documents.is_document_or_import_file(filename, ledger)

检查文件名是否为文档或位于导入目录中。

参数：

  • filename (str) – 要检查的文件名。

  • ledger (FavaLedger) – FavaLedger。

返回：

bool – 是否为文档之一或导入目录中的路径。

fava.core.extensions

Fava 扩展插件。

class fava.core.extensions.ExtensionDetails(name, report_title, has_js_module)

前端所需扩展插件的信息。

has_js_module: 布尔值
名称: str
report_title: str | None
类 fava.core.extensions.ExtensionModule(ledger)

Fava 扩展插件。

after_delete_entry(条目)

运行所有 after_delete_entry 钩子。

返回类型：

None

after_entry_modified(entry, new_lines)

运行所有 after_entry_modified 钩子。

返回类型：

None

after_insert_entry(条目)

运行所有 after_insert_entry 钩子。

返回类型：

None

after_insert_metadata(entry, key, value)

运行所有 after_insert_metadata 钩子。

返回类型：

None

after_load_file()

运行所有 after_load_file 钩子。

返回类型：

None

after_write_source(path, source)

运行所有 after_write_source 钩子。

返回类型：

None

before_request()

运行所有 before_request 钩子。

返回类型：

None

属性 extension_details: 序列[ExtensionDetails]

提供给前端的扩展插件信息。

get_extension(名称)

获取指定名称的扩展插件。

返回类型：

FavaExtensionBase | None

load_file()

在文件被（重新）加载时运行。

返回类型：

None

fava.core.fava_options

Fava 的选项。

Fava 的选项可通过 Beancount 文件中的自定义条目指定。本模块包含所有可能选项的列表、默认值以及解析选项的代码。

class fava.core.fava_options.FavaOptions(account_journal_include_children=True, auto_reload=False, collapse_pattern=<factory>, conversion_currencies=(), currency_column=61, default_file=None, default_page='income_statement/', fiscal_year_end=FiscalYearEnd(month=12, day=31), import_config=None, import_dirs=(), indent=2, insert_entry=<factory>, invert_gains_losses_colors=False, invert_income_liabilities_equity=False, language=None, locale=None, show_accounts_with_zero_balance=True, show_accounts_with_zero_transactions=True, show_closed_accounts=False, sidebar_show_queries=5, unrealized='Unrealized', upcoming_events=7, uptodate_indicator_grey_lookback_days=60, use_external_editor=False)

可在 Beancount 文件中设置的 Fava 选项。

account_journal_include_children: 布尔值 = True
auto_reload: 布尔值 = False
collapse_pattern: 序列[模式[str]]
conversion_currencies: 元组[str, ...] = ()
currency_column: 整数 = 61
default_file: str | None = None
default_page: str = 'income_statement/'
fiscal_year_end: FiscalYearEnd = FiscalYearEnd(month=12, day=31)
import_config: str | None = None
import_dirs: 元组[str, ...] = ()
indent: 整数 = 2
insert_entry: 序列[InsertEntryOption]
invert_gains_losses_colors: 布尔值 = False
invert_income_liabilities_equity: 布尔值 = False
language: str | None = None
locale: str | None = None
set_collapse_pattern(value)

设置 collapse_pattern 选项。

返回类型：

None

set_default_file(value, filename)

设置 default_file 选项。

返回类型：

None

set_fiscal_year_end(value)

设置 fiscal_year_end 选项。

返回类型：

None

set_insert_entry(value, date, filename, lineno)

设置 insert_entry 选项。

返回类型：

None

set_language(value)

设置 locale 选项。

返回类型：

None

set_locale(value)

设置 locale 选项。

返回类型：

None

show_accounts_with_zero_balance: 布尔值 = True
show_accounts_with_zero_transactions: 布尔值 = True
show_closed_accounts: 布尔值 = False
sidebar_show_queries: 整数 = 5
unrealized: str = 'Unrealized'
upcoming_events: 整数 = 7
uptodate_indicator_grey_lookback_days: 整数 = 60
use_external_editor: 布尔值 = False
class fava.core.fava_options.InsertEntryOption(date, re, filename, lineno)

插入选项。

一个决定匹配账户的条目应插入位置的选项。

date: date
filename: str
lineno: 整数
re: 模式[str]
exception fava.core.fava_options.InvalidFiscalYearEndOptionError(value)
exception fava.core.fava_options.MissingOptionError
exception fava.core.fava_options.NotARegularExpressionError(value)
exception fava.core.fava_options.NotAStringOptionError(key)
class fava.core.fava_options.OptionError(source: Meta | None, message: str, entry: Directive | None)

Fava 选项的错误。

exception fava.core.fava_options.UnknownLocaleOptionError(value)
exception fava.core.fava_options.UnknownOptionError(key)
exception fava.core.fava_options.UnsupportedLanguageOptionError(value)
fava.core.fava_options.parse_option_custom_entry(entry, options)

解析单个自定义 Fava 选项条目并相应设置选项。

返回类型：

None

fava.core.fava_options.parse_options(custom_entries)

解析 Fava 选项的自定义条目。

选项条目的格式如下：

2016-04-01 custom "fava-option" "[name]" "[value]"
参数：

custom_entries (Sequence[Custom]) – 自定义条目列表。

返回：

tuple[FavaOptions, list[OptionError]] – 一个元组 (options, errors)，其中 options 是包含所有选项及其值的字典，errors 包含可能的解析错误。

fava.core.file

读取/写入 Beancount 文件。

exception fava.core.file.ExternallyChangedError(path)

文件被外部修改。

类 fava.core.file.FileModule(ledger)

与读取/写入 Beancount 文件相关的函数。

delete_entry_slice(entry_hash, sha256sum)

删除某个条目在源文件中的片段。

参数：

  • entry_hash (str) – 条目的哈希值。

  • sha256sum (str) – 当前条目行内容的 sha256sum 值。

抛出：

FavaAPIError – 如果未找到该条目或文件已被修改。

返回类型：

None

get_source(path)

获取源文件。

参数：

path (Path) – 文件的路径。

返回：

tuple[str, str] – 包含文件内容和文件 sha256sum 的字符串。

抛出：
insert_entries(entries)

插入条目。

参数：

entries (Sequence[Directive]) – 条目列表。

返回类型：

None

insert_metadata(entry_hash, basekey, value)

在指定行号处向文件中插入元数据。

同时防止重复的键。

参数：

  • entry_hash (str) – 条目的哈希值。

  • basekey (str) – 要插入元数据的键。

  • value (str) – 要插入的元数据值。

返回类型：

None

render_entries(entries)

以 Beancount 格式返回条目。

仅渲染 Balance 和 Transaction。

参数：

entries (Sequence[Directive]) – 条目列表。

生成：

以 Beancount 格式渲染的条目。

返回类型：

Iterable[Markup]

save_entry_slice(entry_hash, source_slice, sha256sum)

为条目保存源文件的片段。

参数：

  • entry_hash (str) – 条目的哈希值。

  • source_slice (str) – 用于替换该条目的行内容。

  • sha256sum (str) – 当前条目行内容的 sha256sum 值。

返回：

str – 条目新行内容的 sha256sum 哈希值。

抛出：

FavaAPIError – 如果未找到该条目或文件已被修改。

set_source(path, source, sha256sum)

写入源文件。

参数：

  • path (Path) – 文件的路径。

  • source (str) – 包含文件内容的字符串。

  • sha256sum (str) – 文件的哈希值。

返回：

str – 更新后文件的 sha256sum 哈希值。

抛出：
exception fava.core.file.InvalidUnicodeError(reason)

源文件包含无效的 Unicode。

exception fava.core.file.NonSourceFileError(path)

尝试读取非源文件。

fava.core.file.delete_entry_slice(entry, sha256sum)

删除某个条目在源文件中的片段。

参数：

  • 条目 (Directive) – 一个条目。

  • sha256sum (str) – 当前条目行内容的 sha256sum 值。

抛出：

ExternallyChangedError – 如果文件被外部修改。

返回类型：

None

fava.core.file.find_entry_lines(lines, lineno)

从 lineno 开始的条目行。

参数：

  • lines (Sequence[str]) – 行列表。

  • lineno (int) – 起始的基于 0 的行索引。

返回类型：

Sequence[str]

fava.core.file.find_insert_position(entry, insert_options, default_filename)

查找条目的插入位置。

参数：

  • 条目 (Directive) – 一个条目。

  • insert_options (Sequence[InsertEntryOption]) – InsertOption 列表。

  • default_filename (str) – 若无选项匹配，则默认插入的文件。

返回：

tuple[str, int | None] – 包含文件名和行号的元组。

fava.core.file.get_entry_slice(条目)

获取条目的源文件切片。

参数：

条目 (Directive) – 一个条目。

返回：

tuple[str, str] – 包含条目行的字符串及其 sha256sum。

fava.core.file.insert_entry(entry, default_filename, insert_options, currency_column, indent)

插入一条记录。

参数：

  • 条目 (Directive) – 一个条目。

  • default_filename (str) – 若无选项匹配，则默认插入的文件。

  • insert_options (Sequence[InsertEntryOption]) – 插入选项。

  • currency_column (int) – 用于对齐货币的列。

  • indent (int) – 缩进空格数。

返回：

tuple[Path, Sequence[InsertEntryOption]] – 修改后的路径和更新后的插入选项列表。

fava.core.file.insert_metadata_in_file(path, lineno, indent, key, value)

在 lineno 之后的文件中插入指定的元数据。

考虑 lineno 所在行前的空白字符。

返回类型：

None

fava.core.file.save_entry_slice(entry, source_slice, sha256sum)

为条目保存源文件的片段。

参数：

  • 条目 (Directive) – 一个条目。

  • source_slice (str) – 用于替换该条目的行内容。

  • sha256sum (str) – 当前条目行内容的 sha256sum 值。

返回：

str – 条目新行内容的 sha256sum 哈希值。

抛出：

ExternallyChangedError – 如果文件被外部修改。

fava.core.filters

条目过滤器。

类 fava.core.filters.AccountFilter(value)

按账户过滤。

过滤字符串可以是正则表达式或父账户。

应用(entries)

筛选指令列表。

返回类型：

Sequence[Directive]

类 fava.core.filters.AdvancedFilter(value)

按标签、链接和键筛选。

应用(entries)

筛选指令列表。

返回类型：

Sequence[Directive]

类 fava.core.filters.EntryFilter

筛选条目列表。

abstractmethod 应用(entries)

筛选指令列表。

返回类型：

Sequence[Directive]

异常 fava.core.filters.FilterError(filter_type, message)

筛选异常。

exception fava.core.filters.FilterIllegalCharError(字符)

非法字符筛选错误。

exception fava.core.filters.FilterParseError

筛选解析错误。

类 fava.core.filters.FilterSyntaxLexer

Fava 筛选语法的词法分析器。

ALL(token, _)
返回类型：

tuple[str, str]

ANY(token, _)
返回类型：

tuple[str, str]

CMP_OP(token, value)
返回类型：

tuple[str, str]

EQ_OP(token, value)
返回类型：

tuple[str, str]

KEY(token, value)
返回类型：

tuple[str, str]

返回类型：

tuple[str, str]

数字(标记, 值)
返回类型：

tuple[str, Decimal]

规则 = (('LINK', '\\^[A-Za-z0-9\\-_/.]+'), ('TAG', '\\#[A-Za-z0-9\\-_/.]+'), ('ALL', 'all\\('), ('ANY', 'any\\('), ('KEY', '[a-z][a-zA-Z0-9\\-_]+(?=\\s*(:|=|>=|<=|<|>))'), ('EQ_OP', ':'), ('CMP_OP', '(=|>=|<=|<|>)'), ('NUMBER', '\\d*\\.?\\d+'), ('STRING', '\\w[-\\w]*|"[^"]*"|\'[^\']*\''))
字符串(标记, 值)
返回类型：

tuple[str, str]

标签(标记, 值)
返回类型：

tuple[str, str]

lex(data)

一个生成器，用于输出给定行中的所有标记。

参数：

data (str) – 一个字符串，表示要进行词法分析的行。

生成：

该行中的所有标记。

返回类型：

Iterable[Token]

regex = re.compile('(?P<LINK>\\^[A-Za-z0-9\\-_/.]+)|(?P<TAG>\\#[A-Za-z0-9\\-_/.]+)|(?P<ALL>all\\()|(?P<ANY>any\\()|(?P<KEY>[a-z][a-zA-Z0-9\\-_]+(?=\\s*(:|=|>=|<=|<|>)))|(?P<EQ_OP>:)|(?P<CMP_OP>(=|>=|<=|<|>))|(?P<NUMBER>)
tokens = ('ANY', 'ALL', 'CMP_OP', 'EQ_OP', 'KEY', 'LINK', 'NUMBER', 'STRING', 'TAG')
类 fava.core.filters.FilterSyntaxParser
p_error(_)
返回类型：

None

p_expr(p)

expr : simple_expr

返回类型：

None

p_expr_all(p)

expr : ALL expr ‘)’

返回类型：

None

p_expr_and(p)

expr : expr expr %prec AND

返回类型：

None

p_expr_any(p)

expr : ANY expr ‘)’

返回类型：

None

p_expr_negated(p)

expr : ‘-’ expr %prec UMINUS

返回类型：

None

p_expr_or(p)

expr : expr ‘,’ expr

返回类型：

None

p_expr_parentheses(p)

expr : ‘(’ expr ‘)’

返回类型：

None

p_filter(p)

filter : expr

返回类型：

None

simple_expr : LINK

返回类型：

None

p_simple_expr_STRING(p)

simple_expr : STRING

返回类型：

None

p_simple_expr_TAG(p)

simple_expr : TAG

返回类型：

None

p_simple_expr_key(p)
返回类型：

None

simple_exprKEY EQ_OP STRING
KEY CMP_OP NUMBER
p_simple_expr_units(p)

simple_expr : CMP_OP NUMBER

返回类型：

None

precedence = (('left', 'AND'), ('right', 'UMINUS'))
tokens = ('ANY', 'ALL', 'CMP_OP', 'EQ_OP', 'KEY', 'LINK', 'NUMBER', 'STRING', 'TAG')
类 fava.core.filters.Match(search)

匹配字符串。

match: Callable[[str], 布尔值]
类 fava.core.filters.MatchAmount(op, value)

匹配金额。

match: Callable[[Decimal], 布尔值]
类 fava.core.filters.TimeFilter(options, fava_options, value)

按日期过滤。

应用(entries)

筛选指令列表。

返回类型：

Sequence[Directive]

日期范围
exception fava.core.filters.TimeFilterParseError(value)

时间过滤器解析错误。

类 fava.core.filters.Token(type_, value)

具有特定类型和值的标记。

词法分析器属性仅在 PLY 在解析错误时写入时存在。

lexer
type
value

fava.core.group_entries

按类型分组的条目。

类 fava.core.group_entries.EntriesByType(余额: 序列[abc.Balance], 关闭: 序列[abc.Close], 货币: 序列[abc.Commodity], 自定义: 序列[abc.Custom], 文档: 序列[abc.Document], 事件: 序列[abc.Event], 备注: 序列[abc.Note], 开户: 序列[abc.Open], 补足: 序列[abc.Pad], 价格: 序列[abc.Price], 查询: 序列[abc.Query], 交易: 序列[abc.Transaction])

按类型分组的条目。

类 fava.core.group_entries.TransactionPosting(transaction: abc.Transaction, posting: abc.Posting)

交易和记账项的组合。

fava.core.group_entries.group_entries_by_account(entries)

按账户对记账项进行分组。

参数：

entries (Sequence[Directive]) – 条目列表。

返回：

Mapping[str, Sequence[Directive | TransactionPosting]] — 一个将账户名称映射到其记账项的字典。

fava.core.group_entries.group_entries_by_type(entries)

按类型对条目进行分组。

参数：

entries (Sequence[Directive]) — 需要分组的条目列表。

返回：

EntriesByType – 一个包含分组条目列表的命名元组。

fava.core.ingest

导入辅助函数。

类 fava.core.ingest.FileImportInfo(importer_name, account, date, name)

关于一个文件/导入器组合的信息。

账户: str
date: date
importer_name: str
名称: str
类 fava.core.ingest.FileImporters(name, basename, importers)

用于文件的导入器。

basename: str
importers: 列表[FileImportInfo]
名称: str
exception fava.core.ingest.ImportConfigLoadError(message)

加载导入配置时出错。

exception fava.core.ingest.ImporterExtractError

调用导入器的 extract 方法时出错。

异常 fava.core.ingest.ImporterInvalidTypeError(属性, 预期, 实际)

某个导入器方法返回了意外的类型。

exception fava.core.ingest.ImporterMethodCallError

调用某个导入器方法时出错。

类 fava.core.ingest.IngestError(源: 元数据 | 无, 消息: 字符串, 条目: 指令 | 无)

某个导入器出现错误。

类 fava.core.ingest.IngestModule(ledger)

提供导入功能。

提取(文件名, 导入器名称)

使用指定的导入器从文件中提取条目。

参数：

  • 文件名 (字符串) – 文件的完整路径。

  • 导入器名称 (字符串) – 匹配该文件的导入器名称。

返回：

列表[指令] – 新导入条目的列表。

import_data()

识别可导入的文件和导入器。

返回：

list[FileImporters] – 一个包含 FileImportInfo 的列表。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

属性 模块路径: Path | None

导入器配置的路径。

exception fava.core.ingest.MissingImporterConfigError

缺少 import-config 选项。

exception fava.core.ingest.MissingImporterDirsError

您至少需要设置一个 imports-dir。

类 fava.core.ingest.WrappedImporter(导入器)

用于安全调用导入器方法的包装器。

file_import_info(**kwds: ~typing.~P) → T
返回类型：

TypeVar(T)

identify(**kwds: ~typing.~P) → T
返回类型：

TypeVar(T)

导入器: BeanImporterProtocol | 导入器
属性 名称: T
fava.core.ingest.extract_from_file(wrapped_importer, path, existing_entries)

从文档中导入条目。

参数：

  • wrapped_importer (WrappedImporter) – 用于处理文档的导入器实例。

  • path (Path) – 文档的文件系统路径。

  • existing_entries (Sequence[Directive]) – 现有条目。

返回：

list[Directive] – 导入的条目列表。

fava.core.ingest.filepath_in_primary_imports_folder(filename, ledger)

用于上传到主导入文件夹的文档的文件路径。

参数：

  • filename (str) – 文档的文件名。

  • ledger (FavaLedger) – FavaLedger。

返回：

Path – 文档应保存的路径。

fava.core.ingest.find_imports(config, directory)

将文件与匹配的导入器配对。

生成：

对于目录中的每个文件，返回其文件名和匹配的导入器组成的配对。

返回类型：

可迭代对象[文件导入器]

fava.core.ingest.get_cached_file(path)

获取一个缓存的 FileMemo。

在从缓存中获取之前，会检查文件的修改时间。除了使用 beangulp 缓存外。

返回类型：

FileMemo

fava.core.ingest.load_import_config(模块路径)

加载给定的导入配置，并提取导入器和钩子。

参数：

module_path (Path) —— 导入配置的路径。

返回：

tuple[Mapping[str, WrappedImporter], Sequence[Callable[[list[tuple[str, list[Directive], str, BeanImporterProtocol | Importer]] | list[tuple[str, list[Directive]]], Sequence[Directive]], list[tuple[str, list[Directive], str, BeanImporterProtocol | Importer]] | list[tuple[str, list[Directive]]]]]] —— 由名称标识的导入器及其钩子列表组成的对。

fava.core.ingest.walk_dir(目录)

遍历目录中的所有文件。

忽略常见的点目录，如 .git、.cache、.venv，参见 IGNORE_DIRS。

参数：

目录 (Path) – 起始目录。

生成：

目录下所有完整路径，忽略某些目录。

返回类型：

Iterable[Path]

fava.core.inventory

Beancount 的 Inventory 的替代实现。

类 fava.core.inventory.CounterInventory

一种轻量级库存。

此实现旨在作为 Beancount 的 Inventory 类的更快替代方案。由于不使用列表，对于包含大量不同头寸的库存，插入操作要快得多。

键应为元组 (货币, 成本)。

add(key, number)

向键添加一个数值。

返回类型：

None

add_amount(amount, cost=None)

向库存添加一个 Amount。

返回类型：

None

add_inventory(counter)

添加另一个 CounterInventory。

返回类型：

None

add_position(pos)

向库存添加一个 Position 或 Posting。

返回类型：

None

is_empty()

检查库存是否为空。

返回类型：

布尔值

reduce(reducer, *args, **_kwargs)

简化库存。

请注意，此方法返回一个仅以货币为键的简单 CounterInventory。

返回类型：

SimpleCounterInventory

to_strings()

以字符串列表形式输出（例如用于快照测试）。

返回类型：

list[str]

类 fava.core.inventory.SimpleCounterInventory

一种简单的库存映射，仅将字符串映射到数值。

add(key, number)

向键添加一个数值。

返回类型：

None

is_empty()

检查库存是否为空。

返回类型：

布尔值

reduce(reducer, *args, **_kwargs)

简化库存。

返回类型：

SimpleCounterInventory

fava.core.misc

一些杂项报告。

class fava.core.misc.FavaError(source: Meta | None, message: str, entry: Directive | None)

Fava 特有的通用错误。

类 fava.core.misc.FavaMisc(ledger)

提供对一些杂项报表的访问。

属性 错误: 序列[FavaError]

未设置运营货币时的错误。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

用户自定义的侧边栏链接。

upcoming_events: 序列[事件]

未来几天内的即将发生的事件。

fava.core.misc.align(string, currency_column)

对一列中的货币进行对齐。

返回类型：

str

解析自定义条目以获取链接。

其格式如下：

2016-04-01 custom "fava-sidebar-link" "2014" "/income_statement/?time=2014"

返回类型：

Sequence[tuple[str, str]]

fava.core.misc.upcoming_events(events, max_delta)

解析条目以获取即将发生的事件。

参数：

  • events (Sequence[Event]) – 事件列表。

  • max_delta (int) – 应考虑的天数。

返回：

Sequence[Event] – 条目中距离小于 max_delta 天的事件列表。

fava.core.module_base

FavaLedger 的“模块”的基类。

类 fava.core.module_base.FavaModule(ledger)

FavaLedger 的“模块”的基类。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

fava.core.number

数字格式化。

类 fava.core.number.DecimalFormatModule(ledger)

数字格式化。

load_file()

在文件被（重新）加载时运行。

返回类型：

None

fava.core.number.get_locale_format(locale, precision)

获取指定区域设置和精度的格式化模式。

参数：

  • locale (Locale | None) – 可选的区域设置。

  • precision (int) – 精度。

返回：

Callable[[Decimal], str] – 一个将 Decimal 转换为字符串的函数。

fava.core.query

查询结果类型。

class fava.core.query.AmountColumn(name, dtype='Amount')

一个金额查询列。

dtype: str = 'Amount'
类 fava.core.query.BaseColumn(name, dtype)

一个查询列。

dtype: str
名称: str
静态 serialise(val)

列值的可序列化版本。

返回类型：

bool | int | str | date | Decimal | Position | SimpleCounterInventory | None

类 fava.core.query.BoolColumn(name, dtype='bool')

一个布尔型查询列。

dtype: str = 'bool'
类 fava.core.query.DateColumn(name, dtype='date')

一个日期查询列。

dtype: str = 'date'
类 fava.core.query.DecimalColumn(name, dtype='Decimal')

一个十进制查询列。

dtype: str = 'Decimal'
类 fava.core.query.IntColumn(name, dtype='int')

一个整数查询列。

dtype: str = 'int'
类 fava.core.query.InventoryColumn(name, dtype='Inventory')

一个字符串查询列。

dtype: str = 'Inventory'
静态 serialise(val)

序列化库存。

返回类型：

SimpleCounterInventory | None

类 fava.core.query.ObjectColumn(name, dtype='object')

一个对象查询列。

dtype: str = 'object'
静态 serialise(val)

将未知类型的对象序列化为字符串。

返回类型：

str

类 fava.core.query.PositionColumn(名称, 数据类型='Position')

一个位置查询列。

dtype: str = 'Position'
类 fava.core.query.QueryResultTable(类型, 行, t='table')

表格查询结果。

行: 列表[元组[布尔值 | 整数 | str | date | Decimal | 头寸 | SimpleCounterInventory | None, ...]]
t: Literal['table'] = 'table'
类型: 列表[BaseColumn]
类 fava.core.query.QueryResultText(内容, t='string')

文本查询结果。

contents: str
t: Literal['string'] = 'string'
类 fava.core.query.SetColumn(名称, 数据类型='set')

一个集合查询列。

dtype: str = 'set'
class fava.core.query.StrColumn(name, dtype='str')

一个字符串查询列。

dtype: str = 'str'

fava.core.query_shell

用于从 Fava 中使用 Beancount shell。

类 fava.core.query_shell.FavaBQLShell(ledger)

对 Beancount shell 的轻量级封装。

add_help()

为每个解析的标记处理器附加帮助函数。

返回类型：

None

do_EOF(_)

在 Fava 的查询 shell 中不执行任何操作。

返回类型：

None

do_exit(_)

在 Fava 的查询 shell 中不执行任何操作。

返回类型：

None

do_quit(_)

在 Fava 的查询 shell 中不执行任何操作。

返回类型：

None

do_run(arg)

运行自定义查询。

返回类型：

Cursor | None

noop(_)

在 Fava 的查询 shell 中不执行任何操作。

返回类型：

None

on_Reload(_)

在 Fava 的查询 shell 中不执行任何操作。

返回类型：

None

on_Select(statement)

从交易明细查询中提取数据。

SELECT 语句的一般形式大致遵循 SQL 语法，并包含一些轻微且符合习惯的扩展：

SELECT [DISTINCT] [<targets>|*] [FROM <from_expr> [OPEN ON <date>] [CLOSE [ON <date>]] [CLEAR]] [WHERE <where_expr>] [GROUP BY <groups>] [ORDER BY <groups> [ASC|DESC]] [LIMIT num]

其中：

targets：一组期望从交易明细中输出的属性，

以及对这些属性的表达式。在此上下文中，父交易指令的一些属性也可用。支持单行返回值的简单函数和单组返回值的聚合函数均可使用。有关支持的列和函数的完整列表，请参见“targets”帮助。您也可以在此处使用通配符，以选择一组合理的默认列用于渲染日记账。

from_expr：匹配指令（而非交易明细）属性的逻辑表达式。

这允许您选择一部分交易，从而确保余额报告符合会计等式。有关支持的列和函数的完整列表，请参见“from”帮助。

where_expr：匹配交易明细属性的逻辑表达式。

可用的列与 targets 子句中的类似，但不包含聚合函数。

OPEN 子句：用以下方式替换指定日期之前的所有交易：

汇总条目，并将收入和支出余额转入权益。

CLOSE 子句：删除指定日期之后的所有交易，并

CLEAR：将最终的收入和支出余额转入权益。

返回类型：

游标

输出文件: StringIO
运行(条目, 查询)

运行查询，将输出捕获为字符串或返回结果。

返回类型：

游标 | str

exception fava.core.query_shell.FavaShellError(message)

Fava BQL shell 中的错误将被转换为字符串。

exception fava.core.query_shell.NonExportableQueryError

只有返回表格的查询才能输出到文件。

exception fava.core.query_shell.QueryCompilationError(err)

查询编译错误。

exception fava.core.query_shell.QueryNotFoundError(名称)

查询“{name}”未找到。

exception fava.core.query_shell.QueryParseError(err)

查询解析错误。

类 fava.core.query_shell.QueryShell(ledger)

一个用于运行 BQL 查询的 Fava 模块。

execute_query_serialised(条目, 查询)

运行查询并返回其序列化结果。

参数：

  • entries (Sequence[Directive]) – 要在其上运行查询的条目。

  • query (str) – 查询字符串。

返回：

QueryResultTable | QueryResultText – 表格结果或文本结果（取决于查询）。

抛出：

FavaAPIError – 如果查询响应为错误。

query_to_file(条目, 查询字符串, 结果格式)

将查询结果作为文件获取。

参数：

  • entries (Sequence[Directive]) – 要在其上运行查询的条目。

  • query_string (str) – 字符串，要运行的查询。

  • result_format (str) – 保存文件的格式。

返回：

tuple[str, BytesIO] — 一个元组 (name, data)，其中 name 为 'query_result' 或当查询字符串为 'run name_of_query' 时的自定义查询名称。data 包含文件内容。

抛出：

  • FavaAPIError — 如果结果格式不受支持或

  • 查询失败。 —

exception fava.core.query_shell.TooManyRunArgsError(args)

运行命令的参数过多：'{args}'。

fava.core.tree

账户余额树。

class fava.core.tree.SerialisedTreeNode(account, balance, balance_children, children, has_txns, cost=None, cost_children=None)

一个序列化的 TreeNode。

账户: str
余额: SimpleCounterInventory
balance_children: SimpleCounterInventory
children: 序列[SerialisedTreeNode]
cost: SimpleCounterInventory | None = None
cost_children: SimpleCounterInventory | None = None
has_txns: 布尔值
class fava.core.tree.Tree(entries=None, create_accounts=None)

账户树。

参数：

  • entries (Iterable[Union[Directive, Open, Close, Commodity, Pad, Balance, Transaction, Note, Event, Query, Price, Document, Custom]] | None) – 用于计算余额的条目列表。

  • create_accounts (list[str] | None) – 树应包含的账户列表。

属性 账户: 列表[str]

此树中的账户。

祖先(名称)

账户的祖先。

参数：

name (str) – 账户名称。

生成：

从下至上给出账户的祖先。

返回类型：

Iterable[TreeNode]

cap(options, unrealized_account)

转移收入与支出，添加汇兑损益和未实现收益。

参数：

  • options (BeancountOptions) – Beancount 选项。

  • unrealized_account (str) – 用于记录未实现收益的账户名称（作为 Equity 的子账户）。

返回类型：

None

获取(名称, *, 插入=False)

获取一个账户。

参数：

  • name (str) – 账户名称。

  • insert (bool) – 如果为 True，当名称不存在时将其插入树中。

返回：

该名称对应的账户，或如果账户不在树中则返回一个空账户。

返回类型：

TreeNode

插入(名称, 余额)

插入一个带有余额的账户。

插入账户并更新其余额及其所有祖先账户的余额。

参数：
返回类型：

None

净收益(选项, 账户名称)

计算净收益。

参数：

  • options (BeancountOptions) – Beancount 选项。

  • account_name (str) – 用于包含净收益的账户的名称。

返回类型：

TreeNode

类 fava.core.tree.TreeNode(名称)

账户树中的一个节点。

余额

账户余额。

balance_children

累计账户余额。

children: 列表[TreeNode]

一个包含 TreeNode 的列表，即其子节点。

has_txns

该账户是否包含任何交易。

名称: str

账户名称。

序列化(转换, 价格, 结束, *, 包含成本=False)

序列化该账户。

参数：

  • 转换 (转换) – 要使用的转换。

  • 价格 (FavaPriceMap) – 要使用的价格映射。

  • 结束时间 (date | None) – 用于成本转换的日期。

  • with_cost (bool) – 同时转换为成本。

返回类型：

SerialisedTreeNode

serialise_with_context()

序列化，并从 Flask 上下文中获取所有参数。

返回类型：

SerialisedTreeNode

fava.core.watcher

一个简单的文件和文件夹监视器。

类 fava.core.watcher.Watcher

一个简单的文件和文件夹监视器。

对于文件夹，仅检查文件夹及其所有子目录的修改时间。因此，文件更改不会被察觉，仅能检测到新增或删除的文件。

update(files, folders)

更新要监视的文件和文件夹。

返回类型：

None

类 fava.core.watcher.WatcherBase

Fava 账本文件监视器的抽象基类。

check()

检查是否有更改。

返回：

bool – 如果文件或文件夹中有任何更改，则为 True，否则为 False。

last_checked: 整数

文件监视器最近一次检测到更改的时间戳。

last_notified: 整数

监视器最近一次收到更改通知的时间戳。

notify(path)

通知监视器某个路径发生了更改。

返回类型：

None

abstractmethod update(files, folders)

更新要监视的文件和文件夹。

参数：

  • files (Iterable[Path]) – 文件路径列表。

  • folders (Iterable[Path]) – 文件夹路径列表。

返回类型：

None

类 fava.core.watcher.WatchfilesWatcher

使用 watchfiles 库的文件和文件夹监视器。

update(files, folders)

更新要监视的文件和文件夹。

返回类型：

None