LunarCalendar

What it is and what it does

LunarCalendar is a bidirectional converter between lunar and solar calendar systems, primarily designed for Chinese, Korean, Japanese, and Vietnamese calendars. It converts dates in both directions and provides a built-in festival database covering lunar holidays (Chinese New Year, Mid-Autumn Festival, Dragon Boat Festival), solar holidays with variable dates (Mother's Day, Easter), and 24 solar terms. The package validates date legality (e.g., detecting invalid leap months) and supports both simplified and traditional Chinese language output.

The library covers a fixed time range of 1900 to 2100 and depends on python-dateutil, ephem, and pytz for date arithmetic and astronomical calculations. It includes a console command (lunar-find) for quick festival lookups and is designed to be extended with additional festivals and languages through modification of its festival module.

Use it for:

• Convert a Gregorian date to its lunar calendar equivalent for display in Chinese cultural applications.
• Find the solar date of a lunar festival (e.g., Chinese New Year) for a given year.
• Look up the date of a solar term (e.g., Spring Equinox) using the lunar-find command.
• Validate whether a given lunar date is legal before storing or processing it in a calendar system.
• Generate festival calendars for Chinese, Korean, Japanese, or Vietnamese audiences in their native languages.

Worth the install?

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

Converts between lunar and solar calendar dates, and provides access to lunar and solar festivals (including Chinese New Year, Mid-Autumn Festival, Easter, and 24 solar terms) for dates between 1900 and 2100.

Yes, if you need lunar-solar conversion and festival data for dates between 1900 and 2100 and can tolerate dormant maintenance. The package is stable, has no known vulnerabilities, installs easily, and covers a common use case well. Not recommended if you require active maintenance, support for dates outside the 1900–2100 range, or frequent updates to festival definitions.

Install

lunarcalendar on PyPI

pip install lunarcalendar

uv add lunarcalendar

poetry add lunarcalendar

Installing LunarCalendar

Before you install

Low install friction; pure Python wheel with three lightweight runtime dependencies (python-dateutil, ephem, pytz). Dormant maintenance status since June 2018, though the repository remains active with a recent commit in May 2024.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

from lunarcalendar import Converter, Solar, Lunar

solar = Solar(2018, 1, 1)
lunar = Converter.Solar2Lunar(solar)
print(lunar)

Verify before relying

• Whether the 1900–2100 range and embedded festival data are sufficient for your use case without manual extension.
• Whether the dormant maintenance status (no releases since June 2018) poses a risk for your project's long-term compatibility.

Package facts

Evidence: LunarCalendar-0.0.9-py2.py3-none-any.whl

Keywords: lunar calendar, festival, Chinese festivals, 24 solar terms, solar calendar, lunar solar converter, lunisolar calendar

Tags

More Libraries packages