A typed, dependency-light Python API for Chinese historical chronology: look up any 年号 / 朝代 / 历史时期 by name or by year, from the Paleolithic through 清.

✨ Features

• 🔁 Two-way lookup — name → (begin, end) years; year → list of all parallel polities.
• 🪨 Full timeline — 旧石器 / 新石器 prehistoric brackets through 清.
• 📚 Selectable chronology — 上古 dating is contested scholarship, so pick the source you trust: 上海图书馆, 夏商周断代工程, or 万国鼎《中国历史纪年表》.
• 🧭 Disambiguated — reused names resolve correctly (夏(窦建德) ≠ 上古 夏), and an ambiguous 年号 raises rather than guessing.
• 🌐 Alias-friendly — pass aliases={"新石器": {"Neolithic", "Neo"}} to accept foreign-language input.
• ⚡ Lightweight — only pandas at runtime; data ships with the package, no network needed.

🚀 Quickstart

# From PyPI — distribution name is `chinese_history_toolkits`
pip install chinese_history_toolkits

# Or from source
git clone https://github.com/SongshGeoLab/chinese_history_toolkits.git
cd chinese_history_toolkits
uv sync --all-extras

Note — the PyPI distribution name is chinese_history_toolkits (verbose), but the import name is the short acronym chhiskit for daily use.

import chhiskit

# Name → years
chhiskit.get_age_from_cultural_period("康熙")                              # → (1662.0, 1722.0)
chhiskit.get_age_from_cultural_period("唐", level="dynasty")               # → (618.0, 907.0)
chhiskit.get_age_from_cultural_period("新石器", level="epoch")             # → (-10000.0, -2070.0)

# Year → matching polities (multiple are normal — 三国, 隋末, etc.)
[m.dynasty_id for m in chhiskit.get_cultural_periods_from_year(250)]
# → ['三国', '吴', '蜀', '魏']

# BP convention (radiocarbon, 1950 reference)
chhiskit.get_age_from_cultural_period("商", level="dynasty", anno_domini=False)
# → (3550.0, 2996.0)

# Foreign aliases
chhiskit.get_age_from_cultural_period(
    "Neolithic", level="epoch",
    aliases={"新石器": {"Neolithic", "Neo"}},
)
# → (-10000.0, -2070.0)

📚 Choosing a chronology

Scholars disagree about 上古 dating — the disagreement is real scholarship, not data error — so this library lets you pick rather than deciding for you:

chhiskit.get_age_from_cultural_period("夏", level="epoch")                 # → (-2070.0, ...)  夏商周断代工程 (default)
chhiskit.get_age_from_cultural_period("夏", level="epoch", source="shl")   # → (-1989.0, ...)  上海图书馆
chhiskit.get_age_from_cultural_period("夏", level="epoch", source="wgd")   # → (-2100.0, ...)  万国鼎 1956

chhiskit.set_default_source("shl")   # or set a preference once
chhiskit.list_sources()              # what each source covers

Sources overlay the base table and fall back to it where they are silent, so asking a source for something it never covered warns you rather than quietly handing you someone else's numbers. See Chronology Sources.

📖 Documentation

Build the site locally:

make docs       # serve at http://127.0.0.1:8000
make docs-build # static build

🧪 Development

make test                       # pytest
pre-commit run --all-files      # black + ruff + flake8 + mypy + interrogate
make tox                        # Python 3.10–3.13 matrix

The test file tests/test_dynasties.py is the executable spec — 125 cases organized into one class per behavior cluster, each with a docstring explaining what it pins.

How the shipped data is produced, audited and regenerated is documented for maintainers in data/dynasties/readme.md.

📄 Data attribution

Every modification to the upstream data is recorded row-by-row in dynasty_drops.md, each with a link back to the source record.

🤝 Contributing

PRs welcome. Please:

1. Run pre-commit run --all-files and make test (must pass).
2. New behavior → new test in tests/test_dynasties.py with a docstring describing what it pins.
3. Touching the data? See data/dynasties/readme.md — regenerated artifacts are committed alongside the change so the diff is its own audit trail.

📜 License

MIT — see LICENSE.

👤 Author

SongshGeo · GitHub · Website