CalendarCraft - 节假日日历生成器

A powerful command-line tool to generate holiday calendars with multi-country support and Chinese solar terms.

🌟 Features

Three Types of Calendar Files

• Holidays Only: Contains public holidays for selected countries
• Solar Terms Only: Contains Chinese 24 solar terms (China only)
• Complete Calendar: Contains both holidays and solar terms (China only)

Data Sources

• General Country Holidays: Uses https://date.nager.at/api/v3/ API
• Chinese Special Holidays: Uses https://holiday.cyi.me/api/holidays?year={year} (includes work makeup days)
• 24 Solar Terms: Calculated using simplified astronomical calculations

User Experience

• ASCII art world map for country selection
• Interactive menu system
• Year selection (supports historical years)
• Progress indicators and colored output

🚀 Quick Start

Installation

1. Clone the repository:

git clone https://github.com/PageSecOnd/CalendarCraft.git
cd CalendarCraft

2. Install dependencies:

pip install -r requirements.txt

3. Run the application:

python main.py

📋 Usage

1. Start the Application: Run python main.py
2. Select Country: Choose from the ASCII world map display
3. Choose Year: Enter desired year (default: current year)
4. Select Calendar Type: Choose from available options
5. Generate Calendar: Wait for file generation
6. Import to Calendar: Use the generated .ics file in your calendar app

Example Usage

$ python main.py

🌍 Welcome to CalendarCraft - Holiday Calendar Generator
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ASCII World Map Display]

🌍 Select country (enter 2-letter code): CN
✅ Selected: 🇨🇳 China (CN)

📅 Select year (default: 2025): 2025
✅ Selected year: 2025

📋 Select calendar type (1-3, 0 to go back):
1. Holidays Only
2. Solar Terms Only (24节气)
3. Complete Calendar (Holidays + Solar Terms)

Choice: 3

🚀 Generating Complete Calendar for CN 2025...
✅ Calendar generated successfully!
   📁 File: calendars/CN_2025_complete_20250806.ics
   📊 Events: 35
   💾 Size: 12.3 KB

📁 Output Files

Generated calendar files are saved in the calendars/ directory with the naming format:

{country_code}_{year}_{type}_{timestamp}.ics

Examples:

• CN_2025_holidays_20250806.ics - Chinese holidays for 2025
• CN_2025_solar_terms_20250806.ics - 24 solar terms for 2025
• CN_2025_complete_20250806.ics - Complete calendar for 2025

🏗️ Project Structure

CalendarCraft/
├── main.py                 # Main program entry point
├── src/
│   ├── __init__.py         # Package initialization
│   ├── api_client.py       # API client for holiday data
│   ├── solar_terms.py      # 24 solar terms calculation
│   ├── calendar_generator.py # ICS file generation
│   ├── world_map.py        # ASCII world map display
│   └── utils.py            # Common utilities
├── calendars/              # Generated calendar files
├── requirements.txt        # Python dependencies
└── README.md              # This file

🔧 Dependencies

• requests - HTTP API requests
• icalendar - ICS calendar file generation
• pytz - Timezone handling
• colorama - Terminal colored output

🌏 Supported Countries

The application supports all countries available through the Nager.Date API, including but not limited to:

• 🇨🇳 China (with special solar terms support)
• 🇺🇸 United States
• 🇬🇧 United Kingdom
• 🇩🇪 Germany
• 🇯🇵 Japan
• 🇰🇷 South Korea
• 🇫🇷 France
• 🇮🇹 Italy
• 🇪🇸 Spain
• 🇨🇦 Canada
• 🇦🇺 Australia
• 🇮🇳 India
• 🇧🇷 Brazil
• 🇷🇺 Russia
• 🇲🇽 Mexico
• 🇿🇦 South Africa

🎨 Features

ASCII World Map

• Visual country selection interface
• Highlighted available countries
• Clear country code indicators

Chinese Solar Terms (24节气)

When selecting China, you can generate calendars containing the traditional 24 solar terms:

• 立春 (Beginning of Spring)
• 雨水 (Rain Water)
• 惊蛰 (Awakening of Insects)
• 春分 (Spring Equinox)
• 清明 (Clear and Bright)
• 谷雨 (Grain Rain)
• ... and 18 more

Error Handling

• Network request retries
• Input validation
• Graceful error messages
• Fallback mechanisms

🛠️ Development

Running Tests

# Test individual modules
python -c "import src.api_client; print('API client test passed')"
python -c "import src.solar_terms; print('Solar terms test passed')"
python -c "import src.calendar_generator; print('Calendar generator test passed')"

Adding New Features

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section above
2. Open an issue on GitHub
3. Provide detailed error messages and system information

🎯 Future Enhancements

• More precise solar term calculations
• Additional calendar formats (CSV, JSON)
• Web interface
• Custom holiday definitions
• Recurring event support
• Multiple timezone support