unihan-etl ·

这是一个用于Unicode汉字统一（UNIHAN）数据库发布的ETL工具。unihan-etl旨在从Unicode网站下载（下载）、解压缩（解压）并将数据库转换为平坦的表格格式或结构化的层次格式。

unihan-etl具有双重用途：作为提供API的Python库，用于以Python对象访问数据，以及作为命令行界面（CLI），用于将数据导出为CSV、JSON或YAML格式。

该工具是CJK相关项目套件cihai的组件。有关类似工具，请参阅libUnihan。

截至v0.31.0版本，unihan-etl与UNIHAN版本15.1.0兼容（发布于2023-09-01，修订版35）。

UNIHAN数据库

UNIHAN数据库通过多个文件组织数据，以下是一个示例

U+3400	kCantonese		jau1
U+3400	kDefinition		(same as U+4E18 丘) hillock or mound
U+3400	kMandarin		qiū
U+3401	kCantonese		tim2
U+3401	kDefinition		to lick; to taste, a mat, bamboo bark
U+3401	kHanyuPinyin		10019.020:tiàn
U+3401	kMandarin		tiàn

值根据其字段类型在形状和结构上有所不同。kHanyuPinyin将Unicode代码点映射到Hànyǔ Dà Zìdiǎn，其中10019.020:tiàn代表一个条目。更复杂的是，还有更多变化

U+5EFE	kHanyuPinyin		10513.110,10514.010,10514.020:gǒng
U+5364	kHanyuPinyin		10093.130:xī,lǔ 74609.020:lǔ,xī

kHanyuPinyin支持用空格分隔的多条目。":"（冒号）将作品中的拼音读法与位置分开。","（逗号）分隔多个条目/读法。这只是数据库中包含的90个字段之一。

表格，"平坦"输出

CSV（默认）

$ unihan-etl

char,ucn,kCantonese,kDefinition,kHanyuPinyin,kMandarin
㐀,U+3400,jau1,(same as U+4E18 丘) hillock or mound,,qiū
㐁,U+3401,tim2,"to lick; to taste, a mat, bamboo bark",10019.020:tiàn,tiàn

使用$ unihan-etl -F yaml --no-expand

- char: 㐀
  kCantonese: jau1
  kDefinition: (same as U+4E18 丘) hillock or mound
  kHanyuPinyin: null
  kMandarin: qiū
  ucn: U+3400
- char: 㐁
  kCantonese: tim2
  kDefinition: to lick; to taste, a mat, bamboo bark
  kHanyuPinyin: 10019.020:tiàn
  kMandarin: tiàn
  ucn: U+3401

在CLI中预览，请尝试tabview或csvlens。

JSON

$ unihan-etl -F json --no-expand

[
  {
    "char": "㐀",
    "ucn": "U+3400",
    "kDefinition": "(same as U+4E18 丘) hillock or mound",
    "kCantonese": "jau1",
    "kHanyuPinyin": null,
    "kMandarin": "qiū"
  },
  {
    "char": "㐁",
    "ucn": "U+3401",
    "kDefinition": "to lick; to taste, a mat, bamboo bark",
    "kCantonese": "tim2",
    "kHanyuPinyin": "10019.020:tiàn",
    "kMandarin": "tiàn"
  }
]

工具

• 在CLI中查看：python-fx，jless或fx。
• 通过CLI进行过滤：jq，jql，gojq。

YAML

$ unihan-etl -F yaml --no-expand

- char: 㐀
  kCantonese: jau1
  kDefinition: (same as U+4E18 丘) hillock or mound
  kHanyuPinyin: null
  kMandarin: qiū
  ucn: U+3400
- char: 㐁
  kCantonese: tim2
  kDefinition: to lick; to taste, a mat, bamboo bark
  kHanyuPinyin: 10019.020:tiàn
  kMandarin: tiàn
  ucn: U+3401

使用yq通过CLI进行过滤。

"结构化"输出

代码点可以包含更多细节，unihan-etl以统一的方式仔细提取这些值。空值被删除。

为了实现这一点，unihan-etl导出到JSON、YAML和python列表/字典。

JSON

$ unihan-etl -F json

[
  {
    "char": "㐀",
    "ucn": "U+3400",
    "kDefinition": ["(same as U+4E18 丘) hillock or mound"],
    "kCantonese": ["jau1"],
    "kMandarin": {
      "zh-Hans": "qiū",
      "zh-Hant": "qiū"
    }
  },
  {
    "char": "㐁",
    "ucn": "U+3401",
    "kDefinition": ["to lick", "to taste, a mat, bamboo bark"],
    "kCantonese": ["tim2"],
    "kHanyuPinyin": [
      {
        "locations": [
          {
            "volume": 1,
            "page": 19,
            "character": 2,
            "virtual": 0
          }
        ],
        "readings": ["tiàn"]
      }
    ],
    "kMandarin": {
      "zh-Hans": "tiàn",
      "zh-Hant": "tiàn"
    }
  }
]

YAML

$ unihan-etl -F yaml

- char: 㐀
  kCantonese:
    - jau1
  kDefinition:
    - (same as U+4E18 丘) hillock or mound
  kMandarin:
    zh-Hans: qiū
    zh-Hant: qiū
  ucn: U+3400
- char: 㐁
  kCantonese:
    - tim2
  kDefinition:
    - to lick
    - to taste, a mat, bamboo bark
  kHanyuPinyin:
    - locations:
        - character: 2
          page: 19
          virtual: 0
          volume: 1
      readings:
        - tiàn
  kMandarin:
    zh-Hans: tiàn
    zh-Hant: tiàn
  ucn: U+3401

特性

• 自动从互联网下载UNIHAN
• 力求与UNIHAN的数据库设计中描述的规范保持一致
• 通过-F导出到JSON、CSV和YAML（需要pyyaml）
• 可通过-f配置导出特定字段
• 考虑到由于Unicode内容而导致的编码冲突
• 作为未来CJK（中文、日文、韩文）数据集的技术验证
• 是cihai（一个CJK库）的核心组件和依赖项
• 支持数据包
• 在YAML、JSON和python字典中扩展多值分隔字段
• 支持>= 3.7和pypy

如果您遇到问题或有疑问，请创建问题。

安装

下载并构建自己的UNIHAN导出

$ pip install --user unihan-etl

或通过pipx

$ pipx install unihan-etl

开发版本

pip:

$ pip install --user --upgrade --pre unihan-etl

pipx:

$ pipx install --suffix=@next 'unihan-etl' --pip-args '\--pre' --force
// Usage: unihan-etl@next load yoursession

用法

unihan-etl通过其命令行参数提供可自定义的构建。

请参阅unihan-etl CLI 参数，了解如何指定列、文件、下载URL和输出目标。

输出CSV，默认格式

$ unihan-etl

输出JSON

$ unihan-etl -F json

输出YAML

$ pip install --user pyyaml
$ unihan-etl -F yaml

仅输出csv中的kDefinition字段

$ unihan-etl -f kDefinition

输出多个字段，用空格分隔

$ unihan-etl -f kCantonese kDefinition

输出到自定义文件

$ unihan-etl --destination ./exported.csv

输出到自定义文件（模板文件扩展名）

$ unihan-etl --destination ./exported.{ext}

请参阅unihan-etl CLI 参数，了解高级用法示例。

代码布局

# cache dir (Unihan.zip is downloaded, contents extracted)
{XDG cache dir}/unihan_etl/

# output dir
{XDG data dir}/unihan_etl/
  unihan.json
  unihan.csv
  unihan.yaml   # (requires pyyaml)

# package dir
unihan_etl/
  core.py    # argparse, download, extract, transform UNIHAN's data
  options.py    # configuration object
  constants.py  # immutable data vars (field to filename mappings, etc)
  expansion.py  # extracting details baked inside of fields
  types.py      # type annotations
  util.py       # utility / helper functions

# test suite
tests/*

API

该包在底层是Python，您可以充分利用其完整的API。示例

>>> from unihan_etl.core import Packager
>>> pkgr = Packager()
>>> hasattr(pkgr.options, 'destination')
True

开发

$ git clone https://github.com/cihai/unihan-etl.git

$ cd unihan-etl

设置开发环境并了解如何贡献。我们在所有cihai项目中使用相同的约定/工具：pytest、sphinx、mypy、ruff、tmuxp和文件监视器助手（例如entr(1)）。

更多信息