korean-lunar-calendar

What it is and what it does

korean_lunar_calendar is a stateful date converter that transforms dates between the Korean lunar calendar (음력) and the Gregorian solar calendar (양력). It bundles the conversion table offline, requires no network calls, and follows the KARI (Korea Astronomy and Space Science Institute) standard—the same astronomical basis as the Chinese lunar calendar, but using Korean-specific intercalation rules. The library handles leap months (윤달), the 1582 Gregorian reform gap, and provides output in both Korean and Chinese sexagenary cycle notation.

You instantiate a KoreanLunarCalendar object, call setSolarDate() or setLunarDate() to set a date (both return a bool to indicate success), and then read the result back in the other calendar via LunarIsoFormat(), SolarIsoFormat(), getGapJaString(), or getChineseGapJaString(). Input validation is strict: out-of-range dates, non-integers, and impossible leap months are rejected. The library has no third-party dependencies and requires Python 3.6 or later.

Use it for:

• Convert Korean holidays and traditional dates (e.g., Lunar New Year) to Gregorian dates for scheduling and calendar applications.
• Display sexagenary cycle strings (GapJa) in Korean or Chinese for cultural or astrological contexts.
• Validate lunar dates in user input and reject impossible or out-of-range dates before processing.
• Build calendar or genealogy tools that work with both lunar and solar date systems.
• Integrate lunar calendar support into event management or historical record systems.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts dates between the Korean lunar calendar and Gregorian solar calendar following the KARI standard, entirely offline with no external dependencies.

Yes. The package is actively maintained, has zero known vulnerabilities, imposes no dependency burden, and solves a specific problem (Korean lunar–solar conversion) with a well-defined, validated API. Install it if you need to work with Korean lunar dates; skip it if you only need Gregorian calendars.

Install

korean-lunar-calendar on PyPI

pip install korean-lunar-calendar

uv add korean-lunar-calendar

poetry add korean-lunar-calendar

Installing korean-lunar-calendar

Before you install

Low friction: pure Python with no runtime dependencies, distributed as a wheel, and actively maintained with a recent release.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open and proprietary projects.

Quickstart

pip install korean_lunar_calendar

from korean_lunar_calendar import KoreanLunarCalendar

calendar = KoreanLunarCalendar()
if calendar.setSolarDate(2017, 6, 24):
    print(calendar.LunarIsoFormat())  # 2017-05-01 Intercalation

Supported date range: lunar 1000-01-01 to 2050-11-18, solar 1000-02-13 to 2050-12-31; dates outside this range will cause setters to return False.

Verify before relying

• Whether the KARI conversion tables are updated annually or on a fixed schedule.
• Performance characteristics for bulk conversions or real-time calendar applications.

Package facts

Evidence: korean_lunar_calendar-0.4.0-py3-none-any.whl

Keywords: calendar, korean, lunar, solar, 음력, 양력, 달력

Tags

More Libraries packages