# JapaneseDatetime
[](https://github.com/new-village/cnparser/actions/workflows/test.yaml)
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.
```shell
$ python -m pip install jpdatetime
```
### GitHub Install
Installing the latest version from GitHub:
```shell
$ git clone https://github.com/new-village/JapaneseDatetime
$ cd JapaneseDatetime
$ python setup.py install
```
## Usage
```python
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](https://docs.python.org/3/library/datetime.html#format-codes) 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](https://ja.wikipedia.org/wiki/%E5%85%83%E5%8F%B7%E4%B8%80%E8%A6%A7_(%E6%97%A5%E6%9C%AC)).
## License
This project is licensed under the Apache-2.0 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/new-village/JapaneseDatetime",
"name": "jpdatetime",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "new-village",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6a/49/aba6027fed0a0956ba229ef77a0a7d257b3b4eda2d5da358733c72999a3f/jpdatetime-1.5.0.tar.gz",
"platform": null,
"description": "# JapaneseDatetime\n[](https://github.com/new-village/cnparser/actions/workflows/test.yaml)\n\n\nThe `jpdatetime` library extends Python's `datetime` to support Japanese eras (\u5143\u53f7). It allows parsing and formatting dates using Japanese era names like Reiwa (\u4ee4\u548c), Heisei (\u5e73\u6210), and more, including special support for first-year notation (\u5143\u5e74).\n\n## Features\n- **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.\n- **Formatting**: Convert Gregorian dates to Japanese era formatted strings using the `strftime` method.\n- **Supported Eras**: Support for conversion of eras from Reiki (\u970a\u4e80), which began on October 3, 715, to Reiwa (\u4ee4\u548c).\n- **First Year Notation**: Supports the first-year notation (\u5143\u5e74) for each era.\n\n## Installation\n`jpdatetime` is available for installation via pip.\n```shell\n$ python -m pip install jpdatetime\n```\n \n### GitHub Install\nInstalling the latest version from GitHub: \n```shell\n$ git clone https://github.com/new-village/JapaneseDatetime\n$ cd JapaneseDatetime\n$ python setup.py install\n```\n \n## Usage\n```python\nfrom jpdatetime import jpdatetime\n\n# Parsing Japanese era date string to a datetime object\ndate_string = \"\u5e73\u6210\u4e09\u3007\u5e74\u5341\u4e8c\u6708\u4e8c\u56db\u65e5\"\nformat_string = \"%G\u5e74%m\u6708%d\u65e5\"\ndate_obj = jpdatetime.strptime(date_string, format_string)\nprint(date_obj) # Output: 2018-12-24 00:00:00\n\n# Formatting a datetime object to a Japanese era date string\ndate = jpdatetime(2024, 10, 30)\nformatted_date = date.strftime(\"%G\u5e74%m\u6708%d\u65e5\")\nprint(formatted_date) # Output: \"\u4ee4\u548c06\u5e7410\u670830\u65e5\"\n\n# Handling the first year of an era\ndate_string = \"\u4ee4\u548c\u5143\u5e745\u67081\u65e5\"\nformat_string = \"%G\u5e74%m\u6708%d\u65e5\"\ndate_obj = jpdatetime.strptime(date_string, format_string)\nprint(date_obj) # Output: 2019-05-01 00:00:00\n\n# Formatting a datetime object for the first year of an era\ndate = jpdatetime(2019, 5, 1)\nformatted_date = date.strftime(\"%G\u5e74%m\u6708%d\u65e5\")\nprint(formatted_date) # Output: \"\u4ee4\u548c\u5143\u5e745\u67081\u65e5\"\n\n# Using abbreviated era names\ndate_string = \"\u4ee41\u5e7410\u670830\u65e5\"\nformat_string = \"%g\u5e74%m\u6708%d\u65e5\"\ndate_obj = jpdatetime.strptime(date_string, format_string)\nprint(date_obj) # Output: 2019-10-30 00:00:00\n\ndate = jpdatetime(2019, 10, 30)\nformatted_date = date.strftime(\"%g\u5e74%m\u6708%d\u65e5\")\nprint(formatted_date) # Output: \"\u4ee41\u5e7410\u670830\u65e5\"\n\n# Using English era names\ndate_string = \"Heisei 30, April 1\"\nformat_string = \"%E, %B %d\"\ndate_obj = jpdatetime.strptime(date_string, format_string)\nprint(date_obj) # Output: 2018-04-01 00:00:00\n\ndate = jpdatetime(2018, 4, 1)\nformatted_date = date.strftime(\"%E, %B %d\")\nprint(formatted_date) # Output: \"Heisei 30, April 01\"\n\n# Using abbreviated English era names\ndate_string = \"R1/05/01\"\nformat_string = \"%e/%m/%d\"\ndate_obj = jpdatetime.strptime(date_string, format_string)\nprint(date_obj) # Output: 2019-05-01 00:00:00\n\ndate = jpdatetime(2019, 5, 1)\nformatted_date = date.strftime(\"%e/%m/%d\")\nprint(formatted_date) # Output: \"R1/05/01\"\n```\n\n### `strftime()` and `strptime()` Format Codes \n\n| Directive | Meaning | Example |\n|-------------|-------------|-----------------|\n| `%G` | Full Japanese era name with year. Displays \"\u4ee4\u548c\u5143\" for the first year and \"\u5e73\u621030\" for other years. | \u4ee4\u548c\u5143, \u5e73\u621030 |\n| `%-G`/`%#G` | Full Japanese era name with year (without zero-padding). Displays non-zero-padded numbers for other years (e.g., \"\u5e73\u62106\"). | \u4ee4\u548c2, \u5e73\u62106 |\n| `%g` | Abbreviated Japanese era name (first character) with year. Shows \"\u4ee401\" for the first year and zero-padded numbers for other years (e.g., \"\u5e7330\"). | \u4ee401, \u5e7330 |\n| `%-g`/`%#g` | Abbreviated Japanese era name with year (without zero-padding). Shows \"\u4ee41\" for the first year and non-zero-padded numbers for other years (e.g., \"\u5e7330\"). | \u4ee41, \u5e736 |\n| `%E` | Full English era name with year. Displays \"Reiwa 01\" for the first year and \"Heisei 30\" for other years. | Reiwa 01, Heisei 30 |\n| `%-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 |\n| `%e` | Abbreviated English era name (first letter) with year. Shows \"R01\" for the first year and \"H30\" for other years. | R01, H30 |\n| `%-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 |\n\n`%Y`, `%m`, `%d`, `%B`, etc.: [Standard datetime format](https://docs.python.org/3/library/datetime.html#format-codes) specifiers.\n\n## Limitation\n- **Supported Eras**: The library supports Reiki (from October 3, 715) onwards. Eras prior to Reiki are not supported.\n- **Future Eras**: The library does not account for hypothetical future eras not explicitly defined in the eras list.\n- **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.\n\n## Contributing\n\nFeel free to open issues or submit pull requests if you have suggestions or improvements.\n\n## Reference\n\nThe era conversion in this library is based on the [List of Japanese Eras on Wikipedia](https://ja.wikipedia.org/wiki/%E5%85%83%E5%8F%B7%E4%B8%80%E8%A6%A7_(%E6%97%A5%E6%9C%AC)).\n\n## License\n\nThis project is licensed under the Apache-2.0 license.\n",
"bugtrack_url": null,
"license": "Apache-2.0 license",
"summary": "The jpdatetime library extends Python's datetime to support Japanese eras (\u5143\u53f7). It allows parsing and formatting dates in Japanese eras",
"version": "1.5.0",
"project_urls": {
"Homepage": "https://github.com/new-village/JapaneseDatetime"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06856ae7f9b7d49b021c100a3a8be4e5ab4fc7977ccbc9c7fe86736dbbf2d578",
"md5": "fd59f5b7fb054308f6c998f6ed48d2f6",
"sha256": "42fe636d1ccd10d739dadc92beb36c61643c4b196203032725227f8720fbaa5c"
},
"downloads": -1,
"filename": "jpdatetime-1.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd59f5b7fb054308f6c998f6ed48d2f6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18254,
"upload_time": "2024-11-23T13:33:18",
"upload_time_iso_8601": "2024-11-23T13:33:18.455753Z",
"url": "https://files.pythonhosted.org/packages/06/85/6ae7f9b7d49b021c100a3a8be4e5ab4fc7977ccbc9c7fe86736dbbf2d578/jpdatetime-1.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a49aba6027fed0a0956ba229ef77a0a7d257b3b4eda2d5da358733c72999a3f",
"md5": "0963dc10cf8e9d556b9f0848140a01b0",
"sha256": "73d084e0c679af51bf98b175fe3a63641b2153349f2c308c52db9e081b65981e"
},
"downloads": -1,
"filename": "jpdatetime-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "0963dc10cf8e9d556b9f0848140a01b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19053,
"upload_time": "2024-11-23T13:33:19",
"upload_time_iso_8601": "2024-11-23T13:33:19.878127Z",
"url": "https://files.pythonhosted.org/packages/6a/49/aba6027fed0a0956ba229ef77a0a7d257b3b4eda2d5da358733c72999a3f/jpdatetime-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-23 13:33:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "new-village",
"github_project": "JapaneseDatetime",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "jpdatetime"
}
JSON
