jpdatetime 1.5.0

The jpdatetime library extends Python's datetime to support Japanese eras (元号). It allows parsing and formatting dates in Japanese eras

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

Directive	Meaning	Example
%G	Full Japanese era name with year. Displays "令和元" for the first year and "平成30" for other years.	令和元, 平成30
%-G/%#G	Full Japanese era name with year (without zero-padding). Displays non-zero-padded numbers for other years (e.g., "平成6").	令和2, 平成6
%g	Abbreviated Japanese era name (first character) with year. Shows "令01" for the first year and zero-padded numbers for other years (e.g., "平30").	令01, 平30
%-g/%#g	Abbreviated Japanese era name with year (without zero-padding). Shows "令1" for the first year and non-zero-padded numbers for other years (e.g., "平30").	令1, 平6
%E	Full English era name with year. Displays "Reiwa 01" for the first year and "Heisei 30" for other years.	Reiwa 01, Heisei 30
%-E/%#E	Full English era name with year (without zero-padding). Displays "Reiwa 1" for the first year and non-zero-padded numbers for other years (e.g., "Heisei 30").	Reiwa 1, Heisei 30
%e	Abbreviated English era name (first letter) with year. Shows "R01" for the first year and "H30" for other years.	R01, H30
%-e/%#e	Abbreviated English era name with year (without zero-padding). Shows "R1" for the first year and non-zero-padded numbers for other years (e.g., "H30").	R1, H30

%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.