sanmiao 0.2.2

A Python package for date conversion to and from Chinese and Japanese historical calendars

Sanmiao

Chinese, Japanese, and Korean historical date conversion in Python.

Author: Daniel Patrick Morgan (CNRS-CRCAO)

Sanmiao is a Python package for date conversion to and from Chinese, Japanese, and Korean historical calendars (3rd cent. B.C.–20th cent.) written by a historian of astronomy.

GitHub: https://github.com/PotatoSinology/sanmiao

Installation

The easiest way of installing Sanmiao is using pip:

pip install sanmiao

If you prefer Python3, you can use:

pip3 install --user sanmiao

If you have Sanmiao already installed, but want to upgrade to the latest version:

pip3 install -U sanmiao

Using Sanmiao

Sanmiao provides a variety of functions for date conversion, which are aggregated in sanmiao.cjk_date_interpreter(), which is the back-end for the user-friendly Sanmiao web app. The function sanmiao.cjk_date_interpreter() recognises 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:

import sanmiao

user_input = """
獻帝建安十八年二月, 
宋太祖三年四月
1313-12-10, -215-10-14
415, -181
"""
result = sanmiao.cjk_date_interpreter(user_input)
print(result)

Note that Sanmiao uses the astronomical year, where 1 B.C. = 0, 100 B.C. = -99, etc. The function sanmiao.cjk_date_interpreter() has the following parameters and defaults passed to its sub-functions:

result = sanmiao.cjk_date_interpreter(
    user_input,  # User input, accepts strings
            lang='en',  # Language: 'en' (English), 'fr' (French), 'zh' (Chinese), 'ja' (Japanese), 'de' (German). Defaults to 'en' if not specified or invalid.
    jd_out=False,  # Julian Day Number in output reports (vs ISO date string)
    pg=False,  # Proleptic Gregorian calendar
    gs=None,  # Start of Gregorian calendar, defaults to [1582, 10, 15] if None
    tpq=-500,  # Terminus post quem (earliest date), defaults to -500
    taq=2050,  # Terminus ante quem (latest date), defaults to 2050
    civ=None,  # Civilisation/s, defaults to ['c', 'j', 'k'] if None; set to ['c'] for China only, ['j'] for Japan only, ['k'] for Korea only
    sequential=True  # Intelligently fills missing fields in Sinitic date strings from previous ones (when False, proliferate mode finds all candidates for date strings without dynasty, ruler, or era)
    )

Sanmiao works via XML tagging, and its subcomponents are designed to function independantly of sanmiao.cjk_date_interpreter(). The block of functions that handle XML tagging and table extraction are:

# Convert string to XML (if necessary), tag all date elements
xml_string = tag_date_elements(text, civ=civ)

# Consolidate adjacent date elements
xml_string = consolidate_date(xml_string)

# Remove lone dynasties, rulers, and eras
xml_root = remove_lone_tags(xml_string)

# Remove non-date text
xml_root = strip_text(xml_root)

# Load calendar tables
tables = prepare_tables(civ=civ)

# Extract dates using optimized bulk function
xml_string, output_df, implied = extract_date_table_bulk(
    xml_root, implied=implied, pg=pg, gs=gs, lang=lang,
    tpq=tpq, taq=taq, civ=civ, tables=tables, sequential=sequential, proliferate=not sequential
)

Sources

Sanmiao uses historical tables based on those of Zhang Peiyu[^1] and Uchida Masao,[^2] and it is updated to include new archaeological 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. I have supplemented these for the moment with tables from the Buddhist Studies Time Authority Databases for the Sun-Wu, Liu-Shu, Liao, Jin, and Korea.

In future versions, I plan to:

• improve tables and functionalities
• supply supporting textual evidence to table items and, somehow, outputted reports
• provide a concorance and critical comparison of the aforementioned tables, textual evidence, and calculations using contemporary procedure texts
• add Vietnamese tables with the aid of Phạm Vũ Lộc 范武禄
• add Chinese, Japanese, and Vietnamese translations to outputs and to the web app

[^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