datasette-dateutil

Datasette的dateutil函数

安装

在Datasette相同的环境中安装此插件。

$ datasette install datasette-dateutil

用法

此函数添加了自定义SQL函数，用于公开来自dateutil Python库的功能。

安装后，以下SQL函数将可用

解析日期字符串

• dateutil_parse(text) - 从文本中解析出ISO8601日期字符串，如果输入无法解析则返回null。dateutil_parse("10 october 2020 3pm")返回2020-10-10T15:00:00。
• dateutil_parse_fuzzy(text) - 与dateutil_parse()相同，但此函数还可以针对包含日期的字符串进行处理 - 将返回该日期，如果找不到日期则返回null。dateutil_parse_fuzzy("This is due 10 september")返回2020-09-10T00:00:00（但如果年份是2021年，则会开始返回2021年的版本）。

dateutil_parse()和dateutil_parse_fuzzy()函数都遵循美国习惯，假设1/2/2020表示月份首先，评估此示例为1月2日。

如果您想假设日期先于月份，请使用这两个函数代替

• dateutil_parse_dayfirst(text)
• dateutil_parse_fuzzy_dayfirst(text)

以下是一个演示这些函数的查询

select
  dateutil_parse("10 october 2020 3pm"),
  dateutil_parse_fuzzy("This is due 10 september"),
  dateutil_parse("1/2/2020"),
  dateutil_parse("2020-03-04"),
  dateutil_parse_dayfirst("2020-03-04");

尝试此查询

可选默认日期

dateutil_parse()、dateutil_parse_fuzzy()、dateutil_parse_dayfirst()和dateutil_parse_fuzzy_dayfirst()函数都接受一个可选的第二个参数，用于指定如果某些细节缺失时考虑的“默认”日期时间。例如，以下内容

select dateutil_parse('1st october', '1985-01-01')

将返回1985-10-01T00:00:00 - 缺失的年份被默认日期的年份替换。

以下是一个演示默认日期参数的查询示例

计算复活节

• dateutil_easter(year) - 返回该年的复活节日期，例如 dateutil_easter("2020") 返回 2020-04-12。

复活节查询示例

日期的 JSON 数组

几个函数返回日期字符串的 JSON 数组。这些可以与 SQLite 的 json_each() 函数一起使用，以执行针对特定日期范围或重复规则的连接。

这些函数最多可以返回 10,000 个结果。如果返回超过 10,000 个日期，将返回错误 - 这是为了防止拒绝服务攻击。

• dateutil_dates_between('1 january 2020', '5 jan 2020') - 给定两个日期（任何可以被 dateutil_parse() 处理的格式），此函数返回包含两个日期之间日期的 JSON 字符串，包括这两天。此示例返回 ["2020-01-01", "2020-01-02", "2020-01-03", "2020-01-04", "2020-01-05"]。
• dateutil_dates_between('1 january 2020', '5 jan 2020', 0) - 将可选的第三个参数设置为 0 以指定您希望该日期不包括最后一天。此示例返回 ["2020-01-01", "2020-01-02", "2020-01-03", "2020-01-04"]。

尝试这些查询

dateutil_rrule() 和 dateutil_rrule_date() 函数接受 iCalendar 标准的 ``rrule` 格式 - 请参阅dateutil 文档获取更多示例。

此格式允许您指定重复规则，例如“该月的下四个最后一个星期一”。

• dateutil_rrule(rrule, optional_dtsart) - 给定一个 rrule，返回一个包含 ISO 日期时间的 JSON 数组。第二个参数是可选的，并将其作为规则的开始日期处理。
• dateutil_rrule_date(rrule, optional_dtsart) - 与 dateutil_rrule() 相同，但返回 ISO 日期。

查询示例

select
  dateutil_rrule('FREQ=HOURLY;COUNT=5'),
  dateutil_rrule_date(
    'FREQ=DAILY;COUNT=3',
    '1st jan 2020'
  );

尝试 rrule 示例查询

使用 json_each() 连接数据

SQLite 的 json_each() 函数 可以将日期的 JSON 数组转换为可以与其他数据连接的表。以下是一个返回显示 2019 年 1 月每一天的表的查询。

select
  value as date
from
  json_each(
    dateutil_dates_between('1 Jan 2019', '31 Jan 2019')
  )

尝试此查询

您可以通过使用 SQLite 的 对公共表表达式 (CTEs) 的支持 为此表分配一个名称来运行对此表的连接。

此查询示例使用 substr(created, 0, 11) 来检索 facetable 示例表 中 created 列的日期部分，然后将其与 1 月份的日期表连接以计算每天创建的行数。对 days_in_january 的 LEFT JOIN 确保在没有创建记录的日期仍然返回结果，计数为 0。

with created_dates as (
  select
    substr(created, 0, 11) as date
  from
    facetable
),
days_in_january as (
  select
    value as date
  from
    json_each(
      dateutil_dates_between('1 Jan 2019', '31 Jan 2019')
    )
)
select
  days_in_january.date,
  count(created_dates.date) as total
from
  days_in_january
  left join created_dates on days_in_january.date = created_dates.date
group by
  days_in_january.date;

尝试该查询 并使用 datasette-vega 插件绘制条形图。

开发

要本地设置此插件，首先检出代码。然后创建一个新的虚拟环境

cd datasette-dateutil
python3 -mvenv venv
source venv/bin/activate

或者如果您正在使用 pipenv

pipenv shell

现在安装依赖项和测试

pip install -e '.[test]'

要运行测试

pytest