Metadata-Version: 2.4 Name: korean_lunar_calendar Version: 0.4.0 Summary: Convert the Korean lunar calendar to/from the Gregorian solar calendar (KARI standard). Author-email: Jinil Lee Maintainer-email: Jinil Lee License-Expression: MIT Project-URL: Homepage, https://github.com/usingsky/korean_lunar_calendar_py Project-URL: Repository, https://github.com/usingsky/korean_lunar_calendar_py Project-URL: Issues, https://github.com/usingsky/korean_lunar_calendar_py/issues Keywords: calendar,korean,lunar,solar,음력,양력,달력 Classifier: Development Status :: 5 - Production/Stable Classifier: Intended Audience :: Developers Classifier: Operating System :: OS Independent Classifier: Programming Language :: Python :: 3 Classifier: Topic :: Software Development :: Libraries Requires-Python: >=3.6 Description-Content-Type: text/markdown License-File: LICENSE Dynamic: license-file

korean_lunar_calendar

Convert between the Korean lunar calendar (음력) and the Gregorian solar calendar (양력) — entirely offline, following the KARI (Korea Astronomy and Space Science Institute) standard.

PyPI version MIT license Zero dependencies Live demo

> The Korean and Chinese lunar calendars share the same astronomical basis but can fall on > different dates. This library uses the Korean (KARI) standard. ## Features - **Two-way conversion** — solar → lunar and lunar → solar. - **Offline** — the conversion table is bundled; no network calls, no external services. - **GapJa (간지) strings** — the sexagenary year/month/day in both Korean (정유년 병오월) and Chinese (丁酉年 丙午月). - **Leap-month aware** — handles intercalation months (윤달) and the 1582 Gregorian reform gap. - **Input validation** — every setter returns a `bool`; out-of-range, non-integer, and impossible-leap-month dates are rejected. - **Pure standard library** — no third-party dependencies. ## Supported range | Calendar | From | To | | ------------ | ------------ | ------------ | | Lunar (음력) | `1000-01-01` | `2050-11-18` | | Solar (양력) | `1000-02-13` | `2050-12-31` | Dates outside this range cause the corresponding setter to return `False`. ## Install ```bash pip install korean_lunar_calendar ``` ```python from korean_lunar_calendar import KoreanLunarCalendar ``` ## Usage ### Solar → Lunar (양력 → 음력) ```python calendar = KoreanLunarCalendar() # setSolarDate(year, month, day) -> bool calendar.setSolarDate(2017, 6, 24) print(calendar.LunarIsoFormat()) # 2017-05-01 Intercalation print(calendar.getGapJaString()) # 정유년 병오월 임오일 (윤월) print(calendar.getChineseGapJaString()) # 丁酉年 丙午月 壬午日 (閏月) ``` ### Lunar → Solar (음력 → 양력) ```python calendar = KoreanLunarCalendar() # setLunarDate(year, month, day, isIntercalation) -> bool calendar.setLunarDate(1956, 1, 21, False) print(calendar.SolarIsoFormat()) # 1956-03-03 print(calendar.getGapJaString()) # 병신년 경인월 기사일 # Intercalation (leap) month, e.g. lunar 1727-03-01 (leap) -> solar 1727-04-21 calendar.setLunarDate(1727, 3, 1, True) print(calendar.SolarIsoFormat()) # 1727-04-21 print(calendar.getGapJaString()) # 정미년 갑진월 정사일 (윤월) ``` > Always check the return value of `setSolarDate` / `setLunarDate` before reading the result — > the accessors reflect the **last successful** set call. ## API `KoreanLunarCalendar()` creates a stateful converter. Set a date, then read it back in the other calendar. | Member | Returns | Description | | ------ | ------- | ----------- | | `setSolarDate(year, month, day)` | `bool` | Set a Gregorian date. Returns `False` for out-of-range, non-integer, or nonexistent dates. | | `setLunarDate(year, month, day, isIntercalation)` | `bool` | Set a lunar date. `isIntercalation` requests the leap month; returns `False` if that month has no leap month. | | `LunarIsoFormat()` | `str` | Lunar date as `YYYY-MM-DD`, with ` Intercalation` appended for a leap month. | | `SolarIsoFormat()` | `str` | Solar date as `YYYY-MM-DD`. | | `getGapJaString()` | `str` | Sexagenary cycle in Korean, e.g. `정유년 병오월 임오일 (윤월)`. | | `getChineseGapJaString()` | `str` | Sexagenary cycle in Chinese characters, e.g. `丁酉年 丙午月 壬午日 (閏月)`. | After a successful set you can also read the components directly: `lunarYear`, `lunarMonth`, `lunarDay`, `isIntercalation`, `solarYear`, `solarMonth`, `solarDay`. ## Validation Every setter validates its input and returns a `bool`, so you can branch on the result: ```python calendar = KoreanLunarCalendar() # Rejected -> returns False calendar.setLunarDate(99, 1, 1, False) # before supported range calendar.setSolarDate(2051, 1, 1) # after supported range calendar.setSolarDate(2017, 6, 24.5) # non-integer input calendar.setSolarDate(1582, 10, 8) # skipped by the 1582 Gregorian reform calendar.setLunarDate(2017, 3, 1, True) # month 3 of 2017 has no leap month # Accepted -> returns True calendar.setLunarDate(1000, 1, 1, False) calendar.setSolarDate(2050, 12, 31) ``` ## Tests ```bash python -m unittest -v ``` ## Other languages - **Java** — [usingsky/KoreanLunarCalendar](https://github.com/usingsky/KoreanLunarCalendar) - **Python** — [usingsky/korean_lunar_calendar_py](https://github.com/usingsky/korean_lunar_calendar_py) - **JavaScript** — [usingsky/korean_lunar_calendar_js](https://github.com/usingsky/korean_lunar_calendar_js) ## Acknowledgements Conversion data follows the [KARI (Korea Astronomy and Space Science Institute)](https://astro.kasi.re.kr/) Korean lunar–solar standard. Many thanks to KARI for publishing the reference tables. ## License MIT © [Jinil Lee](https://github.com/usingsky)