0
# Fortune Telling and Eight Characters
1

2
Comprehensive Eight Character (BaZi) analysis system, Nine Star calculations, and advanced Chinese metaphysical analysis for fortune telling and personality assessment.
3

4
## Capabilities
5

6
### Eight Characters (八字) Analysis
7

8
The core BaZi system analyzing four pillars (year, month, day, time) with comprehensive fortune-telling capabilities.
9

10
```python { .api }
11
class EightChar:
12
    @staticmethod
13
    def fromLunar(lunar: 'Lunar') -> 'EightChar': ...
14
    
15
    def getSect(self) -> int: ...  # Calculation sect (1 or 2)
16
    def setSect(self, sect: int): ...
17
```
18

19
#### Four Pillars (四柱)
20

21
Basic four-pillar structure forming the foundation of BaZi analysis.
22

23
```python { .api }
24
class EightChar:
25
    # Year Pillar (年柱)
26
    def getYear(self) -> str: ...  # Year stem-branch combination
27
    def getYearGan(self) -> str: ...  # Year heavenly stem
28
    def getYearZhi(self) -> str: ...  # Year earthly branch
29
    
30
    # Month Pillar (月柱)
31
    def getMonth(self) -> str: ...
32
    def getMonthGan(self) -> str: ...
33
    def getMonthZhi(self) -> str: ...
34
    
35
    # Day Pillar (日柱) - Most important pillar
36
    def getDay(self) -> str: ...
37
    def getDayGan(self) -> str: ...  # Day Master (日主)
38
    def getDayZhi(self) -> str: ...
39
    
40
    # Time Pillar (时柱)
41
    def getTime(self) -> str: ...
42
    def getTimeGan(self) -> str: ...
43
    def getTimeZhi(self) -> str: ...
44
```
45

46
#### Hidden Stems (藏干)
47

48
Hidden heavenly stems within earthly branches for detailed analysis.
49

50
```python { .api }
51
class EightChar:
52
    def getYearHideGan(self) -> list: ...  # Hidden stems in year branch
53
    def getMonthHideGan(self) -> list: ...
54
    def getDayHideGan(self) -> list: ...
55
    def getTimeHideGan(self) -> list: ...
56
```
57

58
#### Five Elements Analysis (五行)
59

60
Five Elements strength and relationship analysis.
61

62
```python { .api }
63
class EightChar:
64
    def getYearWuXing(self) -> str: ...  # Year pillar five element
65
    def getMonthWuXing(self) -> str: ...
66
    def getDayWuXing(self) -> str: ...  # Day Master element
67
    def getTimeWuXing(self) -> str: ...
68
```
69

70
#### Sound Classifications (纳音)
71

72
Traditional sound-based element classifications.
73

74
```python { .api }
75
class EightChar:
76
    def getYearNaYin(self) -> str: ...
77
    def getMonthNaYin(self) -> str: ...
78
    def getDayNaYin(self) -> str: ...
79
    def getTimeNaYin(self) -> str: ...
80
```
81

82
#### Ten Gods Analysis (十神)
83

84
Relationship analysis based on interactions between heavenly stems.
85

86
```python { .api }
87
class EightChar:
88
    # Ten Gods for Heavenly Stems
89
    def getYearShiShenGan(self) -> str: ...  # Year stem Ten God
90
    def getMonthShiShenGan(self) -> str: ...
91
    def getDayShiShenGan(self) -> str: ...  # Always "日主" (Day Master)
92
    def getTimeShiShenGan(self) -> str: ...
93
    
94
    # Ten Gods for Earthly Branches  
95
    def getYearShiShenZhi(self) -> list: ...  # Year branch Ten Gods
96
    def getMonthShiShenZhi(self) -> list: ...
97
    def getDayShiShenZhi(self) -> list: ...
98
    def getTimeShiShenZhi(self) -> list: ...
99
```
100

101
#### Twelve Growth Phases (十二长生)
102

103
Life cycle phases analysis for detailed fortune interpretation.
104

105
```python { .api }
106
class EightChar:
107
    def getYearDiShi(self) -> str: ...  # Year growth phase
108
    def getMonthDiShi(self) -> str: ...
109
    def getDayDiShi(self) -> str: ...
110
    def getTimeDiShi(self) -> str: ...
111
```
112

113
#### Special Palaces (宫位)
114

115
Important palace calculations for comprehensive analysis.
116

117
```python { .api }
118
class EightChar:
119
    # Conception Palace (胎元)
120
    def getTaiYuan(self) -> str: ...
121
    def getTaiYuanNaYin(self) -> str: ...
122
    
123
    # Breath Palace (胎息)  
124
    def getTaiXi(self) -> str: ...
125
    def getTaiXiNaYin(self) -> str: ...
126
    
127
    # Life Palace (命宫)
128
    def getMingGong(self) -> str: ...
129
    def getMingGongNaYin(self) -> str: ...
130
    
131
    # Body Palace (身宫)
132
    def getShenGong(self) -> str: ...
133
    def getShenGongNaYin(self) -> str: ...
134
```
135

136
#### Fortune Cycles (大运)
137

138
Major life period fortune analysis and predictions.
139

140
```python { .api }
141
class EightChar:
142
    def getYun(self, gender: int, sect: int = 1) -> 'Yun': ...
143
    # gender: 0=female, 1=male
144
    # sect: calculation method (1 or 2)
145
```
146

147
### Fortune Cycle Classes (运程)
148

149
Detailed fortune cycle analysis classes for life period predictions.
150

151
```python { .api }
152
class Yun:
153
    def getGender(self) -> int: ...  # 0=female, 1=male
154
    def getStartYear(self) -> int: ...  # Fortune cycle start year
155
    def getStartAge(self) -> int: ...   # Starting age
156
    def isForward(self) -> bool: ...    # Forward or reverse calculation
157
    
158
    def getDaYun(self) -> list: ...     # List of 10-year major cycles
159
    def getXiaoYun(self) -> list: ...   # List of yearly minor cycles
160
    def getLiuNian(self, n: int) -> list: ...  # List of n yearly cycles
161

162
class DaYun:
163
    def getIndex(self) -> int: ...      # Cycle index
164
    def getStartYear(self) -> int: ...  # Cycle start year
165
    def getStartAge(self) -> int: ...   # Starting age
166
    def getEndYear(self) -> int: ...    # Cycle end year
167
    def getEndAge(self) -> int: ...     # Ending age
168
    def getGanZhi(self) -> str: ...     # Cycle stem-branch
169
    
170
    def getLiuYue(self) -> list: ...    # Monthly cycles within this period
171

172
class XiaoYun:
173
    def getYear(self) -> int: ...       # Year
174
    def getAge(self) -> int: ...        # Age during this year
175
    def getIndex(self) -> int: ...      # Cycle index
176
    def getGanZhi(self) -> str: ...     # Year stem-branch
177

178
class LiuNian:
179
    def getYear(self) -> int: ...       # Year
180
    def getAge(self) -> int: ...        # Age
181
    def getGanZhi(self) -> str: ...     # Year stem-branch
182

183
class LiuYue:
184
    def getIndex(self) -> int: ...      # Month index
185
    def getMonthInChinese(self) -> str: ...  # Chinese month name
186
    def getGanZhi(self) -> str: ...     # Month stem-branch (Wu Hu Dun formula)
187
    def getXun(self) -> str: ...        # Sexagenary cycle
188
    def getXunKong(self) -> str: ...    # Cycle void
189
```
190

191
### Nine Star System (九星)
192

193
Traditional Nine Star calculations for metaphysical analysis.
194

195
```python { .api }
196
class NineStar:
197
    @staticmethod
198
    def fromIndex(index: int) -> 'NineStar': ...  # index: 0-8
199
    
200
    def getIndex(self) -> int: ...      # Star index (0-8)
201
    def getNumber(self) -> str: ...     # Star number (一-九)
202
    def getColor(self) -> str: ...      # Associated color
203
    def getWuXing(self) -> str: ...     # Five element
204
    def getPosition(self) -> str: ...   # Direction position
205
    def getPositionDesc(self) -> str: ... # Position description
206
```
207

208
#### Nine Star Name Systems
209

210
Different naming conventions for various metaphysical schools.
211

212
```python { .api }
213
class NineStar:
214
    def getNameInBeiDou(self) -> str: ...   # Big Dipper names
215
    def getNameInXuanKong(self) -> str: ... # Xuan Kong Feng Shui names
216
    def getNameInQiMen(self) -> str: ...    # Qi Men Dun Jia names  
217
    def getNameInTaiYi(self) -> str: ...    # Tai Yi Shen Shu names
218
```
219

220
#### Nine Star Attributes
221

222
Additional metaphysical attributes for detailed analysis.
223

224
```python { .api }
225
class NineStar:
226
    # Luck classifications
227
    def getLuckInQiMen(self) -> str: ...    # Qi Men luck classification
228
    def getLuckInXuanKong(self) -> str: ... # Xuan Kong luck classification
229
    
230
    # Other attributes
231
    def getYinYangInQiMen(self) -> str: ... # Yin-Yang classification in Qi Men
232
    def getTypeInTaiYi(self) -> str: ...    # Type in Tai Yi system
233
    def getBaMenInQiMen(self) -> str: ...   # Eight Gates in Qi Men
234
    def getSongInTaiYi(self) -> str: ...    # Song formula in Tai Yi
235
    
236
    def toString(self) -> str: ...
237
    def toFullString(self) -> str: ...
238
```
239

240
### Nine Star Access from Calendar Classes
241

242
Access Nine Star calculations from various calendar contexts.
243

244
```python { .api }
245
class Lunar:
246
    def getNineStar(self) -> 'NineStar': ...     # Day Nine Star
247

248
class LunarYear:
249
    def getNineStar(self) -> 'NineStar': ...     # Year Nine Star
250

251
class LunarMonth:  
252
    def getNineStar(self) -> 'NineStar': ...     # Month Nine Star
253

254
class LunarTime:
255
    def getNineStar(self) -> 'NineStar': ...     # Time Nine Star
256
```
257

258
## Usage Examples
259

260
### Basic Eight Characters Analysis
261

262
```python
263
from lunar_python import Lunar, EightChar
264

265
# Create lunar date
266
lunar = Lunar.fromYmd(1986, 4, 21)
267

268
# Get Eight Characters analysis
269
ba_zi = EightChar.fromLunar(lunar)
270

271
# Four Pillars
272
print("=== Four Pillars ===")
273
print(f"Year:  {ba_zi.getYear()}")   # 丙寅
274
print(f"Month: {ba_zi.getMonth()}")  # 癸巳  
275
print(f"Day:   {ba_zi.getDay()}")    # 癸酉 (Day Master)
276
print(f"Time:  {ba_zi.getTime()}")   # 子时
277

278
# Individual stems and branches
279
print("\n=== Stems and Branches ===")
280
print(f"Year Gan: {ba_zi.getYearGan()}, Zhi: {ba_zi.getYearZhi()}")
281
print(f"Day Gan (Day Master): {ba_zi.getDayGan()}")
282
```
283

284
### Five Elements and Ten Gods Analysis
285

286
```python
287
from lunar_python import Lunar, EightChar
288

289
lunar = Lunar.fromYmd(1986, 4, 21)
290
ba_zi = EightChar.fromLunar(lunar)
291

292
# Five Elements
293
print("=== Five Elements ===")
294
print(f"Year: {ba_zi.getYearWuXing()}")
295
print(f"Month: {ba_zi.getMonthWuXing()}")  
296
print(f"Day (Day Master): {ba_zi.getDayWuXing()}")
297
print(f"Time: {ba_zi.getTimeWuXing()}")
298

299
# Ten Gods relationships
300
print("\n=== Ten Gods ===")
301
print(f"Year: {ba_zi.getYearShiShenGan()}")
302
print(f"Month: {ba_zi.getMonthShiShenGan()}")
303
print(f"Day: {ba_zi.getDayShiShenGan()}")  # Always "日主"
304
print(f"Time: {ba_zi.getTimeShiShenGan()}")
305
```
306

307
### Palace Calculations
308

309
```python
310
from lunar_python import Lunar, EightChar
311

312
lunar = Lunar.fromYmd(1986, 4, 21)
313
ba_zi = EightChar.fromLunar(lunar)
314

315
# Special palaces
316
print("=== Special Palaces ===")
317
print(f"Conception Palace: {ba_zi.getTaiYuan()}")
318
print(f"Life Palace: {ba_zi.getMingGong()}")
319
print(f"Body Palace: {ba_zi.getShenGong()}")
320

321
# Palace sound classifications
322
print(f"Life Palace NaYin: {ba_zi.getMingGongNaYin()}")
323
```
324

325
### Fortune Cycle Analysis
326

327
```python
328
from lunar_python import Lunar, EightChar
329

330
lunar = Lunar.fromYmd(1986, 4, 21)  
331
ba_zi = EightChar.fromLunar(lunar)
332

333
# Get fortune cycles (gender: 1=male, 0=female)
334
yun = ba_zi.getYun(1)  # Male
335

336
print(f"Fortune cycle starts at age: {yun.getStartAge()}")
337
print(f"Forward counting: {yun.isForward()}")
338

339
# Major 10-year cycles
340
da_yun_list = yun.getDaYun()
341
print("\n=== Major 10-Year Cycles ===")
342
for i, da_yun in enumerate(da_yun_list[:5]):  # First 5 cycles
343
    print(f"Age {da_yun.getStartAge()}-{da_yun.getEndAge()}: {da_yun.getGanZhi()}")
344

345
# Yearly cycles
346
xiao_yun_list = yun.getXiaoYun()
347
print(f"\n=== Some Yearly Cycles ===") 
348
for i, xiao_yun in enumerate(xiao_yun_list[:10]):  # First 10 years
349
    print(f"Age {xiao_yun.getAge()}: {xiao_yun.getGanZhi()}")
350
```
351

352
### Nine Star Analysis
353

354
```python
355
from lunar_python import Lunar, NineStar
356

357
lunar = Lunar.fromYmd(2023, 4, 11)
358

359
# Get Nine Star for this day
360
nine_star = lunar.getNineStar()
361

362
print("=== Nine Star Analysis ===")
363
print(f"Star Number: {nine_star.getNumber()}")
364
print(f"Color: {nine_star.getColor()}")  
365
print(f"Five Element: {nine_star.getWuXing()}")
366
print(f"Position: {nine_star.getPosition()} ({nine_star.getPositionDesc()})")
367

368
# Different naming systems
369
print(f"Big Dipper name: {nine_star.getNameInBeiDou()}")
370
print(f"Xuan Kong name: {nine_star.getNameInXuanKong()}")
371
print(f"Qi Men name: {nine_star.getNameInQiMen()}")
372

373
# Luck classifications
374
print(f"Qi Men luck: {nine_star.getLuckInQiMen()}")
375
print(f"Xuan Kong luck: {nine_star.getLuckInXuanKong()}")
376
```
377

378
### Creating Nine Star Directly
379

380
```python
381
from lunar_python import NineStar
382

383
# Create Nine Star from index (0-8)
384
star = NineStar.fromIndex(0)  # First star (贪狼)
385

386
print(f"Star: {star.getNumber()} - {star.getNameInBeiDou()}")
387
print(f"Element: {star.getWuXing()}")
388
print(f"Position: {star.getPosition()}")
389
```
390

391
### Advanced Analysis Example
392

393
```python
394
from lunar_python import Lunar, EightChar
395

396
# Birth information
397
lunar = Lunar.fromYmd(1986, 4, 21)
398
ba_zi = EightChar.fromLunar(lunar)
399

400
print("=== Complete BaZi Analysis ===")
401
print(f"Birth: {lunar.toFullString()}")
402
print(f"Four Pillars: {ba_zi.getYear()} {ba_zi.getMonth()} {ba_zi.getDay()} {ba_zi.getTime()}")
403

404
# Day Master analysis (most important)
405
day_master = ba_zi.getDayGan()
406
day_element = ba_zi.getDayWuXing()
407
print(f"Day Master: {day_master} ({day_element})")
408

409
# Hidden stems analysis
410
print(f"Day Hidden Stems: {ba_zi.getDayHideGan()}")
411

412
# Growth phases
413
print(f"Day Growth Phase: {ba_zi.getDayDiShi()}")
414

415
# Sound classifications
416
nayin_list = [ba_zi.getYearNaYin(), ba_zi.getMonthNaYin(), 
417
              ba_zi.getDayNaYin(), ba_zi.getTimeNaYin()]
418
print(f"NaYin: {nayin_list}")
419
```