数据源

学界对上古（先秦）纪年存在分歧。这是真实的学术分歧, 不是数据错误, 所以本库不替你裁决 —— 由你来选。

import chhiskit

chhiskit.get_age_from_cultural_period("夏", level="epoch")                 # → (-2070.0, ...)
chhiskit.get_age_from_cultural_period("夏", level="epoch", source="shl")   # → (-1989.0, ...)
chhiskit.get_age_from_cultural_period("夏", level="epoch", source="wgd")   # → (-2100.0, ...)

chhiskit.set_default_source("shl")   # 也可以一次性设定偏好

可选数据源

`source`	参照	年份	覆盖范围
`"shl"`	上海图书馆开放数据平台	2024	全部 —— 朝代 / 年号 / 帝王。基础表。
`"xsz"`	夏商周断代工程	2000	仅夏 / 商 / 周 / 东周
`"wgd"`	万国鼎《中国历史纪年表》(中华书局)	1956	仅国号 / 朝代级起讫（74 条）
`"default"`	别名	—	`set_default_source` 最近设定的值; 初始为 `"xsz"`

运行时可用 chhiskit.list_sources() 取得此表。

数据源如何叠加

数据源是覆盖层, 不是替代品。 只有上图具备完整覆盖, 所以它永远是底表; 所选数据源覆盖它知道的条目, 其余一律回落上图。

这一点很重要, 因为三者覆盖度天差地别: 断代工程只对四个政体发言, 万国鼎可解析的索引覆盖 74 条, 而两者都不涉及年号:

chhiskit.get_age_from_cultural_period("康熙", source="wgd")
# → (1662.0, 1722.0)   ← 上图数据; 万国鼎索引不含年号起讫
# SourceFallbackWarning: source='wgd' has no entry for '康熙'; falling back to 上图 base data

你指名的数据源无话可说时, 这个警告就会出现。 答案本身是对的, 只是它并非来自你指名的那个源 —— 而默默地把别处的数字冠以该源之名返回, 就是在歪曲出处。默认源不警告（回落是它的设计), "shl" 也不警告（它本身就是底表）。

覆盖层只作用于朝代级行。某个源说「清 1636~1911」, 那是对政体的声明, 不是对它每个年号的声明 —— 所以它绝不会改写康熙。一个副作用: level="dynasty" 取的是并集, 因此若上图存在比覆盖层起年更早的年号行（清的天命 1616 vs 万国鼎的 1636 国号改称）, 并集仍会报告更早那个年份。

分歧一览

	上图 (`shl`)	万国鼎 (`wgd`)	断代工程 (`xsz`)
夏	-1989 ~ -1559	約-2100 ~ -1600	-2070 ~ -1600
商	-1559 ~ -1123	約-1600 ~ -1028	-1600 ~ -1046
周	-1123 ~ -256	-1027 ~ -256	-1046 ~ -256
西周	-1046 ~ -771	-1027 ~ -771	-1046 ~ -771
东周	-770 ~ -221	-770 ~ -256	-770 ~ -256
春秋	-770 ~ -477	-770 ~ -481	(未覆盖)
战国	-476 ~ -221	-480 ~ -222	(未覆盖)

完整的三源对照（含上古之外的差异）存放于仓库的 data/dynasties/chronology_crosscheck.md。

为什么默认是 `xsz`

两个理由, 都关乎上图自身, 而非「谁对」:

它补上了一个静默的空洞。 新石器 止于 -2070 —— 本就是断代工程的数字 —— 而上图的夏起于 -1989, 于是 -2069..-1990 查询返回空。
上图内部自相矛盾。 它的周起于 -1123（旧说）, 而它自己的西周起于 -1046 （断代工程）。同一张表, 两套编年。

锚定上古行, 是为了让一张表只讲一个故事。但要说清楚这个主张不是什么: 断代工程的夏 -2070 并非举世公认（其精度在海外汉学界普遍受质疑）。它是本数据集的默认, 而非终极意义上的「正确」—— 这恰恰是数据源保持可选的原因。

source="shl" 返回未经改动的上图记录, 并有测试钉死: 它会一直返回本库在多源功能出现之前所发布的那套数字。

东周: 一处如实标注的例外

xsz.csv 里有东周 -770 ~ -256, 但它的 note 明确写着这不是断代工程的结论。断代工程的新成果针对的是公元前 841 年以前; 东周用的是本就无争议的传统纪年。

之所以收录, 是因为万国鼎与传统纪年在 -256（周赧王卒 / 秦灭东周）上一致, 共同反对上图的 -221 —— 后者看起来是把东周与战国混为一谈了。若把它归到断代工程名下, 那是伪造出处 —— 比年份错误更糟。

春秋与战国刻意不覆盖: 断代工程不涉及它们, 且春秋讫年本身就是三方争议（前481 获麟 / 前476 / 前453）。它们的差异只报告, 不裁决。

确认答案的出处

SourceFallbackWarning 就是「这个数字真的来自我指名的源吗」的答案 —— 它恰好在不是的时候出现。若希望把回落当作错误而非警告:

import warnings
from chhiskit import SourceFallbackWarning

with warnings.catch_warnings():
    warnings.simplefilter("error", SourceFallbackWarning)
    chhiskit.get_age_from_cultural_period("夏", level="epoch", source="wgd")   # 正常
    chhiskit.get_age_from_cultural_period("康熙", source="wgd")                # 抛错

当某个结果必须可归因于某一特定文献时, 这很有用 —— 比如一份引用断代工程的分析, 不应该悄悄混入上图的年份。

数据源