Zhdate

1.0 verified Fri May 01 auth: no python

A Python library to convert Chinese Lunar Calendar (农历) to datetime and vice versa. Supports lunar dates from 1900 to 2100. Current version: 1.0. Release cadence is irregular; last release was 2024.

pip install zhdate

Common errors

error ValueError: month must be in 1..12 ↓

cause ZhDate expects month 1-12, not 0-11.

fix

Ensure month is between 1 and 12. For example, use month=1 for January.

error AttributeError: module 'zhdate' has no attribute 'ZhDate' ↓

cause Typo or incorrect import (e.g., `import zhdate` then `zhdate.ZhDate` is correct, but some try `zhdate.zhdate`).

fix

Use from zhdate import ZhDate or import zhdate; zhdate.ZhDate.

Warnings

gotcha ZhDate uses 1-indexed months and days (January = 1), unlike some lunar libraries that use 0-indexed. ↓

fix Always use month=1 for January, day=1 for first day.

gotcha Leap months must be explicitly specified with leap_month=True. The library does not auto-detect leap months. ↓

fix When creating a leap month, pass leap_month=True (e.g., ZhDate(2023, 2, 1, leap_month=True)).

deprecated The from_datetime method may be renamed or behavior changed in future versions. Check changelog. ↓

fix Use ZhDate.from_datetime(date_obj) as documented; watch for alternative static methods.

Imports

ZhDate
```
from zhdate import ZhDate
```

Quickstart

Basic usage: creating ZhDate objects and converting between lunar and Gregorian dates.

from zhdate import ZhDate

# Convert Chinese lunar date to Gregorian date
lunar_date = ZhDate(2024, 1, 1)  # 2024-01-01 in lunar calendar
gregorian_date = lunar_date.to_datetime()
print(gregorian_date)  # Output: 2024-02-10 00:00:00

# Convert Gregorian date to Chinese lunar date
gregorian_dt = datetime.date(2024, 2, 10)
lunar_date = ZhDate.from_datetime(gregorian_dt)
print(lunar_date)  # Output: ZhDate(2024, 1, 1)

# Leap month example
lunar_date_leap = ZhDate(2023, 2, 1, leap_month=True)  # Leap second month
print(lunar_date_leap.to_datetime())