Add generic vacanza.py script for exporting holiday calendars

[sinhaanushka]

Proposed change

This PR adds a generic example script 'vacanza.py' under the 'examples' directory.

The script demonstrates how to:

• Generate holiday calendars dynamically for a given country
• Export '.ics' files for each supported holiday category
• Reuse the existing 'ICalExporter' functionality

This serves as a reusable helper for future CLI or automation workflows.

My PR link : #3257

Fixes #3189

Type of change

-[x] Existing code/documentation/test/process quality improvement (best practice, cleanup, refactoring, optimization)

Checklist

• I've read and followed the contributing guidelines(https://github.com/vacanza/holidays/blob/dev/CONTRIBUTING.md).
• I've run 'make check' locally; all checks and tests passed.

[coderabbitai]

Caution

Review failed

Failed to post review comments

Summary by CodeRabbit

• New Features

  • Added an example script to export holiday calendars to ICS files per category, supporting multiple categories, flexible year ranges, language selection, and configurable output directory; continues processing remaining categories if one fails.

• Documentation

  • Provides a practical usage example demonstrating how to run exports and integrate resulting ICS files with calendar applications.

Walkthrough

Adds a new example script docs/examples/vacanza.py that exports per-category holiday calendars to .ics files by constructing holiday objects (years, categories, language), computing year labels, handling per-category exceptions, and saving with ICalExporter; includes a US-focused main invocation.

Changes

Cohort / File(s)	Summary
Holiday Calendar Export Example docs/examples/vacanza.py	New example script. Adds export_holiday_calendars(country_class, country_code, years, categories, language=None, output_dir="."), iterates categories to build holiday objects and year labels (handles range objects), constructs output_dir/<country>_<CATEGORY>_<year_label>.ics filenames, saves via ICalExporter, and continues on per-category exceptions; exposes a US-specific main call.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• Add iCalendar export support #2362: Adds holidays/ical.py and ICalExporter, which this example imports and uses.

Suggested reviewers

• arkid15r
• KJhellico
• PPsyrius

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR partially meets issue #3189 requirements: implements a generic script with dynamic category iteration and ICS export, but lacks full command-line argument support, year range handling, and public-holidays-only filtering.	Enhance the script to accept country code and year arguments from command line, implement year range parsing, and add optional public-holidays-only filtering as specified in #3189.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a generic vacanza.py script for exporting holiday calendars.
Description check	✅ Passed	The description clearly relates to the changeset, explaining the script's purpose and functionality for generating and exporting holiday calendars.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the script file is directly related to the feature request and follows the outlined objectives without introducing unrelated modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sinhaanushka]

I’ve addressed the CI issues by removing print statements, fixing formatting, and adding the required license header. I’ve also pushed an update to re-trigger the checks. Please let me know if there’s anything else I should adjust. Thanks!

[Surya-Jaiswal]

Hi @arkid15r and @KJhellico 👋

I noticed that PR #3257 was opened a few weeks ago for this, but it seems to be stalled. The automated review also noted that it's currently missing the core requirements discussed here: command-line argument support (country code, year ranges) and the --public-only filtering.

If the current author is no longer working on it, I would love to be assigned to this issue. I can open a fresh PR that cleanly implements the examples/vacanza.py script with all the requested CLI features and passing checks. Let me know if I can go ahead!