lunar_python

What it is and what it does

lunar_python is a zero-dependency calendar library that converts between Gregorian (Western) and Chinese lunar calendars, along with related traditional calendar systems. It computes lunar date components, zodiac animals, stems-and-branches (干支), constellation signs, lucky directions (喜神), festival dates, and other astrological properties. The library is written in pure Python with no external dependencies, making it self-contained but requiring compilation from source during installation.

The package is typically used to display or calculate lunar calendar dates in applications serving Chinese-speaking users, to determine auspicious dates and directions according to traditional practices, or to map between solar and lunar date systems. It supports bidirectional conversion and provides a rich set of computed properties for each date, including festival calendars and traditional fortune-telling attributes.

Use it for:

• Display lunar calendar dates alongside Gregorian dates in applications for Chinese users.
• Determine zodiac animals and astrological properties for a given birth date.
• Calculate auspicious dates and lucky directions for traditional Chinese ceremonies or events.
• Convert between solar and lunar date systems for historical or genealogical records.
• Populate festival and holiday calendars that follow the lunar calendar.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Converts between Gregorian (solar) and Chinese lunar calendars, and computes associated astrological and traditional calendar properties like zodiac signs, stems-and-branches, lucky directions, and festival dates.

Yes, if you need lunar calendar conversion and astrological properties for a Chinese-language or culturally-aware application. The zero-dependency design and permissive MIT license are strong points. However, the high install friction (source-only distribution) and aging maintenance status (last commit 282 days ago) mean you should verify compatibility with your Python version and build environment before committing. No known vulnerabilities.

Install

lunar-python on PyPI

pip install lunar-python

uv add lunar-python

poetry add lunar-python

Installing lunar_python

Before you install

High install friction: the package is distributed as a source tarball with no pre-built wheels, requiring compilation or manual setup. Maintenance status is aging—last commit was 282 days ago, though the repository remains active and has accumulated 646 stars.

License in practice

MIT license is permissive; you may use, modify, and distribute this package freely in commercial or private projects with minimal restriction, provided you retain the license notice.

Quickstart

pip install lunar_python

from lunar_python import Lunar

# Initialize lunar calendar from year, month, day
lunar = Lunar.fromYmd(1986, 4, 21)

# Print full lunar date string
print(lunar.toFullString())

# Convert to solar (Gregorian) and print
print(lunar.getSolar().toFullString())

No runtime dependencies, but source-only distribution may require a C compiler or build tools on some systems.

Verify before relying

• Whether Python version support is truly unspecified or if there is a practical minimum (e.g., Python 3.6+).
• Whether the package works correctly with all modern Python versions or if there are known compatibility issues.
• Performance characteristics when handling large date ranges or bulk conversions.

Package facts

Evidence: lunar_python-1.4.8.tar.gz

Keywords: solar, lunar

Tags

More Utilities packages