Registry / serialization / korean-lunar-calendar

korean-lunar-calendar

library0.4.0pypypi✓ verified 24d ago

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.

serialization data

pip install korean-lunar-calendar

github ↗package ↗

INSTALL

IMPORT

SIG · KOREAN-LUNAR-CALEN

korean-lunar-calendar

serializationpythonv0.4.0

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.002s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.004s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KoreanLunarCalendar

✓ from korean_lunar_calendar import KoreanLunarCalendar

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']}")

Debug

Known issues

gotchaThe 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).

affects: All versions

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

affects: All versions

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

affects: All versions

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

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'korean_lunar_calendar'

The Python interpreter cannot find the installed library, often due to the package not being installed or a mismatch between the installed package name (using hyphens) and the import statement (using underscores).

fix

Ensure the package is installed correctly and import it using underscores: `pip install korean-lunar-calendar` (for installation) and `from korean_lunar_calendar import KoreanLunarCalendar` (for import).

ImportError: cannot import name 'KoreanLunarCalendar' from 'korean_lunar_calendar'

The class `KoreanLunarCalendar` is either misspelled in the import statement, or it's not directly exposed at the top level of the `korean_lunar_calendar` module.

fix

Verify the capitalization of the class name `KoreanLunarCalendar` and ensure it's imported directly from the module as shown in the documentation: `from korean_lunar_calendar import KoreanLunarCalendar`.

ValueError: date out of range

This error occurs when attempting to convert a date that falls outside the library's supported range (Lunar: 1000-01-01 to 2050-11-18; Solar: 1000-02-13 to 2050-12-31).

fix

Adjust the input date to be within the supported range of the `korean-lunar-calendar` library before calling conversion methods like `setSolarDate()` or `setLunarDate()`.

Upgrade

Version history

0.4.0latest on PyPI · released Jun 15, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

Resources

githubhttps://github.com/usingsky/korean_lunar_calendar_py ↗

packagehttps://pypi.org/project/korean-lunar-calendar/ ↗