zhdate

What it is and what it does

ZhDate is a Python library for working with Chinese lunar calendar dates. It performs bidirectional conversion between lunar dates and Gregorian datetime objects entirely through local computation, without calling external APIs. The library represents lunar dates as objects with year, month, and day fields, and supports leap months—a feature of the lunar calendar where an extra month is inserted periodically. It also implements arithmetic operations: you can add or subtract days from a lunar date, or subtract two lunar dates to find the number of days between them.

The package is intended for applications that need to work with traditional Chinese dates—such as calendar systems, holiday calculators, or cultural event scheduling. It has no runtime dependencies and operates as a standalone date-conversion utility. However, the package is dormant (last release January 2023, last commit February 2024) and distributes primarily as a macOS ARM64 wheel, creating significant installation friction on other platforms.

Use it for:

• Convert Chinese lunar calendar dates to Gregorian dates for scheduling or calendar applications.
• Calculate the number of days between two lunar dates or between a lunar and gregorian date.
• Generate lunar calendar displays or holiday calendars that recognize traditional Chinese festivals by lunar date.
• Parse or validate lunar date input in applications serving Chinese-speaking users.
• Perform date arithmetic on lunar dates (e.g., 'what lunar date is 30 days from now').

Worth the install?

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

Converts between Chinese lunar calendar dates and Gregorian datetime objects without requiring network access, supporting leap months and date arithmetic.

No, unless you are on macOS ARM64 and specifically need lunar calendar conversion. The high install friction (platform-specific wheel, dormant maintenance, unspecified Python version support) and copyleft license (GPLv3+) make it unsuitable for most projects. If you need lunar calendar support on other platforms, verify that the package builds from source or consider alternatives.

Install

zhdate on PyPI

pip install zhdate

uv add zhdate

poetry add zhdate

Installing zhdate

Before you install

High install friction: the package distributes a pre-built macOS ARM64 wheel as its primary artifact, which will not install on other platforms. Last commit was 2024-02-11 and the project is marked dormant, with no releases since 2023-01-21.

License in practice

Licensed under GPLv3+, a copyleft license requiring that any derivative work or distribution also be licensed under GPL. This restricts use in proprietary or closed-source projects.

Quickstart

from zhdate import ZhDate
from datetime import datetime

# Create lunar date for 2010 lunar year, month 1, day 1
date1 = ZhDate(2010, 1, 1)
print(date1)  # Prints lunar date string

# Convert lunar to gregorian
dt_date1 = date1.to_datetime()

# Convert gregorian to lunar
dt_date2 = datetime(2010, 2, 6)
date2 = ZhDate.from_datetime(dt_date2)

The package distributes a macOS ARM64 wheel; installation on other platforms (Linux, Windows, or non-ARM macOS) may fail or require building from source. Python version requirements are unspecified.

Verify before relying

• Whether the package builds successfully on Linux, Windows, or Intel macOS without the prebuilt wheel
• Minimum and maximum Python versions supported (requires_python is empty in metadata)
• Whether the lunar calendar calculations are accurate for dates outside the 2010–2023 range

Package facts

Evidence: zhdate-1.0.macosx-11.0-arm64.tar.gz

Tags

More Utilities packages