CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-lunar-python

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

79

0.89x
Overview
Eval results
Files

religious-calendars.mddocs/

Buddhist and Taoist Calendars

Specialized calendar systems for Buddhist (Foto) and Taoist (Tao) traditions, providing religious festival calculations, fasting days, and spiritual observances according to traditional Chinese religious practices.

Capabilities

Buddhist Calendar (佛历)

Traditional Buddhist calendar system with comprehensive festival and observance calculations.

class Foto:
    @staticmethod
    def fromLunar(lunar: 'Lunar') -> 'Foto': ...
    
    def getLunar(self) -> 'Lunar': ...  # Get associated lunar date

Buddhist Festivals

Calculation of traditional Buddhist festivals and important observance days.

class Foto:
    def getFestivals(self) -> list: ...  # List of FotoFestival objects for this date
    def getOtherFestivals(self) -> list: ...  # Other Buddhist observances

class FotoFestival:
    def __init__(self, name: str, result: str = None): ...
    
    def getName(self) -> str: ...  # Festival name
    def setName(self, name: str): ...
    def getResult(self) -> str: ...  # Festival description/result
    def setResult(self, result: str): ...
    def toString(self) -> str: ...

Buddhist Constellations (星宿)

Traditional 28 constellation system used in Buddhist calendar calculations.

class Foto:
    def getXiu(self) -> str: ...  # Current constellation name
    def getXiuLuck(self) -> str: ...  # Constellation luck classification
    def getXiuSong(self) -> str: ...  # Constellation verse/song
    def getZheng(self) -> str: ...  # Government/direction
    def getAnimal(self) -> str: ...  # Associated animal
    def getGong(self) -> str: ...  # Palace/location
    def getShou(self) -> str: ...  # Guardian/protector

Buddhist String Representation

class Foto:
    def toString(self) -> str: ...  # Basic Buddhist date string
    def toFullString(self) -> str: ...  # Complete Buddhist calendar description

Taoist Calendar (道历)

Traditional Taoist calendar system for Taoist festivals and spiritual observances.

class Tao:
    @staticmethod
    def fromLunar(lunar: 'Lunar') -> 'Tao': ...
    
    def getLunar(self) -> 'Lunar': ...  # Get associated lunar date

Taoist Festivals

Calculation of traditional Taoist festivals and important spiritual observance days.

class Tao:
    def getFestivals(self) -> list: ...  # List of TaoFestival objects for this date

class TaoFestival:
    def __init__(self, name: str, result: str = None): ...
    
    def getName(self) -> str: ...  # Festival name  
    def setName(self, name: str): ...
    def getResult(self) -> str: ...  # Festival description/result
    def setResult(self, result: str): ...
    def toString(self) -> str: ...

Taoist String Representation

class Tao:
    def toString(self) -> str: ...  # Basic Taoist date string
    def toFullString(self) -> str: ...  # Complete Taoist calendar description

Religious Calendar Utilities

Utility functions for Buddhist and Taoist calendar calculations.

Buddhist Utilities (FotoUtil)

class FotoUtil:
    # Buddhist constellation calculation
    @staticmethod
    def getXiu(month: int, day: int) -> str: ...
    
    # Fasting day calculations
    @staticmethod
    def getDayYi(monthGanZhi: str, dayGanZhi: str) -> list: ...
    @staticmethod
    def getDayJi(monthGanZhi: str, dayGanZhi: str) -> list: ...

Taoist Utilities (TaoUtil)

class TaoUtil:
    # Taoist festival calculations
    @staticmethod
    def getFestival(month: int, day: int) -> list: ...

Usage Examples

Basic Buddhist Calendar Usage

from lunar_python import Lunar, Foto

# Create lunar date
lunar = Lunar.fromYmd(2023, 4, 8)  # Traditional Buddha's Birthday

# Get Buddhist calendar equivalent
foto = Foto.fromLunar(lunar)

print("=== Buddhist Calendar ===")
print(f"Buddhist date: {foto.toString()}")
print(f"Full description: {foto.toFullString()}")

# Get Buddhist festivals
festivals = foto.getFestivals()
if festivals:
    print("\nBuddhist Festivals:")
    for festival in festivals:
        print(f"  {festival.getName()}: {festival.getResult()}")

other_festivals = foto.getOtherFestivals()
if other_festivals:
    print("\nOther Buddhist Observances:")
    for festival in other_festivals:
        print(f"  {festival.getName()}: {festival.getResult()}")

Buddhist Constellation Analysis

from lunar_python import Lunar, Foto

lunar = Lunar.fromYmd(2023, 4, 11)
foto = Foto.fromLunar(lunar)

print("=== Buddhist Constellation Analysis ===")
print(f"Constellation (星宿): {foto.getXiu()}")
print(f"Luck classification: {foto.getXiuLuck()}")
print(f"Constellation verse: {foto.getXiuSong()}")
print(f"Direction: {foto.getZheng()}")
print(f"Associated animal: {foto.getAnimal()}")
print(f"Palace: {foto.getGong()}")
print(f"Guardian: {foto.getShou()}")

Basic Taoist Calendar Usage

from lunar_python import Lunar, Tao

# Create lunar date
lunar = Lunar.fromYmd(2023, 1, 9)  # Jade Emperor's Birthday

# Get Taoist calendar equivalent
tao = Tao.fromLunar(lunar)

print("=== Taoist Calendar ===")
print(f"Taoist date: {tao.toString()}")
print(f"Full description: {tao.toFullString()}")

# Get Taoist festivals
festivals = tao.getFestivals()
if festivals:
    print("\nTaoist Festivals:")
    for festival in festivals:
        print(f"  {festival.getName()}: {festival.getResult()}")

Religious Festival Survey

from lunar_python import Lunar, Foto, Tao

# Survey a date for all religious observances
lunar = Lunar.fromYmd(2023, 4, 8)

print(f"=== Religious Observances for {lunar.toString()} ===")

# Buddhist observances
foto = Foto.fromLunar(lunar)
buddhist_festivals = foto.getFestivals() + foto.getOtherFestivals()
if buddhist_festivals:
    print("\nBuddhist:")
    for festival in buddhist_festivals:
        print(f"  • {festival.getName()}")

# Taoist observances  
tao = Tao.fromLunar(lunar)
taoist_festivals = tao.getFestivals()
if taoist_festivals:
    print("\nTaoist:")
    for festival in taoist_festivals:
        print(f"  • {festival.getName()}")

# If no religious festivals
if not buddhist_festivals and not taoist_festivals:
    print("\nNo major religious festivals on this date.")

Monthly Religious Calendar

from lunar_python import Lunar, Foto, Tao, LunarMonth

# Get all religious festivals in a lunar month
lunar_month = LunarMonth.fromYm(2023, 4)  # 4th lunar month
days_in_month = lunar_month.getDayCount()

print(f"=== Religious Calendar for Lunar Month 4, 2023 ===")

religious_days = []

for day in range(1, days_in_month + 1):
    lunar = Lunar.fromYmd(2023, 4, day)
    
    # Check Buddhist festivals
    foto = Foto.fromLunar(lunar)
    buddhist = foto.getFestivals() + foto.getOtherFestivals()
    
    # Check Taoist festivals
    tao = Tao.fromLunar(lunar)  
    taoist = tao.getFestivals()
    
    if buddhist or taoist:
        religious_days.append({
            'day': day,
            'lunar': lunar,
            'buddhist': buddhist,
            'taoist': taoist
        })

# Display religious days
for info in religious_days:
    print(f"\nDay {info['day']} ({info['lunar'].getSolar().toYmd()}):")
    
    if info['buddhist']:
        print("  Buddhist:")
        for festival in info['buddhist']:
            print(f"    • {festival.getName()}")
    
    if info['taoist']:
        print("  Taoist:")
        for festival in info['taoist']:
            print(f"    • {festival.getName()}")

Constellation Cycle Analysis

from lunar_python import Lunar, Foto

# Analyze constellation changes over a period
print("=== 28-Day Constellation Cycle ===")

base_lunar = Lunar.fromYmd(2023, 4, 1)

for i in range(28):  # 28 constellations
    current_lunar = base_lunar.next(i)
    foto = Foto.fromLunar(current_lunar)
    
    constellation = foto.getXiu()
    luck = foto.getXiuLuck()
    animal = foto.getAnimal()
    
    print(f"Day {i+1:2d}: {constellation:3s} ({luck:2s}) - {animal}")

Religious Calendar Integration

from lunar_python import Lunar, Foto, Tao

def get_religious_info(lunar_date):
    """Get comprehensive religious calendar information."""
    
    # Basic date info
    solar = lunar_date.getSolar()
    print(f"Date: {solar.toYmd()} ({lunar_date.toString()})")
    
    # Buddhist calendar
    foto = Foto.fromLunar(lunar_date)
    print(f"Buddhist: {foto.toFullString()}")
    
    buddhist_festivals = foto.getFestivals() + foto.getOtherFestivals()
    if buddhist_festivals:
        print("  Festivals:")
        for festival in buddhist_festivals:
            print(f"    {festival.getName()}")
    
    # Taoist calendar
    tao = Tao.fromLunar(lunar_date)
    print(f"Taoist: {tao.toFullString()}")
    
    taoist_festivals = tao.getFestivals()
    if taoist_festivals:
        print("  Festivals:")
        for festival in taoist_festivals:
            print(f"    {festival.getName()}")

# Example usage
lunar = Lunar.fromYmd(2023, 4, 8)  # Buddha's Birthday
get_religious_info(lunar)

Fasting Day Calculations

from lunar_python import Lunar, Foto
from lunar_python.util import FotoUtil

# Traditional Buddhist fasting days (1st, 8th, 14th, 15th, 18th, 23rd, 24th, 28th-30th)
def is_buddhist_fasting_day(lunar_date):
    """Check if a lunar date is a traditional Buddhist fasting day."""
    day = lunar_date.getDay()
    
    # Common fasting days
    fasting_days = [1, 8, 14, 15, 18, 23, 24]
    
    # End of month fasting days (varies by month length)
    lunar_month = lunar_date.getMonth()
    lunar_year = lunar_date.getYear()
    from lunar_python import LunarMonth
    month_obj = LunarMonth.fromYm(lunar_year, lunar_month)
    days_in_month = month_obj.getDayCount()
    
    if days_in_month == 29:
        fasting_days.extend([28, 29])
    else:  # 30 days
        fasting_days.extend([28, 29, 30])
    
    return day in fasting_days

# Check several dates
test_dates = [
    Lunar.fromYmd(2023, 4, 1),   # 1st - fasting day
    Lunar.fromYmd(2023, 4, 8),   # 8th - fasting day  
    Lunar.fromYmd(2023, 4, 15),  # 15th - fasting day
    Lunar.fromYmd(2023, 4, 16),  # 16th - not fasting day
]

print("=== Buddhist Fasting Day Analysis ===")
for lunar in test_dates:
    is_fasting = is_buddhist_fasting_day(lunar)
    status = "Fasting Day" if is_fasting else "Regular Day"
    print(f"{lunar.toString()} - {status}")

Install with Tessl CLI

npx tessl i tessl/pypi-lunar-python

docs

core-calendar.md

fortune-telling.md

index.md

religious-calendars.md

traditional-elements.md

utilities.md

tile.json