{"id":2988,"library":"lunarcalendar","title":"Lunar Calendar Converter","description":"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.","status":"active","version":"0.0.9","language":"en","source_language":"en","source_url":"https://github.com/wolfhong/LunarCalendar","tags":["calendar","lunar","solar","chinese calendar","holidays","solar terms"],"install":[{"cmd":"pip install LunarCalendar","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for 24-solar-terms calculation. Requires C++ build tools on Windows for installation.","package":"ephem","optional":false}],"imports":[{"symbol":"Converter","correct":"from lunarcalendar import Converter"},{"symbol":"Solar","correct":"from lunarcalendar import Solar"},{"symbol":"Lunar","correct":"from lunarcalendar import Lunar"},{"symbol":"DateNotExist","correct":"from lunarcalendar import DateNotExist"}],"quickstart":{"code":"import datetime\nfrom lunarcalendar import Converter, Solar, Lunar, DateNotExist\n\n# Solar to Lunar conversion\nsolar_date = Solar(2024, 4, 11) # Example: April 11, 2024\nprint(f\"Solar date: {solar_date}\")\nlunar_date = Converter.Solar2Lunar(solar_date)\nprint(f\"Converted Lunar date: {lunar_date}\")\n\n# Lunar to Solar conversion\nlunar_date_example = Lunar(2024, 3, 3) # Example: 3rd day of 3rd lunar month, 2024\nprint(f\"Lunar date: {lunar_date_example}\")\nsolar_date_converted = Converter.Lunar2Solar(lunar_date_example)\nprint(f\"Converted Solar date: {solar_date_converted}\")\n\n# Handling invalid lunar dates\ntry:\n    invalid_lunar = Lunar(2024, 2, 30, isleap=False) # February 30th is invalid in any lunar calendar\nexcept DateNotExist as e:\n    print(f\"Caught expected error for invalid date: {e}\")","lang":"python","description":"Demonstrates converting a solar date to a lunar date and vice-versa, and shows how to handle `DateNotExist` for invalid lunar date inputs."},"warnings":[{"fix":"On Windows, ensure C++ build tools (e.g., from Visual Studio Build Tools) are installed before running `pip install LunarCalendar`.","message":"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'.","severity":"gotcha","affected_versions":"0.0.9 and potentially earlier"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.9"},{"fix":"Wrap lunar date creation (e.g., `Lunar(year, month, day)`) in a `try...except DateNotExist` block to handle impossible dates gracefully.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}