or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-calendar.mdfortune-telling.mdindex.mdreligious-calendars.mdtraditional-elements.mdutilities.md
tile.json

tessl/pypi-lunar-python

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/lunar-python@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-lunar-python@1.4.0

index.mddocs/

Lunar Python

A comprehensive Chinese lunar calendar library providing accurate Solar (Gregorian) to Lunar calendar conversion with extensive traditional Chinese calendar features. The library supports advanced Chinese almanac calculations, fortune telling elements, Buddhist and Taoist calendars, with no third-party dependencies.

Package Information

  • Package Name: lunar_python
  • Language: Python
  • Installation: pip install lunar_python

Core Imports

from lunar_python import Solar, Lunar

For specific calendar systems:

from lunar_python import Solar, Lunar, EightChar, JieQi, NineStar

For utilities:

from lunar_python.util import LunarUtil, SolarUtil

Basic Usage

from lunar_python import Solar, Lunar

# Create a solar date
solar = Solar.fromYmd(2023, 5, 29)
print(solar.toFullString())

# Convert solar to lunar
lunar = solar.getLunar()
print(lunar.toFullString())

# Create lunar date directly
lunar = Lunar.fromYmd(2023, 4, 11)  # lunar year, month, day
print(lunar.toFullString())

# Convert lunar to solar
solar = lunar.getSolar()
print(solar.toFullString())

# Get traditional elements
print(f"Year: {lunar.getYearInGanZhi()}")  
print(f"Month: {lunar.getMonthInGanZhi()}")
print(f"Day: {lunar.getDayInGanZhi()}")
print(f"Chinese Zodiac: {lunar.getYearShengXiao()}")

Architecture

The library is organized around core calendar classes:

  • Solar/Lunar Classes: Primary date representations with conversion methods
  • Time Period Classes: Year, month, week, season, and time period representations
  • Traditional Elements: Eight Character analysis, Nine Star calculations, solar terms
  • Religious Calendars: Buddhist (Foto) and Taoist (Tao) calendar systems
  • Utility Classes: Constants, calculations, and helper functions

Capabilities

Core Calendar Conversion

Primary functionality for converting between Solar (Gregorian) and Lunar (Chinese) calendar systems, with comprehensive date manipulation and formatting capabilities.

class Solar:
    @staticmethod
    def fromYmd(year: int, month: int, day: int) -> 'Solar': ...
    @staticmethod
    def fromDate(date) -> 'Solar': ...
    
    def getLunar(self) -> 'Lunar': ...
    def toFullString(self) -> str: ...

class Lunar:
    @staticmethod
    def fromYmd(lunar_year: int, lunar_month: int, lunar_day: int) -> 'Lunar': ...
    @staticmethod
    def fromSolar(solar: 'Solar') -> 'Lunar': ...
    
    def getSolar(self) -> 'Solar': ...
    def toFullString(self) -> str: ...

Core Calendar Conversion

Chinese Traditional Elements

Traditional Chinese calendar elements including Heavenly Stems and Earthly Branches (Gan-Zhi), Chinese zodiac animals, Five Elements, and positional calculations for deities and spirits.

class Lunar:
    def getYearGan(self) -> str: ...
    def getYearZhi(self) -> str: ...
    def getYearInGanZhi(self) -> str: ...
    def getYearShengXiao(self) -> str: ...
    def getPositionXi(self) -> str: ...
    def getPositionYangGui(self) -> str: ...

Chinese Traditional Elements

Fortune Telling and Eight Characters

Comprehensive Eight Character (BaZi) analysis system including Ten Gods, Five Elements analysis, Hidden Stems, palace calculations, and fortune cycle predictions.

class EightChar:
    @staticmethod
    def fromLunar(lunar: 'Lunar') -> 'EightChar': ...
    
    def getYear(self) -> str: ...
    def getYearGan(self) -> str: ...
    def getYearZhi(self) -> str: ...
    def getYun(self, gender: int, sect: int = 1): ...

class NineStar:
    @staticmethod
    def fromIndex(index: int) -> 'NineStar': ...
    
    def getNumber(self) -> str: ...
    def getColor(self) -> str: ...

Fortune Telling and Eight Characters

Buddhist and Taoist Calendars

Specialized calendar systems for Buddhist (Foto) and Taoist (Tao) traditions, including festival calculations, fasting days, and religious observances.

class Foto:
    @staticmethod
    def fromLunar(lunar: 'Lunar') -> 'Foto': ...
    
    def getFestivals(self) -> list: ...
    def getXiu(self) -> str: ...

class Tao:
    @staticmethod
    def fromLunar(lunar: 'Lunar') -> 'Tao': ...
    
    def getFestivals(self) -> list: ...

Buddhist and Taoist Calendars

Utilities and Constants

Comprehensive utility functions and constants for Chinese calendar calculations, including solar terms, position calculations, and holiday determinations.

class LunarUtil:
    GAN: tuple  # Heavenly Stems
    ZHI: tuple  # Earthly Branches
    JIA_ZI: tuple  # 60 stem-branch combinations
    SHENGXIAO: tuple  # Chinese zodiac animals
    
    @staticmethod
    def getJiaZiIndex(gan_zhi: str) -> int: ...

class SolarUtil:
    @staticmethod
    def isLeapYear(year: int) -> bool: ...
    @staticmethod
    def getDaysOfMonth(year: int, month: int) -> int: ...

Utilities and Constants

Types

# Core calendar types
Solar: class
Lunar: class
EightChar: class
NineStar: class
JieQi: class  # Solar terms
ShuJiu: class  # Winter counting
Fu: class  # Dog days

# Time period types
LunarYear: class
LunarMonth: class
LunarTime: class
SolarYear: class
SolarMonth: class
SolarWeek: class
SolarSeason: class
SolarHalfYear: class

# Holiday and festival types
Holiday: class
FotoFestival: class
TaoFestival: class

# Religious calendar types  
Foto: class  # Buddhist calendar
Tao: class   # Taoist calendar

# Utility types
LunarUtil: class
SolarUtil: class
HolidayUtil: class