0
# Chinese Traditional Elements
1

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

4
## Capabilities
5

6
### Heavenly Stems and Earthly Branches (干支)
7

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

10
```python { .api }
11
class Lunar:
12
    # Year Gan-Zhi
13
    def getYearGan(self) -> str: ...  # Year heavenly stem
14
    def getYearZhi(self) -> str: ...  # Year earthly branch  
15
    def getYearInGanZhi(self) -> str: ...  # Combined year stem-branch
16
    
17
    # Month Gan-Zhi
18
    def getMonthGan(self) -> str: ...
19
    def getMonthZhi(self) -> str: ...
20
    def getMonthInGanZhi(self) -> str: ...
21
    
22
    # Day Gan-Zhi
23
    def getDayGan(self) -> str: ...
24
    def getDayZhi(self) -> str: ...
25
    def getDayInGanZhi(self) -> str: ...
26
    
27
    # Time Gan-Zhi (2-hour periods)
28
    def getTimeGan(self) -> str: ...
29
    def getTimeZhi(self) -> str: ...
30
    def getTimeInGanZhi(self) -> str: ...
31

32
class LunarTime:
33
    def getGan(self) -> str: ...
34
    def getZhi(self) -> str: ...
35
    def getGanZhi(self) -> str: ...
36
```
37

38
### Chinese Zodiac Animals (生肖)
39

40
Twelve zodiac animals associated with different time periods.
41

42
```python { .api }
43
class Lunar:
44
    def getYearShengXiao(self) -> str: ...  # Year zodiac animal
45
    def getMonthShengXiao(self) -> str: ...
46
    def getDayShengXiao(self) -> str: ...
47
    def getTimeShengXiao(self) -> str: ...
48

49
class LunarTime:
50
    def getShengXiao(self) -> str: ...
51
```
52

53
### Five Elements and Sound Classifications (五行纳音)
54

55
Traditional Five Elements theory and sound classifications for fortune analysis.
56

57
```python { .api }
58
class Lunar:
59
    # NaYin (Sound Classifications) for different periods
60
    def getYearNaYin(self) -> str: ...
61
    def getMonthNaYin(self) -> str: ...
62
    def getDayNaYin(self) -> str: ...
63
    def getTimeNaYin(self) -> str: ...
64

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

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

71
class LunarMonth:
72
    def getMonthNaYin(self) -> str: ...
73
```
74

75
### Directional Positions and Deity Locations
76

77
Calculations for auspicious directions of various deities and spirits.
78

79
```python { .api }
80
class Lunar:
81
    # Deity positions
82
    def getPositionXi(self) -> str: ...  # Joy god position
83
    def getPositionYangGui(self) -> str: ...  # Yang noble person position
84
    def getPositionYinGui(self) -> str: ...  # Yin noble person position
85
    def getPositionFu(self, sect: int = 2) -> str: ...  # Fortune god position
86
    def getPositionCai(self, sect: int = 2) -> str: ...  # Wealth god position
87
    
88
    # Tai Sui (Grand Duke Jupiter) position
89
    def getPositionTaiSui(self) -> str: ...
90
    def getPositionTaiSuiDesc(self) -> str: ...
91

92
class LunarTime:
93
    def getPositionXi(self) -> str: ...
94
    def getPositionYangGui(self) -> str: ...
95
    def getPositionYinGui(self) -> str: ...
96
    def getPositionFu(self, sect: int = 2) -> str: ...
97
    def getPositionCai(self, sect: int = 2) -> str: ...
98

99
class LunarYear:
100
    def getPositionXi(self) -> str: ...
101
    def getPositionTaiSui(self) -> str: ...
102
    def getPositionTaiSuiDesc(self) -> str: ...
103
```
104

105
### Fetal God Positions (胎神)
106

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

109
```python { .api }
110
class Lunar:
111
    def getPositionTai(self) -> str: ...  # Fetal god position
112
    def getPositionTaiDesc(self) -> str: ...  # Fetal god position description
113
```
114

115
### Conflict and Harm Calculations (冲煞害)
116

117
Traditional calculations for conflicts, clashes, and harmful directions.
118

119
```python { .api }
120
class Lunar:
121
    # Conflicts (冲)
122
    def getChong(self) -> str: ...  # What this day conflicts with
123
    def getChongGan(self) -> str: ...  # Stem conflict
124
    def getChongGanTie(self) -> str: ...  # Stem conflict binding
125
    def getChongShengXiao(self) -> str: ...  # Zodiac conflict
126
    def getChongDesc(self) -> str: ...  # Conflict description
127
    
128
    # Harmful direction (煞)
129
    def getSha(self) -> str: ...
130

131
class LunarTime:
132
    def getChong(self) -> str: ...
133
    def getChongGan(self) -> str: ...
134
    def getChongShengXiao(self) -> str: ...
135
    def getSha(self) -> str: ...
136
```
137

138
### PengZu Taboos (彭祖百忌)
139

140
Traditional taboos associated with specific Gan-Zhi combinations.
141

142
```python { .api }
143
class Lunar:
144
    def getPengZuGan(self) -> str: ...  # Stem-related taboo
145
    def getPengZuZhi(self) -> str: ...  # Branch-related taboo
146
```
147

148
### Auspicious and Inauspicious Activities
149

150
Traditional guidance on favorable and unfavorable activities for specific times.
151

152
```python { .api }
153
class Lunar:
154
    def getYi(self) -> list: ...  # Auspicious activities for the day
155
    def getJi(self) -> list: ...  # Inauspicious activities for the day
156

157
class LunarTime:
158
    def getYi(self) -> list: ...  # Auspicious activities for the time
159
    def getJi(self) -> list: ...  # Inauspicious activities for the time
160
```
161

162
### Solar Terms (节气)
163

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

166
```python { .api }
167
class Lunar:
168
    def getJieQi(self) -> str: ...  # Current solar term name
169
    def getNextJie(self, whole_day: bool = False) -> 'JieQi': ...  # Next solar term
170
    def getPrevJie(self, whole_day: bool = False) -> 'JieQi': ...  # Previous solar term
171
    def getNextQi(self, whole_day: bool = False) -> 'JieQi': ...  # Next "Qi" type term
172
    def getPrevQi(self, whole_day: bool = False) -> 'JieQi': ...  # Previous "Qi" type term
173
    def getNextJieQi(self, whole_day: bool = False) -> 'JieQi': ...  # Next solar term (any type)
174
    def getPrevJieQi(self, whole_day: bool = False) -> 'JieQi': ...  # Previous solar term (any type)
175

176
class JieQi:
177
    def getName(self) -> str: ...
178
    def setName(self, name: str): ...
179
    def getSolar(self) -> 'Solar': ...
180
    def setSolar(self, solar: 'Solar'): ...
181
    def isJie(self) -> bool: ...  # Is this a "Jie" (node) term
182
    def isQi(self) -> bool: ...   # Is this a "Qi" (breath) term
183
    def toString(self) -> str: ...
184
```
185

186
### Seasonal Calculations
187

188
Special seasonal period calculations including winter counting and dog days.
189

190
```python { .api }
191
class Lunar:
192
    def getShuJiu(self) -> 'ShuJiu': ...  # Winter counting period
193
    def getFu(self) -> 'Fu': ...  # Dog days period
194

195
class ShuJiu:
196
    def getName(self) -> str: ...  # Period name (一九, 二九, etc.)
197
    def setName(self, name: str): ...
198
    def getIndex(self) -> int: ...  # Day index within period
199
    def setIndex(self, index: int): ...
200
    def toString(self) -> str: ...
201
    def toFullString(self) -> str: ...
202

203
class Fu:
204
    def getName(self) -> str: ...  # Period name (初伏, 中伏, 末伏)
205
    def setName(self, name: str): ...
206
    def getIndex(self) -> int: ...  # Day index within period
207
    def setIndex(self, index: int): ...
208
    def toString(self) -> str: ...
209
    def toFullString(self) -> str: ...
210
```
211

212
### Festivals and Special Days
213

214
Traditional lunar and solar festivals and special observances.
215

216
```python { .api }
217
class Lunar:
218
    def getFestivals(self) -> list: ...  # Lunar festivals
219
    def getOtherFestivals(self) -> list: ...  # Other lunar festivals
220
    
221
class Solar:
222
    def getFestivals(self) -> list: ...  # Solar festivals
223
    def getOtherFestivals(self) -> list: ...  # Other solar festivals
224
```
225

226
## Usage Examples
227

228
### Basic Gan-Zhi and Zodiac
229

230
```python
231
from lunar_python import Lunar
232

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

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

241
# Get zodiac animals
242
print(f"Year animal: {lunar.getYearShengXiao()}")   # 兔
243
print(f"Day animal: {lunar.getDayShengXiao()}")     # 鸡
244
```
245

246
### Directional Calculations
247

248
```python
249
from lunar_python import Lunar
250

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

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

258
# Get fetal god position
259
print(f"Fetal god: {lunar.getPositionTai()}")     # Position
260
print(f"Fetal god desc: {lunar.getPositionTaiDesc()}")  # Description
261
```
262

263
### Conflict and Taboo Information
264

265
```python
266
from lunar_python import Lunar
267

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

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

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

280
### Auspicious Activities
281

282
```python
283
from lunar_python import Lunar
284

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

287
# Get daily activities
288
yi_list = lunar.getYi()  # Auspicious activities
289
ji_list = lunar.getJi()  # Inauspicious activities
290

291
print("Auspicious activities:")
292
for activity in yi_list:
293
    print(f"  {activity}")
294
    
295
print("Inauspicious activities:")
296
for activity in ji_list:
297
    print(f"  {activity}")
298
```
299

300
### Solar Terms
301

302
```python
303
from lunar_python import Lunar
304

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

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

311
# Next and previous solar terms
312
next_jie = lunar.getNextJie()
313
prev_jie = lunar.getPrevJie()
314

315
print(f"Next Jie: {next_jie.getName()} on {next_jie.getSolar().toYmd()}")
316
print(f"Previous Jie: {prev_jie.getName()} on {prev_jie.getSolar().toYmd()}")
317
```
318

319
### Seasonal Periods
320

321
```python
322
from lunar_python import Lunar
323

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

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