Install & Compatibility
Where this runs
tested against v0.0.9 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.042s · 25MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.038s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Converter
✓ from lunarcalendar import Converter
Solar
✓ from lunarcalendar import Solar
Lunar
✓ from lunarcalendar import Lunar
DateNotExist
✓ from lunarcalendar import DateNotExist
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}")
Debug
Known issues
gotchaThe 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'.fixOn Windows, ensure C++ build tools (e.g., from Visual Studio Build Tools) are installed before running `pip install LunarCalendar`.
affects: 0.0.9 and potentially earlier
gotchaThe 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.fixEnsure 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.
affects: All versions
gotchaThe 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.fixWhile 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.
affects: 0.0.9
gotchaInvalid 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.fixWrap lunar date creation (e.g., `Lunar(year, month, day)`) in a `try...except DateNotExist` block to handle impossible dates gracefully.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'lunarcalendar'
The 'lunarcalendar' package is not installed in the current Python environment or is not accessible by the interpreter. This often occurs when `lunarcalendar` is a dependency of another package (like `prophet`) and fails to install correctly itself.
fixEnsure the package is installed using pip: `pip install lunarcalendar` or `python -m pip install lunarcalendar`.
lunarcalendar.DateNotExist: The lunar date does not exist.
This error occurs when attempting to create or convert to a lunar date that is astronomically or calendrically invalid, such as a non-existent leap month for a given year or an invalid day within a specific lunar month.
fixVerify the input date components (year, month, day, isleap) are valid according to Chinese lunisolar calendar rules and fall within the library's supported range (1900-2100).
AttributeError: 'Solar' object has no attribute '...' (or 'Lunar' object)
This typically means you are trying to access an attribute or call a method on a `Solar` or `Lunar` date object that does not exist or is not publicly exposed. For example, trying to access a date component like `day` via `get_day()` instead of directly as `lunar.day`.
fixConsult the `lunarcalendar` library's documentation or source code to confirm the correct attribute names (e.g., `.year`, `.month`, `.day`, `.isleap`) and available methods for `Solar` and `Lunar` objects, and for the `Converter` class (e.g., `Converter.Solar2Lunar`).
Upgrade
Version history
0.0.9latest on PyPI · released Jun 13, 2018
Audit
Dependencies
ephemrequiredUsed for 24-solar-terms calculation. Requires C++ build tools on Windows for installation.