Korean Lunar Calendar

0.3.1 · active · verified Thu Apr 09

This Python library provides functionalities to convert between the Gregorian (solar) calendar and the Korean lunisolar calendar, adhering to the standards of the Korea Astronomy and Space Science Institute (KASI). It supports a date range from 1000-01-01 to 2050-11-18 for lunar dates and 1000-02-13 to 2050-12-31 for solar dates. The current version is 0.3.1.

Warnings

gotcha The library has a defined date range for conversions: lunar dates (1000-01-01 to 2050-11-18) and solar dates (1000-02-13 to 2050-12-31). Dates outside this range will cause validation methods to return `False`.
Fix: Ensure input dates fall within the supported range (1000 to 2050).
gotcha The Korean lunisolar calendar can differ from the Chinese lunar calendar by a day or even a month due to time zone differences and calculation methods. This library strictly adheres to Korean Astronomical standards.
Fix: Be aware that results may not align with Chinese lunar calendar calculations. This library is specific to the Korean system.
gotcha When setting a lunar date using `setLunarDate`, you must explicitly specify if the month is intercalary (윤달, `intercalation=True`) or not (`intercalation=False`). Incorrectly setting this boolean will lead to wrong conversion results.
Fix: Always provide the correct `intercalation` boolean parameter when calling `setLunarDate` to ensure accurate conversions.
gotcha The project is currently classified as 'Development Status :: 3 - Alpha' on PyPI. While functional, this status suggests that the API may not be entirely stable, and breaking changes or significant modifications could occur in future minor versions.
Fix: For production systems, monitor releases for potential breaking changes. Consider pinning exact versions to mitigate unexpected updates.

Install

pip install korean-lunar-calendar Install stable version

Imports

KoreanLunarCalendar

from korean_lunar_calendar import KoreanLunarCalendar

Quickstart

Initialize the calendar, then use `setSolarDate` or `setLunarDate` to perform conversions and retrieve results using `getLunarCalendar`, `getSolarCalendar`, `getKoreanGapja`, or `getChineseGapja`.

from korean_lunar_calendar import KoreanLunarCalendar

calendar = KoreanLunarCalendar()

# Convert Solar (Gregorian) to Lunar
calendar.setSolarDate(2017, 6, 24)
lunar_date = calendar.getLunarCalendar()
print(f"Solar 2017-06-24 is Lunar: {lunar_date['year']}-{lunar_date['month']}-{lunar_date['day']} (Intercalation: {lunar_date['intercalation']})")

korean_gapja = calendar.getKoreanGapja()
print(f"Korean GapJa: {korean_gapja['year']} {korean_gapja['month']} {korean_gapja['day']} (Intercalation: {korean_gapja['intercalation']})")

# Convert Lunar to Solar
calendar.setLunarDate(1956, 1, 21, False) # year, month, day, is_intercalary (윤달여부)
solar_date = calendar.getSolarCalendar()
print(f"Lunar 1956-01-21 (not intercalary) is Solar: {solar_date['year']}-{solar_date['month']}-{solar_date['day']}")

view raw JSON →