0
# Lunar Python
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: lunar_python
7
- **Language**: Python
8
- **Installation**: `pip install lunar_python`
9

10
## Core Imports
11

12
```python
13
from lunar_python import Solar, Lunar
14
```
15

16
For specific calendar systems:
17

18
```python
19
from lunar_python import Solar, Lunar, EightChar, JieQi, NineStar
20
```
21

22
For utilities:
23

24
```python
25
from lunar_python.util import LunarUtil, SolarUtil
26
```
27

28
## Basic Usage
29

30
```python
31
from lunar_python import Solar, Lunar
32

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

37
# Convert solar to lunar
38
lunar = solar.getLunar()
39
print(lunar.toFullString())
40

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

45
# Convert lunar to solar
46
solar = lunar.getSolar()
47
print(solar.toFullString())
48

49
# Get traditional elements
50
print(f"Year: {lunar.getYearInGanZhi()}")  
51
print(f"Month: {lunar.getMonthInGanZhi()}")
52
print(f"Day: {lunar.getDayInGanZhi()}")
53
print(f"Chinese Zodiac: {lunar.getYearShengXiao()}")
54
```
55

56
## Architecture
57

58
The library is organized around core calendar classes:
59

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

66
## Capabilities
67

68
### Core Calendar Conversion
69

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

72
```python { .api }
73
class Solar:
74
    @staticmethod
75
    def fromYmd(year: int, month: int, day: int) -> 'Solar': ...
76
    @staticmethod
77
    def fromDate(date) -> 'Solar': ...
78
    
79
    def getLunar(self) -> 'Lunar': ...
80
    def toFullString(self) -> str: ...
81

82
class Lunar:
83
    @staticmethod
84
    def fromYmd(lunar_year: int, lunar_month: int, lunar_day: int) -> 'Lunar': ...
85
    @staticmethod
86
    def fromSolar(solar: 'Solar') -> 'Lunar': ...
87
    
88
    def getSolar(self) -> 'Solar': ...
89
    def toFullString(self) -> str: ...
90
```
91

92
[Core Calendar Conversion](./core-calendar.md)
93

94
### Chinese Traditional Elements
95

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

98
```python { .api }
99
class Lunar:
100
    def getYearGan(self) -> str: ...
101
    def getYearZhi(self) -> str: ...
102
    def getYearInGanZhi(self) -> str: ...
103
    def getYearShengXiao(self) -> str: ...
104
    def getPositionXi(self) -> str: ...
105
    def getPositionYangGui(self) -> str: ...
106
```
107

108
[Chinese Traditional Elements](./traditional-elements.md)
109

110
### Fortune Telling and Eight Characters
111

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

114
```python { .api }
115
class EightChar:
116
    @staticmethod
117
    def fromLunar(lunar: 'Lunar') -> 'EightChar': ...
118
    
119
    def getYear(self) -> str: ...
120
    def getYearGan(self) -> str: ...
121
    def getYearZhi(self) -> str: ...
122
    def getYun(self, gender: int, sect: int = 1): ...
123

124
class NineStar:
125
    @staticmethod
126
    def fromIndex(index: int) -> 'NineStar': ...
127
    
128
    def getNumber(self) -> str: ...
129
    def getColor(self) -> str: ...
130
```
131

132
[Fortune Telling and Eight Characters](./fortune-telling.md)
133

134
### Buddhist and Taoist Calendars
135

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

138
```python { .api }
139
class Foto:
140
    @staticmethod
141
    def fromLunar(lunar: 'Lunar') -> 'Foto': ...
142
    
143
    def getFestivals(self) -> list: ...
144
    def getXiu(self) -> str: ...
145

146
class Tao:
147
    @staticmethod
148
    def fromLunar(lunar: 'Lunar') -> 'Tao': ...
149
    
150
    def getFestivals(self) -> list: ...
151
```
152

153
[Buddhist and Taoist Calendars](./religious-calendars.md)
154

155
### Utilities and Constants
156

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

159
```python { .api }
160
class LunarUtil:
161
    GAN: tuple  # Heavenly Stems
162
    ZHI: tuple  # Earthly Branches
163
    JIA_ZI: tuple  # 60 stem-branch combinations
164
    SHENGXIAO: tuple  # Chinese zodiac animals
165
    
166
    @staticmethod
167
    def getJiaZiIndex(gan_zhi: str) -> int: ...
168

169
class SolarUtil:
170
    @staticmethod
171
    def isLeapYear(year: int) -> bool: ...
172
    @staticmethod
173
    def getDaysOfMonth(year: int, month: int) -> int: ...
174
```
175

176
[Utilities and Constants](./utilities.md)
177

178
## Types
179

180
```python { .api }
181
# Core calendar types
182
Solar: class
183
Lunar: class
184
EightChar: class
185
NineStar: class
186
JieQi: class  # Solar terms
187
ShuJiu: class  # Winter counting
188
Fu: class  # Dog days
189

190
# Time period types
191
LunarYear: class
192
LunarMonth: class
193
LunarTime: class
194
SolarYear: class
195
SolarMonth: class
196
SolarWeek: class
197
SolarSeason: class
198
SolarHalfYear: class
199

200
# Holiday and festival types
201
Holiday: class
202
FotoFestival: class
203
TaoFestival: class
204

205
# Religious calendar types  
206
Foto: class  # Buddhist calendar
207
Tao: class   # Taoist calendar
208

209
# Utility types
210
LunarUtil: class
211
SolarUtil: class
212
HolidayUtil: class
213
```