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

core-calendar.mddocs/

Core Calendar Conversion

Primary functionality for converting between Solar (Gregorian) and Lunar (Chinese) calendar systems. Provides comprehensive date manipulation, formatting, and time period calculations.

Capabilities

Solar Calendar Class

Represents a solar (Gregorian) calendar date with full conversion and manipulation capabilities.

class Solar:
    def __init__(self, solar_year: int, solar_month: int, solar_day: int, 
                 solar_hour: int = 0, solar_minute: int = 0, solar_second: int = 0): ...
    
    @staticmethod
    def fromYmd(year: int, month: int, day: int) -> 'Solar': ...
    
    @staticmethod
    def fromYmdHms(year: int, month: int, day: int, hour: int, minute: int, second: int) -> 'Solar': ...
    
    @staticmethod
    def fromDate(date) -> 'Solar': ...
    
    @staticmethod
    def fromJulianDay(julian_day: float) -> 'Solar': ...
    
    @staticmethod
    def fromBaZi(year_gan_zhi: str, month_gan_zhi: str, day_gan_zhi: str, 
                 time_gan_zhi: str, sect: int = 2, base_year: int = 1900) -> 'Solar': ...

Date Properties and Getters

class Solar:
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...
    def getDay(self) -> int: ...
    def getHour(self) -> int: ...
    def getMinute(self) -> int: ...
    def getSecond(self) -> int: ...
    
    def getWeek(self) -> int: ...  # 0=Sunday, 1=Monday, etc.
    def getWeekInChinese(self) -> str: ...
    def getXingZuo(self) -> str: ...  # Zodiac sign
    def getJulianDay(self) -> int: ...

Calendar Conversion

class Solar:
    def getLunar(self) -> 'Lunar': ...
    def isLeapYear(self) -> bool: ...

Date Arithmetic

class Solar:
    def next(self, days: int, only_work_day: bool = False) -> 'Solar': ...
    def nextYear(self, years: int) -> 'Solar': ...
    def nextMonth(self, months: int) -> 'Solar': ...
    def nextHour(self, hours: int) -> 'Solar': ...
    
    def subtract(self, solar: 'Solar') -> int: ...  # Days difference
    def subtractMinute(self, solar: 'Solar') -> int: ...  # Minutes difference
    
    def isAfter(self, solar: 'Solar') -> bool: ...
    def isBefore(self, solar: 'Solar') -> bool: ...

Festivals and Events

class Solar:
    def getFestivals(self) -> list: ...  # Official festivals
    def getOtherFestivals(self) -> list: ...  # Unofficial festivals

String Formatting

class Solar:
    def toString(self) -> str: ...  # Basic date string
    def toYmd(self) -> str: ...  # YYYY-MM-DD format
    def toYmdHms(self) -> str: ...  # YYYY-MM-DD HH:MM:SS format
    def toFullString(self) -> str: ...  # Complete descriptive format

Lunar Calendar Class

Represents a lunar (Chinese traditional) calendar date with comprehensive traditional features.

class Lunar:
    def __init__(self, lunar_year: int, lunar_month: int, lunar_day: int,
                 hour: int = 0, minute: int = 0, second: int = 0): ...
    
    @staticmethod
    def fromYmd(lunar_year: int, lunar_month: int, lunar_day: int) -> 'Lunar': ...
    
    @staticmethod
    def fromYmdHms(lunar_year: int, lunar_month: int, lunar_day: int,
                   hour: int, minute: int, second: int) -> 'Lunar': ...
    
    @staticmethod
    def fromDate(date) -> 'Lunar': ...
    
    @staticmethod
    def fromSolar(solar: 'Solar') -> 'Lunar': ...

Date Properties and Getters

class Lunar:
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...
    def getDay(self) -> int: ...
    def getHour(self) -> int: ...
    def getMinute(self) -> int: ...
    def getSecond(self) -> int: ...
    
    def isLeapMonth(self) -> bool: ...  # Is current month a leap month
    def getWeek(self) -> int: ...  # Day of week (0=Sunday)
    def getWeekInChinese(self) -> str: ...  # Chinese day of week
    def getSeason(self) -> str: ...  # Get season name

Calendar Conversion

class Lunar:
    def getSolar(self) -> 'Solar': ...

Chinese Formatting

class Lunar:
    def getYearInChinese(self) -> str: ...  # e.g., "二〇二三"
    def getMonthInChinese(self) -> str: ...  # e.g., "四月"
    def getDayInChinese(self) -> str: ...  # e.g., "十一"

Date Arithmetic

class Lunar:
    def next(self, days: int) -> 'Lunar': ...

String Formatting

class Lunar:
    def toString(self) -> str: ...  # Basic lunar date
    def toFullString(self) -> str: ...  # Complete traditional format with all elements

Solar Time Period Classes

Helper classes for working with solar calendar time periods.

class SolarYear:
    @staticmethod
    def fromYear(year: int) -> 'SolarYear': ...
    @staticmethod
    def fromDate(date) -> 'SolarYear': ...
    
    def getYear(self) -> int: ...
    def getMonths(self) -> list: ...  # List of SolarMonth objects
    def next(self, years: int) -> 'SolarYear': ...

class SolarMonth:
    @staticmethod
    def fromYm(year: int, month: int) -> 'SolarMonth': ...
    @staticmethod
    def fromDate(date) -> 'SolarMonth': ...
    
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...
    def getDays(self) -> list: ...  # List of Solar objects
    def getWeeks(self, start: int) -> list: ...  # List of SolarWeek objects
    def next(self, months: int) -> 'SolarMonth': ...

class SolarWeek:
    @staticmethod
    def fromDate(date, start: int) -> 'SolarWeek': ...
    @staticmethod
    def fromYmd(year: int, month: int, day: int, start: int) -> 'SolarWeek': ...
    
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...
    def getDay(self) -> int: ...
    def getWeek(self) -> int: ...  # Week of year
    def getStart(self) -> int: ...  # Start day (0=Sunday, 1=Monday)
    def getDays(self) -> list: ...  # List of 7 Solar objects
    def next(self, weeks: int, sep_month: bool = True) -> 'SolarWeek': ...

class SolarSeason:
    @staticmethod
    def fromYm(year: int, month: int) -> 'SolarSeason': ...
    @staticmethod
    def fromDate(date) -> 'SolarSeason': ...
    
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...  # Starting month of season
    def getIndex(self) -> int: ...  # Season index (0-3)
    def getMonths(self) -> list: ...  # List of 3 SolarMonth objects
    def next(self, seasons: int) -> 'SolarSeason': ...

class SolarHalfYear:
    @staticmethod
    def fromYm(year: int, month: int) -> 'SolarHalfYear': ...
    @staticmethod
    def fromDate(date) -> 'SolarHalfYear': ...
    
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...  # Starting month of half year
    def getIndex(self) -> int: ...  # Half year index (0-1)
    def getMonths(self) -> list: ...  # List of 6 SolarMonth objects
    def getSeasons(self) -> list: ...  # List of 2 SolarSeason objects
    def next(self, half_years: int) -> 'SolarHalfYear': ...

Lunar Time Period Classes

Helper classes for working with lunar calendar time periods.

class LunarYear:
    @staticmethod
    def fromYear(lunar_year: int) -> 'LunarYear': ...
    
    def getYear(self) -> int: ...
    def getDayCount(self) -> int: ...  # Total days in lunar year
    def getMonths(self) -> list: ...  # List of LunarMonth objects
    def getLeapMonth(self) -> int: ...  # Leap month number (0 if none)
    def getMonth(self, lunar_month: int) -> 'LunarMonth': ...
    def next(self, n: int) -> 'LunarYear': ...

class LunarMonth:
    @staticmethod
    def fromYm(lunar_year: int, lunar_month: int) -> 'LunarMonth': ...
    
    def getYear(self) -> int: ...
    def getMonth(self) -> int: ...
    def isLeap(self) -> bool: ...
    def getDayCount(self) -> int: ...  # Number of days in month
    def getFirstJulianDay(self) -> int: ...
    def next(self, n: int) -> 'LunarMonth': ...

class LunarTime:
    @staticmethod
    def fromYmdHms(lunar_year: int, lunar_month: int, lunar_day: int,
                   hour: int, minute: int, second: int) -> 'LunarTime': ...
    
    def getMinHm(self) -> str: ...  # Start time in HH:MM format
    def getMaxHm(self) -> str: ...  # End time in HH:MM format

Holiday Information

Helper class for working with official holidays and work days.

class Holiday:
    def __init__(self, day: str, name: str, work: bool, target: str): ...
    # day: date in YYYY-MM-DD format
    # name: holiday name
    # work: whether it's a make-up work day  
    # target: associated holiday date
    
    def getDay(self) -> str: ...  # Holiday date (YYYY-MM-DD)
    def getName(self) -> str: ...  # Holiday name
    def isWork(self) -> bool: ...  # Is this a make-up work day
    def getTarget(self) -> str: ...  # Associated holiday date
    def toString(self) -> str: ...

Constants

# Julian day constant for 2000-1-1
Solar.J2000 = 2451545

# Month constants
SolarYear.MONTH_COUNT = 12

Usage Examples

Basic Conversion

from lunar_python import Solar, Lunar

# Create solar date and convert to lunar
solar = Solar.fromYmd(2023, 5, 29)
lunar = solar.getLunar()
print(f"Solar: {solar.toFullString()}")
print(f"Lunar: {lunar.toFullString()}")

# Create lunar date and convert to solar  
lunar = Lunar.fromYmd(2023, 4, 11)
solar = lunar.getSolar()
print(f"Lunar: {lunar.toString()}")
print(f"Solar: {solar.toString()}")

Date Arithmetic

from lunar_python import Solar

solar = Solar.fromYmd(2023, 5, 29)

# Add days
future = solar.next(30)
print(f"30 days later: {future.toYmd()}")

# Add months  
next_month = solar.nextMonth(1)
print(f"Next month: {next_month.toYmd()}")

# Calculate difference
other = Solar.fromYmd(2023, 6, 15)
diff = other.subtract(solar)
print(f"Difference: {diff} days")

Working with Time Periods

from lunar_python import SolarYear, LunarYear

# Get all months in a solar year
solar_year = SolarYear.fromYear(2023)
months = solar_year.getMonths()
print(f"Solar year has {len(months)} months")

# Get lunar year information
lunar_year = LunarYear.fromYear(2023)
print(f"Lunar year has {lunar_year.getDayCount()} days")
print(f"Leap month: {lunar_year.getLeapMonth()}")

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