JapaneseDatetime

The jpdatetime library extends Python's datetime to support Japanese eras (元号). It allows parsing and formatting dates using Japanese era names like Reiwa (令和), Heisei (平成), and more, including special support for first-year notation (元年).

Features

• Parsing: Convert Japanese era date strings to Gregorian dates using the strptime method. This method supports date strings that include full-width characters and can handle years, months, and days written in kanji numerals.
• Formatting: Convert Gregorian dates to Japanese era formatted strings using the strftime method.
• Supported Eras: Support for conversion of eras from Reiki (霊亀), which began on October 3, 715, to Reiwa (令和).
• First Year Notation: Supports the first-year notation (元年) for each era.

Installation

jpdatetime is available for installation via pip.

$ python -m pip install jpdatetime

GitHub Install

Installing the latest version from GitHub:

$ git clone https://github.com/new-village/JapaneseDatetime
$ cd JapaneseDatetime
$ python setup.py install

Usage

from jpdatetime import jpdatetime

# Parsing Japanese era date string to a datetime object
date_string = "平成三〇年十二月二四日"
format_string = "%G年%m月%d日"
date_obj = jpdatetime.strptime(date_string, format_string)
print(date_obj)  # Output: 2018-12-24 00:00:00

# Formatting a datetime object to a Japanese era date string
date = jpdatetime(2024, 10, 30)
formatted_date = date.strftime("%G年%m月%d日")
print(formatted_date)  # Output: "令和06年10月30日"

# Handling the first year of an era
date_string = "令和元年5月1日"
format_string = "%G年%m月%d日"
date_obj = jpdatetime.strptime(date_string, format_string)
print(date_obj)  # Output: 2019-05-01 00:00:00

# Formatting a datetime object for the first year of an era
date = jpdatetime(2019, 5, 1)
formatted_date = date.strftime("%G年%m月%d日")
print(formatted_date)  # Output: "令和元年5月1日"

# Using abbreviated era names
date_string = "令1年10月30日"
format_string = "%g年%m月%d日"
date_obj = jpdatetime.strptime(date_string, format_string)
print(date_obj)  # Output: 2019-10-30 00:00:00

date = jpdatetime(2019, 10, 30)
formatted_date = date.strftime("%g年%m月%d日")
print(formatted_date)  # Output: "令1年10月30日"

# Using English era names
date_string = "Heisei 30, April 1"
format_string = "%E, %B %d"
date_obj = jpdatetime.strptime(date_string, format_string)
print(date_obj)  # Output: 2018-04-01 00:00:00

date = jpdatetime(2018, 4, 1)
formatted_date = date.strftime("%E, %B %d")
print(formatted_date)  # Output: "Heisei 30, April 01"

# Using abbreviated English era names
date_string = "R1/05/01"
format_string = "%e/%m/%d"
date_obj = jpdatetime.strptime(date_string, format_string)
print(date_obj)  # Output: 2019-05-01 00:00:00

date = jpdatetime(2019, 5, 1)
formatted_date = date.strftime("%e/%m/%d")
print(formatted_date)  # Output: "R1/05/01"

strftime() and strptime() Format Codes

%Y, %m, %d, %B, etc.: Standard datetime format specifiers.

Limitation

• Supported Eras: The library supports Reiki (from October 3, 715) onwards. Eras prior to Reiki are not supported.
• Future Eras: The library does not account for hypothetical future eras not explicitly defined in the eras list.
• Conversion rule of abbrivation Era: When converting from abbreviated era names (such as Rei, Hei, or R, H) to a date-time format, duplicate initial letters may exist among era names. In cases of duplication, the conversion defaults to the newer era.

Contributing

Feel free to open issues or submit pull requests if you have suggestions or improvements.

Reference

The era conversion in this library is based on the List of Japanese Eras on Wikipedia.

License

This project is licensed under the Apache-2.0 license.