# Sanmiao
> **Chinese and Japanese historical date conversion in Python**.
Author: Daniel Patrick Morgan (CNRS-CRCAO)
Sanmiao is a Python package for date conversion to and from Chinese and Japanese historical calendars (3rd cent. B.C.–20th cent.) written by a historian of astronomy.
GitHub: [https://github.com/architest/pymeeus](https://github.com/architest/pymeeus)
## Installation
The easiest way of installing Sanmiao is using pip:
```sh
pip install sanmiao
```
If you prefer Python3, you can use:
```sh
pip3 install --user sanmiao
```
If you have Sanmiao already installed, but want to upgrade to the latest version:
```sh
pip3 install -U sanmiao
```
## Using Sanmiao
Sanmiao uses the astronomical year, where 1 B.C. = 0, 100 B.C. = -99, etc. It recognizes years (e.g., 534), Y-M-D date strings (e.g., -99-3-5, 1532-6-4), Julian Day Numbers (e.g., 1684971.5), and Chinese date strings of differing precision and completeness (e.g., "東漢孝獻皇帝劉協建安十八年二月," "太祖元年," or "三年三月甲申"). These should be separated by commas, semicolons, or line breaks:
```Python
import sanmiao
user_input = """
東漢孝獻皇帝劉協建安十八年二月,
宋太祖三年四月
313-12-10,
415, 416, 417
"""
result = sanmiao.cjk_date_interpreter(user_input)
```
## Sources
What distinguishes this date convertor from others is that it uses historical tables based, notably those of Zhang Peiyu[^1] and Uchida Masao,[^2] and it is updated to include new archeological evidence[^3] as well as minor dynasties and reign eras. The tables are based on calculation from contemporary procedure texts (_lifa_ 曆法), eclipses, and recorded dates, and I plan to expand them in future versions to include Korean tables and independantly calculated new moons for minor dynasties running different calendars.
[^1]: Zhang Peiyu 張培瑜, _Sanqianwubai nian liri tianxiang_ 三千五百年曆日天象 (Zhengzhou: Daxiang chubanshe, 1997).
[^2]: Uchida Masao, _Nihon rekijitsu genten_ 日本暦日原典 (Tōkyō : Yūzankaku shuppan , 1975).
[^3]: E.g., Zhang Peiyu 張培瑜, "Genju xinchu liri jiandu shilun Qin he Han chu de lifa" 根据新出歷日簡牘試論秦和漢初的曆法, _Zhongyuan wenwu_ 中原文物 2007.5: 62–77.
## Contributing
The preferred method to contribute is through forking and pull requests:
1. Fork it (<https://github.com/PotatoSinology/sanmiao/fork>)
2. Create your feature branch (`git checkout -b feature/fooBar`)
3. Commit your changes (`git commit -am 'Add some fooBar'`)
4. Push to the branch (`git push origin feature/fooBar`)
5. Create a new Pull Request
Raw data
{
"_id": null,
"home_page": null,
"name": "sanmiao",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "date conversion, Chinese calendar, Japanese calendar, history, history of astronomy, astronomy",
"author": null,
"author_email": "Daniel Patrick Morgan <daniel.morgan@college-de-france.fr>",
"download_url": "https://files.pythonhosted.org/packages/b9/15/c52f254d61da1445ff54df54074659a35005c1bcbe100d00e9c0048282ca/sanmiao-0.1.0.tar.gz",
"platform": null,
"description": "# Sanmiao\n> **Chinese and Japanese historical date conversion in Python**.\n\nAuthor: Daniel Patrick Morgan (CNRS-CRCAO)\n\nSanmiao is a Python package for date conversion to and from Chinese and Japanese historical calendars (3rd cent. B.C.\u201320th cent.) written by a historian of astronomy. \n\nGitHub: [https://github.com/architest/pymeeus](https://github.com/architest/pymeeus)\n\n## Installation\n\nThe easiest way of installing Sanmiao is using pip:\n\n```sh\npip install sanmiao\n```\n\nIf you prefer Python3, you can use:\n\n```sh\npip3 install --user sanmiao\n```\n\nIf you have Sanmiao already installed, but want to upgrade to the latest version:\n\n```sh\npip3 install -U sanmiao\n```\n\n## Using Sanmiao\n\nSanmiao uses the astronomical year, where 1\u00a0B.C. = 0, 100\u00a0B.C. = -99, etc. It recognizes years (e.g., 534), Y-M-D date strings (e.g., -99-3-5, 1532-6-4), Julian Day Numbers (e.g., 1684971.5), and Chinese date strings of differing precision and completeness (e.g., \"\u6771\u6f22\u5b5d\u737b\u7687\u5e1d\u5289\u5354\u5efa\u5b89\u5341\u516b\u5e74\u4e8c\u6708,\" \"\u592a\u7956\u5143\u5e74,\" or \"\u4e09\u5e74\u4e09\u6708\u7532\u7533\"). These should be separated by commas, semicolons, or line breaks:\n\n```Python\nimport sanmiao\n\nuser_input = \"\"\"\n\u6771\u6f22\u5b5d\u737b\u7687\u5e1d\u5289\u5354\u5efa\u5b89\u5341\u516b\u5e74\u4e8c\u6708, \n\u5b8b\u592a\u7956\u4e09\u5e74\u56db\u6708\n313-12-10, \n415, 416, 417\n\"\"\"\nresult = sanmiao.cjk_date_interpreter(user_input)\n```\n## Sources\nWhat distinguishes this date convertor from others is that it uses historical tables based, notably those of Zhang Peiyu[^1] and Uchida Masao,[^2] and it is updated to include new archeological evidence[^3] as well as minor dynasties and reign eras. The tables are based on calculation from contemporary procedure texts (_lifa_ \u66c6\u6cd5), eclipses, and recorded dates, and I plan to expand them in future versions to include Korean tables and independantly calculated new moons for minor dynasties running different calendars.\n\n[^1]: Zhang Peiyu \u5f35\u57f9\u745c, _Sanqianwubai nian liri tianxiang_ \u4e09\u5343\u4e94\u767e\u5e74\u66c6\u65e5\u5929\u8c61 (Zhengzhou: Daxiang chubanshe, 1997).\n[^2]: Uchida Masao, _Nihon rekijitsu genten_ \u65e5\u672c\u66a6\u65e5\u539f\u5178 (T\u014dky\u014d : Y\u016bzankaku shuppan , 1975).\n[^3]: E.g., Zhang Peiyu \u5f35\u57f9\u745c, \"Genju xinchu liri jiandu shilun Qin he Han chu de lifa\" \u6839\u636e\u65b0\u51fa\u6b77\u65e5\u7c21\u7258\u8a66\u8ad6\u79e6\u548c\u6f22\u521d\u7684\u66c6\u6cd5, _Zhongyuan wenwu_ \u4e2d\u539f\u6587\u7269 2007.5: 62\u201377.\n\n## Contributing\n\nThe preferred method to contribute is through forking and pull requests:\n\n1. Fork it (<https://github.com/PotatoSinology/sanmiao/fork>)\n2. Create your feature branch (`git checkout -b feature/fooBar`)\n3. Commit your changes (`git commit -am 'Add some fooBar'`)\n4. Push to the branch (`git push origin feature/fooBar`)\n5. Create a new Pull Request\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for date conversion to and from Chinese and Japanese historical calendars",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/PotatoSinology/sanmiao",
"Issues": "https://github.com/PotatoSinology/sanmiao/issues",
"Repository": "https://github.com/PotatoSinology/sanmiao.git"
},
"split_keywords": [
"date conversion",
" chinese calendar",
" japanese calendar",
" history",
" history of astronomy",
" astronomy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "096d1b12df2b813833decc13e0f0a751b2c651110c69e9bbbd436cdce9662f81",
"md5": "27726951947cf3fd43d93a1f96aac017",
"sha256": "3bfc2a2a381fbd70c31fb12266cb4c6bff7b23eb3aca7dac394ba3baa15e4e3f"
},
"downloads": -1,
"filename": "sanmiao-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27726951947cf3fd43d93a1f96aac017",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 704396,
"upload_time": "2025-08-03T08:04:10",
"upload_time_iso_8601": "2025-08-03T08:04:10.289109Z",
"url": "https://files.pythonhosted.org/packages/09/6d/1b12df2b813833decc13e0f0a751b2c651110c69e9bbbd436cdce9662f81/sanmiao-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b915c52f254d61da1445ff54df54074659a35005c1bcbe100d00e9c0048282ca",
"md5": "383961433ab38634bbc550ab3c1c252c",
"sha256": "6de008dc40b7685cc10efc80916e8c54727172af3644225ea431f963bc086048"
},
"downloads": -1,
"filename": "sanmiao-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "383961433ab38634bbc550ab3c1c252c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 654818,
"upload_time": "2025-08-03T08:04:12",
"upload_time_iso_8601": "2025-08-03T08:04:12.806574Z",
"url": "https://files.pythonhosted.org/packages/b9/15/c52f254d61da1445ff54df54074659a35005c1bcbe100d00e9c0048282ca/sanmiao-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 08:04:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PotatoSinology",
"github_project": "sanmiao",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sanmiao"
}
JSON
