Advent-of-Code-Data 示例解析器

年度编程挑战 Advent of Code 通常会提供一些示例数据（和解决方案）供你测试你的代码，这些数据通常是你要解决的每日真实输入数据的缩略版。

尽管真实谜题的输入和答案因用户而异，但示例数据是直接写在谜题文本中的，并且对未认证用户也开放。

为了说明这意味着什么，2022年的第一个谜题是 --- 第 1 天：卡路里计数 ---，它有以下的示例数据（54字节）

1000
2000
3000

4000

5000
6000

7000
8000
9000

10000

对应这个样本数据的正确答案是部分 a 的 24000，部分 b 的 45000。示例数据文本位于第一个 <pre> 标签中，答案位于每个 <article> 部分的最后一个 <code> 块中，位于谜题页面的 HTML 中。请注意，必须先解决谜题的前半部分，第二个 <article> 标签才会出现，因此第二个文章对未认证用户不可见。

在 2022 年，这种示例数据在 HTML 中的位置模式在连续的四天内重复，然后在 --- 第 6 天：调谐困难 --- 发生变化。

这个包是什么？

本包提供了一个 aocd 示例解析器插件 的实现，该插件尝试自动从谜题文本中解析样本数据和相应的答案。

aocd 示例解析器插件是 "adventofcode.examples" 组中的一个 入口点。它必须是一个接受两个参数的可调用对象，如下所示

from aocd.examples import Example
from aocd.examples import Page

def my_plugin(page: Page, datas: list[str]) -> list[Example]:
    """my example parser implementation"""
    ...
    # given the puzzle html found in "page", and a list of real user inputs found in
    # "datas" for potential comparison, the plugin function should scrape and return
    # a list of Example instances. Note that "datas" might be an empty list, if aocd
    # doesn't have any real user inputs cached locally.
    return result

此可调用对象必须返回一个 Example 实例的列表。如果无法解析任何示例，您应返回一个空列表 []，而不是 None。

任何提供示例解析器的包都应该在包元数据中注册 "adventofcode.examples" 组的入口点，在您的 pyproject.toml 文件中添加如下内容

[project.entry-points."adventofcode.examples"]
my_example_parser = "my_module:my_plugin"

有关更多信息，请参阅 入口点 部分 PEP 621 – 将项目元数据存储在 pyproject.toml 中。

如何使用/选择解析器插件？

当示例解析器包与 advent-of-code-data >= 2.0.0 正确安装在一起时，它将作为选项出现在 aoce --help 中

$ aoce --help
usage: aoce [-h] [-e {reference,simple}] [-y 2015+ [2015+ ...]] [-v]

options:
  -h, --help            show this help message and exit
  -e {reference,simple}, --example-parser {reference,simple}
                        plugin to use for example extraction testing (default: reference)
  -y 2015+ [2015+ ...], --years 2015+ [2015+ ...]
                        years to run the parser against (can specify multiple)
  -v, --verbose         increased logging (-v INFO, -vv DEBUG)

它应该可用于选择和使用/验证

$ aoce --example-parser=my_example_parser

要打印解析器针对单个谜题生成的实际结果，您可以使用 aocd --example-parser。再次演示使用这些结果进行 --- 第 1 天：卡路里计数 ---

$ aocd 2022 1 --example-parser=reference
                        --- Day 1: Calorie Counting ---
                      https://adventofcode.com/2022/day/1
------------------------------- Example data 1/1 -------------------------------
1000
2000
3000

4000

5000
6000

7000
8000
9000

10000
--------------------------------------------------------------------------------
answer_a: 24000
answer_b: 45000
--------------------------------------------------------------------------------

为什么是插件？直接在 aocd 中编写解析器不是更简单吗？

我创建了此包，并在 advent-of-code-data 中创建了相应的测试器 aoce，以便让社区尝试并提出更好的解析器。这个包举例说明了解析器应该与之交互的接口，可以说，aocd 使用这个插件进行 自食其力。作为额外的好处，这意味着示例解析可以频繁更新，以确保为以前的谜题返回正确的结果，而无需发布新的 aocd 版本。

有这么多有创造力和智慧的人在对 AoC 进行破解，我相信一定有人能想出比我更好的东西！aocd 的默认实现有超过 40% 的时间会失败，所以你不需要很高的标准去超越。任何得分高于 aoce -e simple 的东西都是一种改进。如果有人提出了比 "取第一个 pre 作为输入数据，取答案来自每篇文章的最后 codeblocks" 更高性能的解析器，我将在 aocd 的未来版本中将他们的实现作为默认选项。

如果您正在考虑编写示例解析器，不建议您追求 100% 的成功率，这如果不是 不可能的，将非常困难。有些谜题有 许多示例，有些解析起来真的很难 很复杂，还有一些根本就没有示例 没有示例。但难度 aside，主要原因是不需要“过度拟合”到以前的谜题。这是因为 advent-of-code-data 总是打算通过硬编码 相关的代码块位置 来返回正确的示例数据 对于过去的谜题。该包使用一个类似于 CalVer 的方案，其中版本字符串表示直到哪一天结果已经手动验证。因此，aocd-example-parser 版本 2023.12.17 可以预期会返回所有 Advent of Code 谜题 <= 2023/12/17 的验证结果，而对于 2023/12/18+ 的未经验证的最佳努力结果。

对于解析器插件来说，唯一重要的是它能多好地应对从未见过的谜题。也就是说，目标是在一个新的谜题解锁的瞬间，最大化你的解析器找到正确结果的概率。

默认实现表现如何？

这取决于年份。近年来，位置变得更加一致，因此表现也更好。最后一条由aoce脚本打印出的行是解析器正确率的大致百分比。

$ for YEAR in {2015..2022};
do echo -n "$YEAR " && aoce -e simple -y $YEAR | tail -1;
done
2015 plugin 'simple' scored 78/336 (23.2%)
2016 plugin 'simple' scored 53/159 (33.3%)
2017 plugin 'simple' scored 85/221 (38.5%)
2018 plugin 'simple' scored 69/212 (32.5%)
2019 plugin 'simple' scored 43/204 (21.1%)
2020 plugin 'simple' scored 67/183 (36.6%)
2021 plugin 'simple' scored 82/152 (53.9%)
2022 plugin 'simple' scored 71/120 (59.2%)

平均来看，我们目前大约有三分之一的正确率。

$ aoce -e simple | tail -1
plugin 'simple' scored 548/1587 (34.5%)

当然，“参考”插件对于历史谜题来说始终是正确的。

$ aoce -e reference | tail -1
plugin 'reference' scored 1587/1587 (100.0%)