tessl/pypi-lunar-python

Comprehensive Chinese lunar calendar library with Solar calendar conversion and traditional Chinese calendar features.

0.89x

Overview

Eval results

Files

Chinese Traditional Elements

Name: tessl/pypi-lunar-python
Rating: 0.79 (1 reviews)
Author: tessl

Traditional Chinese calendar elements including Heavenly Stems and Earthly Branches (Gan-Zhi), Chinese zodiac animals, Five Elements, directional calculations, and auspicious timing elements.

Capabilities

Heavenly Stems and Earthly Branches (干支)

The Gan-Zhi system forms the backbone of Chinese traditional calendar calculations, providing 60-year and 60-day cycles.

class Lunar:
    # Year Gan-Zhi
    def getYearGan(self) -> str: ...  # Year heavenly stem
    def getYearZhi(self) -> str: ...  # Year earthly branch  
    def getYearInGanZhi(self) -> str: ...  # Combined year stem-branch
    
    # Month Gan-Zhi
    def getMonthGan(self) -> str: ...
    def getMonthZhi(self) -> str: ...
    def getMonthInGanZhi(self) -> str: ...
    
    # Day Gan-Zhi
    def getDayGan(self) -> str: ...
    def getDayZhi(self) -> str: ...
    def getDayInGanZhi(self) -> str: ...
    
    # Time Gan-Zhi (2-hour periods)
    def getTimeGan(self) -> str: ...
    def getTimeZhi(self) -> str: ...
    def getTimeInGanZhi(self) -> str: ...

class LunarTime:
    def getGan(self) -> str: ...
    def getZhi(self) -> str: ...
    def getGanZhi(self) -> str: ...

Chinese Zodiac Animals (生肖)

Twelve zodiac animals associated with different time periods.

class Lunar:
    def getYearShengXiao(self) -> str: ...  # Year zodiac animal
    def getMonthShengXiao(self) -> str: ...
    def getDayShengXiao(self) -> str: ...
    def getTimeShengXiao(self) -> str: ...

class LunarTime:
    def getShengXiao(self) -> str: ...

Five Elements and Sound Classifications (五行纳音)

Traditional Five Elements theory and sound classifications for fortune analysis.

class Lunar:
    # NaYin (Sound Classifications) for different periods
    def getYearNaYin(self) -> str: ...
    def getMonthNaYin(self) -> str: ...
    def getDayNaYin(self) -> str: ...
    def getTimeNaYin(self) -> str: ...

class LunarTime:
    def getNaYin(self) -> str: ...

class LunarYear:
    def getYearNaYin(self) -> str: ...

class LunarMonth:
    def getMonthNaYin(self) -> str: ...

Directional Positions and Deity Locations

Calculations for auspicious directions of various deities and spirits.

class Lunar:
    # Deity positions
    def getPositionXi(self) -> str: ...  # Joy god position
    def getPositionYangGui(self) -> str: ...  # Yang noble person position
    def getPositionYinGui(self) -> str: ...  # Yin noble person position
    def getPositionFu(self, sect: int = 2) -> str: ...  # Fortune god position
    def getPositionCai(self, sect: int = 2) -> str: ...  # Wealth god position
    
    # Tai Sui (Grand Duke Jupiter) position
    def getPositionTaiSui(self) -> str: ...
    def getPositionTaiSuiDesc(self) -> str: ...

class LunarTime:
    def getPositionXi(self) -> str: ...
    def getPositionYangGui(self) -> str: ...
    def getPositionYinGui(self) -> str: ...
    def getPositionFu(self, sect: int = 2) -> str: ...
    def getPositionCai(self, sect: int = 2) -> str: ...

class LunarYear:
    def getPositionXi(self) -> str: ...
    def getPositionTaiSui(self) -> str: ...
    def getPositionTaiSuiDesc(self) -> str: ...

Fetal God Positions (胎神)

Traditional calculations for fetal god positions, important for pregnancy and childbirth timing.

class Lunar:
    def getPositionTai(self) -> str: ...  # Fetal god position
    def getPositionTaiDesc(self) -> str: ...  # Fetal god position description

Conflict and Harm Calculations (冲煞害)

Traditional calculations for conflicts, clashes, and harmful directions.

class Lunar:
    # Conflicts (冲)
    def getChong(self) -> str: ...  # What this day conflicts with
    def getChongGan(self) -> str: ...  # Stem conflict
    def getChongGanTie(self) -> str: ...  # Stem conflict binding
    def getChongShengXiao(self) -> str: ...  # Zodiac conflict
    def getChongDesc(self) -> str: ...  # Conflict description
    
    # Harmful direction (煞)
    def getSha(self) -> str: ...

class LunarTime:
    def getChong(self) -> str: ...
    def getChongGan(self) -> str: ...
    def getChongShengXiao(self) -> str: ...
    def getSha(self) -> str: ...

PengZu Taboos (彭祖百忌)

Traditional taboos associated with specific Gan-Zhi combinations.

class Lunar:
    def getPengZuGan(self) -> str: ...  # Stem-related taboo
    def getPengZuZhi(self) -> str: ...  # Branch-related taboo

Auspicious and Inauspicious Activities

Traditional guidance on favorable and unfavorable activities for specific times.

class Lunar:
    def getYi(self) -> list: ...  # Auspicious activities for the day
    def getJi(self) -> list: ...  # Inauspicious activities for the day

class LunarTime:
    def getYi(self) -> list: ...  # Auspicious activities for the time
    def getJi(self) -> list: ...  # Inauspicious activities for the time

Solar Terms (节气)

The 24 solar terms that divide the solar year, crucial for agricultural and traditional timing.

class Lunar:
    def getJieQi(self) -> str: ...  # Current solar term name
    def getNextJie(self, whole_day: bool = False) -> 'JieQi': ...  # Next solar term
    def getPrevJie(self, whole_day: bool = False) -> 'JieQi': ...  # Previous solar term
    def getNextQi(self, whole_day: bool = False) -> 'JieQi': ...  # Next "Qi" type term
    def getPrevQi(self, whole_day: bool = False) -> 'JieQi': ...  # Previous "Qi" type term
    def getNextJieQi(self, whole_day: bool = False) -> 'JieQi': ...  # Next solar term (any type)
    def getPrevJieQi(self, whole_day: bool = False) -> 'JieQi': ...  # Previous solar term (any type)

class JieQi:
    def getName(self) -> str: ...
    def setName(self, name: str): ...
    def getSolar(self) -> 'Solar': ...
    def setSolar(self, solar: 'Solar'): ...
    def isJie(self) -> bool: ...  # Is this a "Jie" (node) term
    def isQi(self) -> bool: ...   # Is this a "Qi" (breath) term
    def toString(self) -> str: ...

Seasonal Calculations

Special seasonal period calculations including winter counting and dog days.

class Lunar:
    def getShuJiu(self) -> 'ShuJiu': ...  # Winter counting period
    def getFu(self) -> 'Fu': ...  # Dog days period

class ShuJiu:
    def getName(self) -> str: ...  # Period name (一九, 二九, etc.)
    def setName(self, name: str): ...
    def getIndex(self) -> int: ...  # Day index within period
    def setIndex(self, index: int): ...
    def toString(self) -> str: ...
    def toFullString(self) -> str: ...

class Fu:
    def getName(self) -> str: ...  # Period name (初伏, 中伏, 末伏)
    def setName(self, name: str): ...
    def getIndex(self) -> int: ...  # Day index within period
    def setIndex(self, index: int): ...
    def toString(self) -> str: ...
    def toFullString(self) -> str: ...

Festivals and Special Days

Traditional lunar and solar festivals and special observances.

class Lunar:
    def getFestivals(self) -> list: ...  # Lunar festivals
    def getOtherFestivals(self) -> list: ...  # Other lunar festivals
    
class Solar:
    def getFestivals(self) -> list: ...  # Solar festivals
    def getOtherFestivals(self) -> list: ...  # Other solar festivals

Usage Examples

Basic Gan-Zhi and Zodiac

from lunar_python import Lunar

lunar = Lunar.fromYmd(2023, 4, 11)

# Get Gan-Zhi for different periods
print(f"Year: {lunar.getYearInGanZhi()}")     # 癸卯
print(f"Month: {lunar.getMonthInGanZhi()}")   # 丁巳  
print(f"Day: {lunar.getDayInGanZhi()}")       # 癸酉
print(f"Time: {lunar.getTimeInGanZhi()}")     # 子

# Get zodiac animals
print(f"Year animal: {lunar.getYearShengXiao()}")   # 兔
print(f"Day animal: {lunar.getDayShengXiao()}")     # 鸡

Directional Calculations

from lunar_python import Lunar

lunar = Lunar.fromYmd(2023, 4, 11)

# Get deity positions
print(f"Joy god: {lunar.getPositionXi()}")        # 巽 (Southeast)
print(f"Fortune god: {lunar.getPositionFu()}")    # 兑 (West)  
print(f"Wealth god: {lunar.getPositionCai()}")    # 离 (South)

# Get fetal god position
print(f"Fetal god: {lunar.getPositionTai()}")     # Position
print(f"Fetal god desc: {lunar.getPositionTaiDesc()}")  # Description

Conflict and Taboo Information

from lunar_python import Lunar

lunar = Lunar.fromYmd(2023, 4, 11)

# Get conflicts
print(f"Conflicts with: {lunar.getChong()}")           # 丁卯
print(f"Conflicting animal: {lunar.getChongShengXiao()}")  # 兔
print(f"Harmful direction: {lunar.getSha()}")          # 东

# Get taboos
print(f"Stem taboo: {lunar.getPengZuGan()}")    # 癸不词讼理弱敌强
print(f"Branch taboo: {lunar.getPengZuZhi()}")  # 酉不会客醉坐颠狂

Auspicious Activities

from lunar_python import Lunar

lunar = Lunar.fromYmd(2023, 4, 11)

# Get daily activities
yi_list = lunar.getYi()  # Auspicious activities
ji_list = lunar.getJi()  # Inauspicious activities

print("Auspicious activities:")
for activity in yi_list:
    print(f"  {activity}")
    
print("Inauspicious activities:")
for activity in ji_list:
    print(f"  {activity}")

Solar Terms

from lunar_python import Lunar

lunar = Lunar.fromYmd(2023, 4, 11)

# Current solar term
current_jieqi = lunar.getJieQi()
print(f"Current solar term: {current_jieqi}")

# Next and previous solar terms
next_jie = lunar.getNextJie()
prev_jie = lunar.getPrevJie()

print(f"Next Jie: {next_jie.getName()} on {next_jie.getSolar().toYmd()}")
print(f"Previous Jie: {prev_jie.getName()} on {prev_jie.getSolar().toYmd()}")

Seasonal Periods

from lunar_python import Lunar

# Winter counting (数九)
winter_lunar = Lunar.fromYmd(2023, 11, 20)  # Winter period
shu_jiu = winter_lunar.getShuJiu()
if shu_jiu:
    print(f"Winter period: {shu_jiu.getName()}, day {shu_jiu.getIndex()}")

# Dog days (三伏)  
summer_lunar = Lunar.fromYmd(2023, 6, 15)  # Summer period
fu = summer_lunar.getFu()
if fu:
    print(f"Dog days period: {fu.getName()}, day {fu.getIndex()}")

Install with Tessl CLI

npx tessl i tessl/pypi-lunar-python