0
# Core Calendar Conversion
1

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

4
## Capabilities
5

6
### Solar Calendar Class
7

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

10
```python { .api }
11
class Solar:
12
    def __init__(self, solar_year: int, solar_month: int, solar_day: int, 
13
                 solar_hour: int = 0, solar_minute: int = 0, solar_second: int = 0): ...
14
    
15
    @staticmethod
16
    def fromYmd(year: int, month: int, day: int) -> 'Solar': ...
17
    
18
    @staticmethod
19
    def fromYmdHms(year: int, month: int, day: int, hour: int, minute: int, second: int) -> 'Solar': ...
20
    
21
    @staticmethod
22
    def fromDate(date) -> 'Solar': ...
23
    
24
    @staticmethod
25
    def fromJulianDay(julian_day: float) -> 'Solar': ...
26
    
27
    @staticmethod
28
    def fromBaZi(year_gan_zhi: str, month_gan_zhi: str, day_gan_zhi: str, 
29
                 time_gan_zhi: str, sect: int = 2, base_year: int = 1900) -> 'Solar': ...
30
```
31

32
#### Date Properties and Getters
33

34
```python { .api }
35
class Solar:
36
    def getYear(self) -> int: ...
37
    def getMonth(self) -> int: ...
38
    def getDay(self) -> int: ...
39
    def getHour(self) -> int: ...
40
    def getMinute(self) -> int: ...
41
    def getSecond(self) -> int: ...
42
    
43
    def getWeek(self) -> int: ...  # 0=Sunday, 1=Monday, etc.
44
    def getWeekInChinese(self) -> str: ...
45
    def getXingZuo(self) -> str: ...  # Zodiac sign
46
    def getJulianDay(self) -> int: ...
47
```
48

49
#### Calendar Conversion
50

51
```python { .api }
52
class Solar:
53
    def getLunar(self) -> 'Lunar': ...
54
    def isLeapYear(self) -> bool: ...
55
```
56

57
#### Date Arithmetic
58

59
```python { .api }
60
class Solar:
61
    def next(self, days: int, only_work_day: bool = False) -> 'Solar': ...
62
    def nextYear(self, years: int) -> 'Solar': ...
63
    def nextMonth(self, months: int) -> 'Solar': ...
64
    def nextHour(self, hours: int) -> 'Solar': ...
65
    
66
    def subtract(self, solar: 'Solar') -> int: ...  # Days difference
67
    def subtractMinute(self, solar: 'Solar') -> int: ...  # Minutes difference
68
    
69
    def isAfter(self, solar: 'Solar') -> bool: ...
70
    def isBefore(self, solar: 'Solar') -> bool: ...
71
```
72

73
#### Festivals and Events
74

75
```python { .api }
76
class Solar:
77
    def getFestivals(self) -> list: ...  # Official festivals
78
    def getOtherFestivals(self) -> list: ...  # Unofficial festivals
79
```
80

81
#### String Formatting
82

83
```python { .api }
84
class Solar:
85
    def toString(self) -> str: ...  # Basic date string
86
    def toYmd(self) -> str: ...  # YYYY-MM-DD format
87
    def toYmdHms(self) -> str: ...  # YYYY-MM-DD HH:MM:SS format
88
    def toFullString(self) -> str: ...  # Complete descriptive format
89
```
90

91
### Lunar Calendar Class
92

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

95
```python { .api }
96
class Lunar:
97
    def __init__(self, lunar_year: int, lunar_month: int, lunar_day: int,
98
                 hour: int = 0, minute: int = 0, second: int = 0): ...
99
    
100
    @staticmethod
101
    def fromYmd(lunar_year: int, lunar_month: int, lunar_day: int) -> 'Lunar': ...
102
    
103
    @staticmethod
104
    def fromYmdHms(lunar_year: int, lunar_month: int, lunar_day: int,
105
                   hour: int, minute: int, second: int) -> 'Lunar': ...
106
    
107
    @staticmethod
108
    def fromDate(date) -> 'Lunar': ...
109
    
110
    @staticmethod
111
    def fromSolar(solar: 'Solar') -> 'Lunar': ...
112
```
113

114
#### Date Properties and Getters
115

116
```python { .api }
117
class Lunar:
118
    def getYear(self) -> int: ...
119
    def getMonth(self) -> int: ...
120
    def getDay(self) -> int: ...
121
    def getHour(self) -> int: ...
122
    def getMinute(self) -> int: ...
123
    def getSecond(self) -> int: ...
124
    
125
    def isLeapMonth(self) -> bool: ...  # Is current month a leap month
126
    def getWeek(self) -> int: ...  # Day of week (0=Sunday)
127
    def getWeekInChinese(self) -> str: ...  # Chinese day of week
128
    def getSeason(self) -> str: ...  # Get season name
129
```
130

131
#### Calendar Conversion
132

133
```python { .api }
134
class Lunar:
135
    def getSolar(self) -> 'Solar': ...
136
```
137

138
#### Chinese Formatting
139

140
```python { .api }
141
class Lunar:
142
    def getYearInChinese(self) -> str: ...  # e.g., "二〇二三"
143
    def getMonthInChinese(self) -> str: ...  # e.g., "四月"
144
    def getDayInChinese(self) -> str: ...  # e.g., "十一"
145
```
146

147
#### Date Arithmetic
148

149
```python { .api }
150
class Lunar:
151
    def next(self, days: int) -> 'Lunar': ...
152
```
153

154
#### String Formatting  
155

156
```python { .api }
157
class Lunar:
158
    def toString(self) -> str: ...  # Basic lunar date
159
    def toFullString(self) -> str: ...  # Complete traditional format with all elements
160
```
161

162
### Solar Time Period Classes
163

164
Helper classes for working with solar calendar time periods.
165

166
```python { .api }
167
class SolarYear:
168
    @staticmethod
169
    def fromYear(year: int) -> 'SolarYear': ...
170
    @staticmethod
171
    def fromDate(date) -> 'SolarYear': ...
172
    
173
    def getYear(self) -> int: ...
174
    def getMonths(self) -> list: ...  # List of SolarMonth objects
175
    def next(self, years: int) -> 'SolarYear': ...
176

177
class SolarMonth:
178
    @staticmethod
179
    def fromYm(year: int, month: int) -> 'SolarMonth': ...
180
    @staticmethod
181
    def fromDate(date) -> 'SolarMonth': ...
182
    
183
    def getYear(self) -> int: ...
184
    def getMonth(self) -> int: ...
185
    def getDays(self) -> list: ...  # List of Solar objects
186
    def getWeeks(self, start: int) -> list: ...  # List of SolarWeek objects
187
    def next(self, months: int) -> 'SolarMonth': ...
188

189
class SolarWeek:
190
    @staticmethod
191
    def fromDate(date, start: int) -> 'SolarWeek': ...
192
    @staticmethod
193
    def fromYmd(year: int, month: int, day: int, start: int) -> 'SolarWeek': ...
194
    
195
    def getYear(self) -> int: ...
196
    def getMonth(self) -> int: ...
197
    def getDay(self) -> int: ...
198
    def getWeek(self) -> int: ...  # Week of year
199
    def getStart(self) -> int: ...  # Start day (0=Sunday, 1=Monday)
200
    def getDays(self) -> list: ...  # List of 7 Solar objects
201
    def next(self, weeks: int, sep_month: bool = True) -> 'SolarWeek': ...
202

203
class SolarSeason:
204
    @staticmethod
205
    def fromYm(year: int, month: int) -> 'SolarSeason': ...
206
    @staticmethod
207
    def fromDate(date) -> 'SolarSeason': ...
208
    
209
    def getYear(self) -> int: ...
210
    def getMonth(self) -> int: ...  # Starting month of season
211
    def getIndex(self) -> int: ...  # Season index (0-3)
212
    def getMonths(self) -> list: ...  # List of 3 SolarMonth objects
213
    def next(self, seasons: int) -> 'SolarSeason': ...
214

215
class SolarHalfYear:
216
    @staticmethod
217
    def fromYm(year: int, month: int) -> 'SolarHalfYear': ...
218
    @staticmethod
219
    def fromDate(date) -> 'SolarHalfYear': ...
220
    
221
    def getYear(self) -> int: ...
222
    def getMonth(self) -> int: ...  # Starting month of half year
223
    def getIndex(self) -> int: ...  # Half year index (0-1)
224
    def getMonths(self) -> list: ...  # List of 6 SolarMonth objects
225
    def getSeasons(self) -> list: ...  # List of 2 SolarSeason objects
226
    def next(self, half_years: int) -> 'SolarHalfYear': ...
227
```
228

229
### Lunar Time Period Classes
230

231
Helper classes for working with lunar calendar time periods.
232

233
```python { .api }
234
class LunarYear:
235
    @staticmethod
236
    def fromYear(lunar_year: int) -> 'LunarYear': ...
237
    
238
    def getYear(self) -> int: ...
239
    def getDayCount(self) -> int: ...  # Total days in lunar year
240
    def getMonths(self) -> list: ...  # List of LunarMonth objects
241
    def getLeapMonth(self) -> int: ...  # Leap month number (0 if none)
242
    def getMonth(self, lunar_month: int) -> 'LunarMonth': ...
243
    def next(self, n: int) -> 'LunarYear': ...
244

245
class LunarMonth:
246
    @staticmethod
247
    def fromYm(lunar_year: int, lunar_month: int) -> 'LunarMonth': ...
248
    
249
    def getYear(self) -> int: ...
250
    def getMonth(self) -> int: ...
251
    def isLeap(self) -> bool: ...
252
    def getDayCount(self) -> int: ...  # Number of days in month
253
    def getFirstJulianDay(self) -> int: ...
254
    def next(self, n: int) -> 'LunarMonth': ...
255

256
class LunarTime:
257
    @staticmethod
258
    def fromYmdHms(lunar_year: int, lunar_month: int, lunar_day: int,
259
                   hour: int, minute: int, second: int) -> 'LunarTime': ...
260
    
261
    def getMinHm(self) -> str: ...  # Start time in HH:MM format
262
    def getMaxHm(self) -> str: ...  # End time in HH:MM format
263
```
264

265
### Holiday Information
266

267
Helper class for working with official holidays and work days.
268

269
```python { .api }
270
class Holiday:
271
    def __init__(self, day: str, name: str, work: bool, target: str): ...
272
    # day: date in YYYY-MM-DD format
273
    # name: holiday name
274
    # work: whether it's a make-up work day  
275
    # target: associated holiday date
276
    
277
    def getDay(self) -> str: ...  # Holiday date (YYYY-MM-DD)
278
    def getName(self) -> str: ...  # Holiday name
279
    def isWork(self) -> bool: ...  # Is this a make-up work day
280
    def getTarget(self) -> str: ...  # Associated holiday date
281
    def toString(self) -> str: ...
282
```
283

284
### Constants
285

286
```python { .api }
287
# Julian day constant for 2000-1-1
288
Solar.J2000 = 2451545
289

290
# Month constants
291
SolarYear.MONTH_COUNT = 12
292
```
293

294
## Usage Examples
295

296
### Basic Conversion
297

298
```python
299
from lunar_python import Solar, Lunar
300

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

307
# Create lunar date and convert to solar  
308
lunar = Lunar.fromYmd(2023, 4, 11)
309
solar = lunar.getSolar()
310
print(f"Lunar: {lunar.toString()}")
311
print(f"Solar: {solar.toString()}")
312
```
313

314
### Date Arithmetic
315

316
```python
317
from lunar_python import Solar
318

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

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

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

329
# Calculate difference
330
other = Solar.fromYmd(2023, 6, 15)
331
diff = other.subtract(solar)
332
print(f"Difference: {diff} days")
333
```
334

335
### Working with Time Periods
336

337
```python
338
from lunar_python import SolarYear, LunarYear
339

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

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