lunar_python

The lunar_python library is a zero-dependency tool for handling various calendar systems and traditional Chinese astrological data.

Supported features include:

• Calendars: Solar (Gregorian), Lunar (Nongli), Buddhist, and Taoist calendars.
• Astrology & Zodiac: Constellations (Zodiac signs), Sexagenary cycle (Gan-Zhi), Chinese Zodiac (Shengxiao), and Eight Characters (BaZi).
• Traditional Almanac (Huangli): Solar terms (Jieqi), Festivals, Pengzu Baiji, Auspicious gods (Xi-shen, Fu-shen, Cai-shen, etc.), Fetal god directions, Clashes (Chong-sha), and Na Yin.
• Other Metadata: Julian Day, Five Elements (Wu Xing), Ten Gods (Shi Shen), Twelve Jianchu stars, and official holiday/adjustment schedules.

Install the lunar_python package using pip to access solar and lunar calendar utilities including zodiac signs, solar terms, and traditional Chinese almanac features.

$ pip install lunar_python

Use Lunar.fromYmd(year, month, day) to initialize a lunar calendar object from a specific year, month, and day. You can then retrieve the corresponding solar calendar information using the .getSolar() method.

from lunar_python import Lunar

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

# Print the full lunar calendar string
print(lunar.toFullString())

# Convert lunar to solar and print the full solar calendar string
print(lunar.getSolar().toFullString())

Use the Lunar.fromYmd(year, month, day) method to create a Lunar instance from a specific year, month, and day. You can then use toFullString() to get a detailed Chinese Lunar description or getSolar() to convert the instance to a Solar calendar object.

from lunar_python import Lunar

# init lunar by ymd
lunar = Lunar.fromYmd(1986, 4, 21)

# print lunar
print(lunar.toFullString())

# convert to solar and print
print(lunar.getSolar().toFullString())

The Solar class represents a Gregorian calendar date. You can initialize it using several factory methods depending on your available data format.

from lunar_python import Solar
from datetime import datetime

# From year, month, day, hour, minute, second
solar = Solar(2023, 10, 27, 10, 30, 0)

# From a datetime object
dt = datetime(2023, 10, 27, 10, 30, 0)
solar_from_dt = Solar.fromDate(dt)

# From year, month, day
solar_ymd = Solar.fromYmd(2023, 10, 27)

# From year, month, day, hour, minute, second
solar_ymdhms = Solar.fromYmdHms(2023, 10, 27, 10, 30, 0)

Methods for handling time and alternative calendar systems:

• getTime(): Returns a LunarTime object representing the current time of the Lunar instance.
• getTimes(): Returns a list of all 12 LunarTime objects (shichen/double-hours) for the current day.
• getFoto(): Returns the Buddhist calendar (Foto) equivalent of the current lunar date.
• getTao(): Returns the Taoist calendar (Tao) equivalent of the current lunar date.

The LunarTime class provides methods to identify clashes (Chong) and negative influences (Sha) for a specific time:

• getChong(): Returns the Earthly Branch that clashes with the current time.
• getChongGan(): Returns the Heavenly Stem of the clash.
• getChongShengXiao(): Returns the Zodiac sign of the clashing branch.
• getChongDesc(): Returns a formatted description of the clash (e.g., "(甲子)鼠").
• getSha(): Returns the Sha (煞) associated with the current Earthly Branch.
• getXun(): Returns the Xun (旬) the time belongs to.
• getXunKong(): Returns the Xun Kong (旬空) or void period.

from lunar_python import LunarTime

lunar_time = LunarTime.fromYmdHms(2023, 1, 1, 12, 0, 0)

print(f"Clash: {lunar_time.getChongDesc()}")
print(f"Sha: {lunar_time.getSha()}")
print(f"Xun: {lunar_time.getXun()}")
print(f"Xun Kong: {lunar_time.getXunKong()}")

To convert a solar date to its corresponding lunar (Chinese) calendar date, call the getLunar() method on a Solar instance. This returns a Lunar object.

from lunar_python import Solar

solar = Solar(2023, 10, 27)
lunar = solar.getLunar()

The SolarMonth class represents a month in the solar (Gregorian) calendar. You can initialize it directly by providing a year and a month, or use factory methods to create instances from existing date objects or year/month pairs.

from lunar_python import SolarMonth
import datetime

# Initialize with year and month
solar_month = SolarMonth(2023, 10)

# Use fromYm factory method
solar_month_alt = SolarMonth.fromYm(2023, 10)

# Use fromDate factory method with a datetime object
date_obj = datetime.date(2023, 10, 1)
solar_month_date = SolarMonth.fromDate(date_obj)

The Solar class provides several methods to extract metadata about a specific date:

• getWeek(): Returns the day of the week as an integer (0 for Sunday, 1 for Monday, etc.).
• getWeekInChinese(): Returns the day of the week in Chinese characters (e.g., '日', '一').
• getFestivals(): Returns a list of official holidays/festivals occurring on that date.
• getOtherFestivals(): Returns a list of non-official/traditional festivals (e.g., Zhongyuan Festival).
• getXingZuo(): Returns the Western Zodiac sign.
• isLeapYear(): Returns True if the year is a leap year.

solar = Solar(2023, 10, 27)

print(solar.getWeek())           # 5
print(solar.getWeekInChinese())  # 五
print(solar.getFestivals())      # ['...']
print(solar.getXingZuo())       # 天蝎
print(solar.isLeapYear())        # False