lunardate: Chinese Calendar Library

0.2.2 · active · verified Sat Apr 11

lunardate is a Chinese Calendar Library implemented purely in Python. It provides functionalities to convert between solar and lunar dates, handle leap months, and perform date arithmetic. The library is currently at version 0.2.2 and sees infrequent but consistent updates, with recent fixes and year range extensions.

Warnings

gotcha The library is limited to processing years between 1900 and 2099 (inclusive of 1900, exclusive of 2099 for internal calculations). Input or output dates outside this range will raise a ValueError.
Fix: Ensure that all solar and lunar dates used with the library fall within the 1900-2099 range. Consider alternative libraries for dates outside this range.
breaking Earlier versions (e.g., 0.1.x) had a more restricted year range, only supporting up to 2050. Version 0.2.0 extended this range to 2099.
Fix: Upgrade to version 0.2.0 or newer to utilize the extended year range (up to 2099).
breaking Older versions contained bugs related to specific years (e.g., 1899, 1956, 2050) or date comparison logic (`==` operator). These have been addressed in recent patches.
Fix: Always use the latest stable version (0.2.2 or newer) to benefit from bug fixes and ensure accuracy for specific dates and operations.
gotcha The library is licensed under GPLv3. Ensure this license is compatible with your project's licensing requirements before integration.
Fix: Review the GPLv3 license terms to confirm compatibility with your project's legal requirements.

Install

pip install lunardate Install latest version

Imports

LunarDate
```
from lunardate import LunarDate
```

Quickstart

Demonstrates converting between solar and lunar dates, getting the current lunar date, and checking for leap months.

import datetime
from lunardate import LunarDate

# Convert a solar date to a lunar date
lunar_date = LunarDate.fromSolarDate(1976, 10, 1)
print(f"Lunar Date for 1976-10-01: {lunar_date}")
# Expected: LunarDate(1976, 8, 8, 1) (year, month, day, isLeapMonth)

# Convert a lunar date back to a solar date
solar_date = LunarDate(1976, 8, 8, 1).toSolarDate()
print(f"Solar Date for LunarDate(1976, 8, 8, 1): {solar_date}")
# Expected: 1976-10-01

# Get today's lunar date
today_lunar = LunarDate.today()
print(f"Today's Lunar Date: {today_lunar}")

# Check for leap month in a year
leap_month_2023 = LunarDate.leapMonthForYear(2023)
print(f"Leap month for 2023: {leap_month_2023}") # Expected: 2

leap_month_2022 = LunarDate.leapMonthForYear(2022)
print(f"Leap month for 2022: {leap_month_2022}") # Expected: None

view raw JSON →