Lunar Calendar Converter

0.0.9 · active · verified Sat Apr 11

LunarCalendar is a Python library for converting between solar (Gregorian) and lunar calendars, primarily focused on the Chinese lunisolar calendar. It includes support for 24 solar terms and numerous Chinese lunar and solar holidays. The latest stable version on PyPI is 0.0.9, released in 2018. While the PyPI release is older, the project on GitHub appears functional, supporting a time range of 1900 to 2100. It's suitable for applications requiring accurate Chinese calendar calculations.

Warnings

gotcha The underlying 'ephem' dependency, used for 24-solar-terms calculation, requires C++ build tools on Windows. Users might need to install 'Microsoft Build Tools' to successfully install 'LunarCalendar'.
Fix: On Windows, ensure C++ build tools (e.g., from Visual Studio Build Tools) are installed before running `pip install LunarCalendar`.
gotcha The library explicitly supports a time range from 1900 to 2100. Dates outside this range may produce incorrect results or errors. While a `generate.html` is mentioned in the documentation to extend this, it's not a programmatic Python API for direct use.
Fix: Ensure dates are within the 1900-2100 range. For dates outside this range, consider alternative libraries or custom generation methods if the HTML approach is not suitable.
gotcha The PyPI metadata states `requires_python: >=2.7, <4`, indicating compatibility with Python 2.7 and Python 3.x up to (but not including) Python 4. This means it explicitly supports Python 2.7, which is end-of-life and generally not recommended for new development.
Fix: While it works with modern Python 3 versions, be aware of its older compatibility. For new projects, use Python 3.8+ and thoroughly test compatibility if any issues arise, as the project's last update was some time ago.
gotcha Invalid lunar dates (e.g., a month with too many days, or a non-existent leap month) will raise a `DateNotExist` exception. It's crucial to catch this exception when working with user-provided or dynamically generated lunar dates to prevent application crashes.
Fix: Wrap lunar date creation (e.g., `Lunar(year, month, day)`) in a `try...except DateNotExist` block to handle impossible dates gracefully.

Install

pip install LunarCalendar Install stable version

Imports

Converter
```
from lunarcalendar import Converter
```
Solar
```
from lunarcalendar import Solar
```
Lunar
```
from lunarcalendar import Lunar
```
DateNotExist
```
from lunarcalendar import DateNotExist
```

Quickstart

Demonstrates converting a solar date to a lunar date and vice-versa, and shows how to handle `DateNotExist` for invalid lunar date inputs.

import datetime
from lunarcalendar import Converter, Solar, Lunar, DateNotExist

# Solar to Lunar conversion
solar_date = Solar(2024, 4, 11) # Example: April 11, 2024
print(f"Solar date: {solar_date}")
lunar_date = Converter.Solar2Lunar(solar_date)
print(f"Converted Lunar date: {lunar_date}")

# Lunar to Solar conversion
lunar_date_example = Lunar(2024, 3, 3) # Example: 3rd day of 3rd lunar month, 2024
print(f"Lunar date: {lunar_date_example}")
solar_date_converted = Converter.Lunar2Solar(lunar_date_example)
print(f"Converted Solar date: {solar_date_converted}")

# Handling invalid lunar dates
try:
    invalid_lunar = Lunar(2024, 2, 30, isleap=False) # February 30th is invalid in any lunar calendar
except DateNotExist as e:
    print(f"Caught expected error for invalid date: {e}")

view raw JSON →