fava.util

一些小型实用函数。

fava.util.filter_api_changed(record)

过滤掉用于轮询更改的请求日志记录。

返回类型：

布尔值

fava.util.get_translations(locale)

检查 Fava 是否支持指定的区域设置。

参数：

locale (区域设置) – 要查找的区域设置

返回：

str | None – 找到的翻译文件路径，如果没有匹配项则为 None。

fava.util.listify(func)

将生成器函数包装为返回列表的装饰器。

返回类型：

Callable[[ParamSpec(P, bound= None)], list[TypeVar(Item)]]

fava.util.next_key(basekey, keys)

在提供的字典中返回 basekey 的下一个未使用的键。

首先尝试 basekey，然后依次尝试 basekey-2、basekey-3 等，直到找到一个可用的键。

返回类型：

str

fava.util.send_file_inline(filename)

以内联方式发送文件，包含原始文件名。

参考： http://test.greenbytes.de/tech/tc2231/。

返回类型：

响应

fava.util.setup_debug_logging()

为 Fava 设置调试级别日志记录。

返回类型：

None

fava.util.setup_logging()

为 Fava 设置日志记录。

返回类型：

None

fava.util.simple_wsgi(_, start_response)

返回一个空响应（一个简单的 WSGI 应用）。

返回类型：

list[bytes]

fava.util.slugify(string)

将字符串转换为 slug 格式。

参数：

string (str) – 一个字符串。

返回：

str – 适用于 URL 的字符串的“slug”形式。保留非 ASCII 字符。

fava.util.timefunc(func)

用于调试的时间函数（装饰器）。

返回类型：

Callable[[ParamSpec(P, bound= None)], TypeVar(T)]

fava.util.date

与日期相关的功能。

备注

日期范围始终为元组 (start, end)，从包含起始日期到不包含结束日期。

class fava.util.date.DateRange(begin, end)

一个日期范围，通常对应一个时间区间。

begin: date

此日期范围的包含起始日期。

end: date

此日期范围的不包含结束日期。

属性 end_inclusive: date

此区间的最后一天。

class fava.util.date.FiscalYearEnd(month, day)

指定财年结束的月份和日期。

day: 整数
has_quarters()

此财年结束是否支持财季。

返回类型：

布尔值

month: 整数
属性 month_of_year: 整数

一年中的实际月份。

属性 year_offset: 整数

此日期相对于当前年份向后偏移的年数。

exception fava.util.date.FyeHasNoQuartersError

只有在每月第一天开始的财年才支持财季。

类 fava.util.date.Interval

一个区间。

abstractmethod format_date(date)

为此间隔的 Fava 时间过滤器格式化日期。

返回类型：

str

abstractmethod get_next(date)

获取紧跟在指定日期之后的下一个间隔的起始日期。

返回类型：

date

abstractmethod get_prev(date)

获取包含指定日期的间隔的起始日期。

返回类型：

date

抽象 属性 label: str

该间隔的标签。

number_of_days(date)

获取周围间隔的天数。

返回类型：

整数

exception fava.util.date.InvalidDateRangeError

结束日期必须在开始日期之后。

fava.util.date.dateranges(begin, end, interval, *, complete)

获取给定开始和结束日期的日期范围。

参数：

  • begin (date) – 开始日期 - 第一个间隔范围将包含此日期

  • end (date) – 结束日期 - 最后一个间隔将在该日期或之后结束

  • interval (Interval) – 要生成范围的间隔类型。

  • complete (bool) – 是否补全起始和结束间隔。

生成：

给定间隔内所有日期范围。

返回类型：

Iterable[DateRange]

fava.util.date.days_in_daterange(start_date, end_date)

为指定间隔内的每一天生成一个 datetime。

参数：

  • start_date (date) – 开始日期。

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

生成：

从 start_date 到 end_date 之间的所有日期。

返回类型：

迭代器[date]

fava.util.date.get_fiscal_period(年份, 财年结束日, 季度=None)

计算财年期间。

使用 fava 选项 “fiscal-year-end”，其格式应为 “%m-%d”。默认为日历年 [12-31]。

参数：

  • year (int) – 一个整数年份

  • fye (FiscalYearEnd | None) – 以 “%m-%d” 格式表示的期间结束日期

  • quarter (int | None) – 其中之一：[None, 1, 2, 3 或 4]

返回：

tuple[date | None, date | None] – 一个包含 (开始, 结束) 日期的元组。

fava.util.date.interval_ends(起始, 结束, 间隔, *, 完整)

获取间隔的结束点。

生成：

间隔的结束日期。

返回类型：

迭代器[date]

fava.util.date.local_today()

以本地时区表示的今天日期。

返回类型：

date

fava.util.date.month_offset(date, months)

将日期按指定的月数偏移。

保持日期的天数不变，除非该天数无效，此时将抛出 ValueError。

返回类型：

date

fava.util.date.parse_date(string, fye=None)

解析日期。

支持的格式示例：

  • 2010-03-15、2010-03、2010

  • 2010-W01、2010-Q3

  • FY2012、FY2012-Q2

日期范围可以用以下形式表示：

  • 起始日期 - 结束日期

  • 起始日期 到 结束日期

其中起始日期和结束日期类似于上述示例之一

参数：

  • string (str) – 采用我们自定义格式的日期（或日期范围）。

  • fye (FiscalYearEnd | None) – 要使用的财年结束日。

返回：

tuple[date | None, date | None] – 一个包含 (开始, 结束) 日期的元组。

fava.util.date.parse_fye_string(fye)

解析财年结束日的字符串选项。

参数：

fye (str) – 要解析的财年结束日。

返回类型：

FiscalYearEnd | None

fava.util.date.substitute(string, fye=None)

替换引用当前日期的变量。

参数：

  • string (str) – 可能包含今天变量的字符串。

  • fye (FiscalYearEnd | None) – 使用指定的财年结束日期

返回：

str – 一个字符串，其中如“year”或“week”等指向当前日期的变量已被 parse_date() 能识别的对应字符串替换。支持加减运算。

fava.util.excel

将查询结果写入 CSV 和电子表格文档。

exception fava.util.excel.InvalidResultFormatError(result_format)
fava.util.excel.to_csv(types, rows)

将结果保存为 CSV 文件。

参数：

  • types (list[Column]) – 查询结果的类型列表。

  • rows (list[tuple[Any, ...]]) – 查询结果的行数据。

返回：

BytesIO – （二进制）文件内容。

fava.util.excel.to_excel(types, rows, result_format, query_string)

将结果保存为电子表格文档。

参数：

  • types (list[Column]) – 查询结果的类型列表。

  • rows (list[tuple[Any, ...]]) – 查询结果的行数据。

  • result_format (str) – ‘xlsx’ 或 ‘ods’。

  • query_string (str) – 查询字符串（将写入文档中）。

返回：

BytesIO – （二进制）文件内容。

fava.util.ranking

排名工具。

class fava.util.ranking.ExponentialDecayRanker(list_=None, rate=0.0018990333713971104)

通过指数衰减对列表进行排序。

为列表中的项目维护分数。我们可以将其视为所有“喜欢”值的总和，其中每个“喜欢”的初始值为 1，并呈指数衰减。因此，当前分数由下式给出（其中 t 为当前时间，l 为“喜欢”发生的时间）：

s = Σ exp(-RATE * (t - l))

由于仅需关注项目之间的相对顺序，我们可以将所有分数乘以 exp(RATE * t)，因此只需计算以下分数：

s = Σ exp(RATE * l)

为避免数值过大，我们实际计算并存储该和的对数。

参数：

  • list – 如果提供，该列表将通过 .sort() 进行排序；否则，所有至少有一个“喜欢”的项目都将被排序。

  • rate (float) – 设置衰减率。1/rate 表示一个“喜欢”的价值降至 1/e 所需的时间（以天为单位）。默认速率设置为 math.log(2) * 1/365，使得一年前的“喜欢”仅相当于今天的“喜欢”的一半。

获取(项目)

获取某个项目的当前分数，若无则返回零。

返回类型：

浮点数

列表
速率
分数: 字典[str, 浮点数]
排序()

按排名返回项目。

返回类型：

list[str]

update(item, date)

为项目添加一个“喜欢”。

参数：

  • item (str) – 被排序列表中的一个项目。

  • date (date) – 该项目被点赞的日期。

返回类型：

None

fava.util.sets

用于 Python 集合的工具。

fava.util.sets.add_to_set(set_, new)

向集合中添加一个元素（如果不存在则创建）。

参数：

  • set – 要添加元素的集合（可选）。

  • new (str) – 要添加到集合中的字符串。

返回类型：

set[str]

fava.util.unreachable

用于不可达代码的类型检查辅助工具。

exception fava.util.unreachable.UnreachableCodeAssertionError

预期这段代码不可达。

fava.util.unreachable.assert_never(_)

断言此代码不可达。

返回类型：

永不