# zh2ru-idterms
中文证件（护照 / 驾驶证）用名词的中俄对照库（SQLite 版）。
内置 `terms.db` 数据库，开箱即用：**地理名词、机构名称（按证件类型区分）、中文姓名拼音转俄文（帕拉第乌斯转写）**。
> 0.1.2 版本特性：
> - 全部存入数据库，不再额外提供Palladius转写，之前版本有错误。
---
## 安装
```bash
pip install zh2ru-idterms
```
无需任何 CLI、无需传入数据库路径，包内已自带 `terms.db`。
---
## 快速使用
```python
from zh2ru_idterms import (
get_place_path,
find_surname_pinyin,
to_palladius_given,
translate_person_name,
find_org,
)
# 1) 地理名词：支持简称或全称
print(get_place_path(province_zh="浙江省")) # {'province': 'Чжэцзян'}
print(get_place_path(province_zh="浙江")) # {'province': 'Чжэцзян'}
print(get_place_path(city_zh="宁波市")) # {'province': 'Чжэцзян', 'city': 'Нинбо'}
print(get_place_path(city_zh="宁波", district_zh="鄞州区"))
# -> {'province': 'Чжэцзян', 'city': 'Нинбо', 'district': 'Иньчжоу'}
# 2) 姓氏：拼音 → 俄文
print(find_surname_pinyin("zhang")) # чжан
# 3) 名（给定拼音 → Palladius 转写）
print(to_palladius_given("xiaoming")) # сяомин
# 4) 中文姓名（拼音形式） → 俄文全名
print(translate_person_name("zhang", "xiaoming"))# Чжан Сяомин
# 5) 机构名称（按证件类型）
print(find_org("国家移民管理局", doc_type="passport"))
# {'name_zh': '国家移民管理局', 'name_ru': 'Государственное управление по делам иммиграции КНР', ...}
```
### `get_place_path` 参数说明
- `province_zh`: 省/自治区/直辖市（**全称或简称**都可，如“浙江省”/“浙江”，“广西壮族自治区”/“广西”）
- `city_zh`: 地级市（可写“宁波市”或“宁波”）
- `district_zh`: 区/县（如“鄞州区”“鄞州”）
支持**部分层级**：
- 只给 `province_zh`：返回 `{province: ...}`
- 给 `city_zh` 不给 `province_zh`：全库搜索城市，若唯一命中，返回省市
- 只给 `district_zh`：全库搜索区县，若唯一命中，返回省市区
> 若同名多地命中（模糊情况），将返回 `None`，请提供更精确的上级以消歧。
---
## API 一览（保持兼容旧用法）
- `get_place_path(province_zh=None, city_zh=None, district_zh=None) -> Optional[dict]`
- `find_surname_pinyin(pinyin: str) -> Optional[str]`
- `to_palladius_given(pinyin_text: str) -> str`
- `translate_person_name(surname_pinyin: str, given_pinyin: str) -> str`
- `find_org(name_zh: str, doc_type: str = "passport", region_zh: Optional[str] = None) -> Optional[dict]`
> 机构：`doc_type` 建议使用 `"passport"` 或 `"driving_licence"`。
---
## 数据库说明
包内置 `data/terms.db`，结构包含：
- `geo_province / geo_city / geo_district`
- `authority_org`（机构，按 `doc_type` 区分）
- `surname_pinyin_rule`（姓：拼音→俄文）
- （可选）`surname_rule / givenname_rule / name_exception`（未必在你的数据集中启用）
> 运行时会检测 `aliases_zh` 列是否存在；不存在时**不影响使用**，仅降级为 `name_zh LIKE` 模糊匹配。
---
## 扩展与自定义数据
如果你有自己的数据导入，请**在外部工具中**导入同名表到你的 SQLite，再替换包内 `terms.db` 即可。
（或在你的程序中通过 `importlib.resources.files('zh2ru_idterms')/'data/terms.db'` 找到路径，进行覆盖。）
---
## 版本记录
- **0.1.1**
- 省份/自治区简称支持（浙江/广西等）
- 兼容无 `aliases_zh` 列的数据库（自动降级匹配）
- 0.1.0
- 初始版本，内置 `terms.db` 与核心 API
---
## 许可证
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "zh2ru-idterms",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Chinese, Russian, Palladius, translation, passport, driving licence, SQLite, toponyms",
"author": "koko",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/48/da/892a04e920e6d2bfd1a96bab8f42c5f91d6f7aeb9c07b02fe3e927b804ea/zh2ru_idterms-0.1.2.tar.gz",
"platform": null,
"description": "\n# zh2ru-idterms\n\n\u4e2d\u6587\u8bc1\u4ef6\uff08\u62a4\u7167 / \u9a7e\u9a76\u8bc1\uff09\u7528\u540d\u8bcd\u7684\u4e2d\u4fc4\u5bf9\u7167\u5e93\uff08SQLite \u7248\uff09\u3002 \n\u5185\u7f6e `terms.db` \u6570\u636e\u5e93\uff0c\u5f00\u7bb1\u5373\u7528\uff1a**\u5730\u7406\u540d\u8bcd\u3001\u673a\u6784\u540d\u79f0\uff08\u6309\u8bc1\u4ef6\u7c7b\u578b\u533a\u5206\uff09\u3001\u4e2d\u6587\u59d3\u540d\u62fc\u97f3\u8f6c\u4fc4\u6587\uff08\u5e15\u62c9\u7b2c\u4e4c\u65af\u8f6c\u5199\uff09**\u3002\n\n> 0.1.2 \u7248\u672c\u7279\u6027\uff1a\n> - \u5168\u90e8\u5b58\u5165\u6570\u636e\u5e93\uff0c\u4e0d\u518d\u989d\u5916\u63d0\u4f9bPalladius\u8f6c\u5199\uff0c\u4e4b\u524d\u7248\u672c\u6709\u9519\u8bef\u3002\n\n---\n\n## \u5b89\u88c5\n\n```bash\npip install zh2ru-idterms\n```\n\n\u65e0\u9700\u4efb\u4f55 CLI\u3001\u65e0\u9700\u4f20\u5165\u6570\u636e\u5e93\u8def\u5f84\uff0c\u5305\u5185\u5df2\u81ea\u5e26 `terms.db`\u3002\n\n---\n\n## \u5feb\u901f\u4f7f\u7528\n\n```python\nfrom zh2ru_idterms import (\n get_place_path,\n find_surname_pinyin,\n to_palladius_given,\n translate_person_name,\n find_org,\n)\n\n# 1) \u5730\u7406\u540d\u8bcd\uff1a\u652f\u6301\u7b80\u79f0\u6216\u5168\u79f0\nprint(get_place_path(province_zh=\"\u6d59\u6c5f\u7701\")) # {'province': '\u0427\u0436\u044d\u0446\u0437\u044f\u043d'}\nprint(get_place_path(province_zh=\"\u6d59\u6c5f\")) # {'province': '\u0427\u0436\u044d\u0446\u0437\u044f\u043d'}\nprint(get_place_path(city_zh=\"\u5b81\u6ce2\u5e02\")) # {'province': '\u0427\u0436\u044d\u0446\u0437\u044f\u043d', 'city': '\u041d\u0438\u043d\u0431\u043e'}\nprint(get_place_path(city_zh=\"\u5b81\u6ce2\", district_zh=\"\u911e\u5dde\u533a\"))\n# -> {'province': '\u0427\u0436\u044d\u0446\u0437\u044f\u043d', 'city': '\u041d\u0438\u043d\u0431\u043e', 'district': '\u0418\u043d\u044c\u0447\u0436\u043e\u0443'}\n\n# 2) \u59d3\u6c0f\uff1a\u62fc\u97f3 \u2192 \u4fc4\u6587\nprint(find_surname_pinyin(\"zhang\")) # \u0447\u0436\u0430\u043d\n\n# 3) \u540d\uff08\u7ed9\u5b9a\u62fc\u97f3 \u2192 Palladius \u8f6c\u5199\uff09\nprint(to_palladius_given(\"xiaoming\")) # \u0441\u044f\u043e\u043c\u0438\u043d\n\n# 4) \u4e2d\u6587\u59d3\u540d\uff08\u62fc\u97f3\u5f62\u5f0f\uff09 \u2192 \u4fc4\u6587\u5168\u540d\nprint(translate_person_name(\"zhang\", \"xiaoming\"))# \u0427\u0436\u0430\u043d \u0421\u044f\u043e\u043c\u0438\u043d\n\n# 5) \u673a\u6784\u540d\u79f0\uff08\u6309\u8bc1\u4ef6\u7c7b\u578b\uff09\nprint(find_org(\"\u56fd\u5bb6\u79fb\u6c11\u7ba1\u7406\u5c40\", doc_type=\"passport\"))\n# {'name_zh': '\u56fd\u5bb6\u79fb\u6c11\u7ba1\u7406\u5c40', 'name_ru': '\u0413\u043e\u0441\u0443\u0434\u0430\u0440\u0441\u0442\u0432\u0435\u043d\u043d\u043e\u0435 \u0443\u043f\u0440\u0430\u0432\u043b\u0435\u043d\u0438\u0435 \u043f\u043e \u0434\u0435\u043b\u0430\u043c \u0438\u043c\u043c\u0438\u0433\u0440\u0430\u0446\u0438\u0438 \u041a\u041d\u0420', ...}\n```\n\n### `get_place_path` \u53c2\u6570\u8bf4\u660e\n\n- `province_zh`: \u7701/\u81ea\u6cbb\u533a/\u76f4\u8f96\u5e02\uff08**\u5168\u79f0\u6216\u7b80\u79f0**\u90fd\u53ef\uff0c\u5982\u201c\u6d59\u6c5f\u7701\u201d/\u201c\u6d59\u6c5f\u201d\uff0c\u201c\u5e7f\u897f\u58ee\u65cf\u81ea\u6cbb\u533a\u201d/\u201c\u5e7f\u897f\u201d\uff09\n- `city_zh`: \u5730\u7ea7\u5e02\uff08\u53ef\u5199\u201c\u5b81\u6ce2\u5e02\u201d\u6216\u201c\u5b81\u6ce2\u201d\uff09\n- `district_zh`: \u533a/\u53bf\uff08\u5982\u201c\u911e\u5dde\u533a\u201d\u201c\u911e\u5dde\u201d\uff09\n\n\u652f\u6301**\u90e8\u5206\u5c42\u7ea7**\uff1a\n- \u53ea\u7ed9 `province_zh`\uff1a\u8fd4\u56de `{province: ...}`\n- \u7ed9 `city_zh` \u4e0d\u7ed9 `province_zh`\uff1a\u5168\u5e93\u641c\u7d22\u57ce\u5e02\uff0c\u82e5\u552f\u4e00\u547d\u4e2d\uff0c\u8fd4\u56de\u7701\u5e02\n- \u53ea\u7ed9 `district_zh`\uff1a\u5168\u5e93\u641c\u7d22\u533a\u53bf\uff0c\u82e5\u552f\u4e00\u547d\u4e2d\uff0c\u8fd4\u56de\u7701\u5e02\u533a\n\n> \u82e5\u540c\u540d\u591a\u5730\u547d\u4e2d\uff08\u6a21\u7cca\u60c5\u51b5\uff09\uff0c\u5c06\u8fd4\u56de `None`\uff0c\u8bf7\u63d0\u4f9b\u66f4\u7cbe\u786e\u7684\u4e0a\u7ea7\u4ee5\u6d88\u6b67\u3002\n\n---\n\n## API \u4e00\u89c8\uff08\u4fdd\u6301\u517c\u5bb9\u65e7\u7528\u6cd5\uff09\n\n- `get_place_path(province_zh=None, city_zh=None, district_zh=None) -> Optional[dict]`\n- `find_surname_pinyin(pinyin: str) -> Optional[str]`\n- `to_palladius_given(pinyin_text: str) -> str`\n- `translate_person_name(surname_pinyin: str, given_pinyin: str) -> str`\n- `find_org(name_zh: str, doc_type: str = \"passport\", region_zh: Optional[str] = None) -> Optional[dict]`\n\n> \u673a\u6784\uff1a`doc_type` \u5efa\u8bae\u4f7f\u7528 `\"passport\"` \u6216 `\"driving_licence\"`\u3002\n\n---\n\n## \u6570\u636e\u5e93\u8bf4\u660e\n\n\u5305\u5185\u7f6e `data/terms.db`\uff0c\u7ed3\u6784\u5305\u542b\uff1a\n\n- `geo_province / geo_city / geo_district`\n- `authority_org`\uff08\u673a\u6784\uff0c\u6309 `doc_type` \u533a\u5206\uff09\n- `surname_pinyin_rule`\uff08\u59d3\uff1a\u62fc\u97f3\u2192\u4fc4\u6587\uff09\n- \uff08\u53ef\u9009\uff09`surname_rule / givenname_rule / name_exception`\uff08\u672a\u5fc5\u5728\u4f60\u7684\u6570\u636e\u96c6\u4e2d\u542f\u7528\uff09\n\n> \u8fd0\u884c\u65f6\u4f1a\u68c0\u6d4b `aliases_zh` \u5217\u662f\u5426\u5b58\u5728\uff1b\u4e0d\u5b58\u5728\u65f6**\u4e0d\u5f71\u54cd\u4f7f\u7528**\uff0c\u4ec5\u964d\u7ea7\u4e3a `name_zh LIKE` \u6a21\u7cca\u5339\u914d\u3002\n\n---\n\n## \u6269\u5c55\u4e0e\u81ea\u5b9a\u4e49\u6570\u636e\n\n\u5982\u679c\u4f60\u6709\u81ea\u5df1\u7684\u6570\u636e\u5bfc\u5165\uff0c\u8bf7**\u5728\u5916\u90e8\u5de5\u5177\u4e2d**\u5bfc\u5165\u540c\u540d\u8868\u5230\u4f60\u7684 SQLite\uff0c\u518d\u66ff\u6362\u5305\u5185 `terms.db` \u5373\u53ef\u3002 \n\uff08\u6216\u5728\u4f60\u7684\u7a0b\u5e8f\u4e2d\u901a\u8fc7 `importlib.resources.files('zh2ru_idterms')/'data/terms.db'` \u627e\u5230\u8def\u5f84\uff0c\u8fdb\u884c\u8986\u76d6\u3002\uff09\n\n---\n\n## \u7248\u672c\u8bb0\u5f55\n\n- **0.1.1**\n - \u7701\u4efd/\u81ea\u6cbb\u533a\u7b80\u79f0\u652f\u6301\uff08\u6d59\u6c5f/\u5e7f\u897f\u7b49\uff09\n - \u517c\u5bb9\u65e0 `aliases_zh` \u5217\u7684\u6570\u636e\u5e93\uff08\u81ea\u52a8\u964d\u7ea7\u5339\u914d\uff09\n- 0.1.0\n - \u521d\u59cb\u7248\u672c\uff0c\u5185\u7f6e `terms.db` \u4e0e\u6838\u5fc3 API\n\n---\n\n## \u8bb8\u53ef\u8bc1\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Chinese\u2192Russian ID terms dictionary (places, authorities, surname/given-name rules) with a bundled SQLite DB.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://pypi.org/project/zh2ru-idterms/",
"Source": "https://pypi.org/project/zh2ru-idterms/"
},
"split_keywords": [
"chinese",
" russian",
" palladius",
" translation",
" passport",
" driving licence",
" sqlite",
" toponyms"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d48d81711805882076bc21966119c0972dfed47f1ca78db9671be8fcee9e6469",
"md5": "11872064f23c717d8ed0bf69de39b9f1",
"sha256": "8e3282caff70414ea743c2e57e9b2bea02ab81eda4884b14aa4e4c16c76ed82e"
},
"downloads": -1,
"filename": "zh2ru_idterms-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "11872064f23c717d8ed0bf69de39b9f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35966,
"upload_time": "2025-08-22T15:52:47",
"upload_time_iso_8601": "2025-08-22T15:52:47.981807Z",
"url": "https://files.pythonhosted.org/packages/d4/8d/81711805882076bc21966119c0972dfed47f1ca78db9671be8fcee9e6469/zh2ru_idterms-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "48da892a04e920e6d2bfd1a96bab8f42c5f91d6f7aeb9c07b02fe3e927b804ea",
"md5": "2c615451fb68185153f61dc9cc2560db",
"sha256": "218b3c7d3b5b4f5e6abc82357b8b8e0cb9ada5374fb77fd63a63d805088a306c"
},
"downloads": -1,
"filename": "zh2ru_idterms-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "2c615451fb68185153f61dc9cc2560db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37663,
"upload_time": "2025-08-22T15:52:50",
"upload_time_iso_8601": "2025-08-22T15:52:50.567977Z",
"url": "https://files.pythonhosted.org/packages/48/da/892a04e920e6d2bfd1a96bab8f42c5f91d6f7aeb9c07b02fe3e927b804ea/zh2ru_idterms-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 15:52:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "zh2ru-idterms"
}
JSON