[Feature request] vacanza-holidays.py to generate calendars for any country, year, etc

[davidhedlund]

Is your feature request related to a problem? Please describe.
It can be unintuitive and repetitive to manually write Python scripts for generating holiday calendar exports per country when using the holidays library. While the library provides excellent data coverage, users who want to create localized .ics calendar files (e.g., for all supported categories in multiple languages and year ranges) must currently craft individual scripts for each country. This makes it harder to automate or reproduce results consistently across regions.

Describe the solution you'd like
Implement a single generic script that accepts a country code as a command-line argument. The logic would dynamically check for supported_categories for that country and generate the corresponding .ics files.

If the user runs the script without an argument, it will print the specific error message showing an example (e.g., python3 examples/vacanza.py IN).

Implement a year argument instead of hardcoding a range. For example: python vacanza-sholidays.py US 2025

It would also be useful to include an option to list only public holidays to exclude de-facto holidays. For example:

python vacanza-holidays.py US 2025 public-holidays
python vacanza-holidays.py US 2020-2025

We will then place this script in examples/vacanza.py and include the documentation/usage in both docs/examples.md and README.md.

Describe alternatives you've considered

• Writing ad-hoc scripts manually for each desired country.
• Reviewing source code and documentation to reproduce the export logic for individual locales.
• Using a generalized generator script with dynamic input (though this requires deeper familiarity with the API than average users have).

Additional context
Including Python recipes per country would clarify how to use advanced features (such as categories, language support, and ICalExporter) efficiently. It would also create a consistent, educational reference area within the examples/ folder of the repository, helping both newcomers and automation-focused developers.

Example of a python recipe for sweden.py that may be reused (thanks KJhellico):

from holidays.countries.sweden import SE
from holidays.ical import ICalExporter

def generate():
    language = "sv"
    years = range(2021, 2031)

    for category in SE.supported_categories:
        holidays = SE(include_sundays=False, years=years, categories=category, language=language)
        file_path = f"SE_COMMON_{language.upper()}_{category.upper()}.ics"
        ICalExporter(holidays).save_ics(file_path)

if __name__ == "__main__":
    generate()

[arkid15r]

@davidhedlund sounds like a reasonable addition to https://holidays.readthedocs.io/en/latest/examples/#generate-icalendar-content-and-export-to-ics
Feel free to file a PR or delegate to community -- up to you.

[davidhedlund]

@davidhedlund sounds like a reasonable addition to https://holidays.readthedocs.io/en/latest/examples/#generate-icalendar-content-and-export-to-ics

Thank you.

Feel free to file a PR or delegate to community -- up to you.

Unfortunate I don't have time for that. I contribute on an ecosystem level within the free software community; I just want to share my best advice because I believe in your project, which is why I've submitted my issues to this repo.

[arkid15r]

@davidhedlund np, this will be addressed soon.
Thanks for raising!

[KJhellico]

example scripts for each country

Sample for each country seems excessive. It's enough to replace country code.

[Upanshi-Mittal]

Hi @arkid15r , I’d like to work on this issue if it’s still available.

From the discussion, my understanding is:

• We don’t need country-specific scripts
• Instead, we can improve documentation by adding a single reusable Python recipe
  that shows how to generate .ics files for any country by changing the country code,
  language, categories, and year range.

I’m happy to update docs/examples.md accordingly.
Please let me know if this approach sounds good. Thanks!

[davidhedlund]

example scripts for each country

Sample for each country seems excessive. It's enough to replace country code.

I thought that the categories are customized for the countries.

[davidhedlund]

Hi @arkid15r , I’d like to work on this issue if it’s still available.

From the discussion, my understanding is:

* We **don’t need country-specific scripts**

* Instead, we can **improve documentation** by adding a single reusable Python recipe
  that shows how to generate `.ics` files for any country by changing the country code,
  language, categories, and year range.

I’m happy to update docs/examples.md accordingly. Please let me know if this approach sounds good. Thanks!

A python script that requires country code as argument would be useful (e.g. python3 vacanza.py us).

[akg5053]

Thanks for the clarification

That makes sense — I’ll keep the example generic and avoid country-specific scripts.
I’ll ensure the recipe shows how to replace the country code and handle categories dynamically.

I’ll proceed with updating docs/examples.md with a single reusable Python example and open a PR shortly.

[davidhedlund]

Thanks for the clarification

That makes sense — I’ll keep the example generic and avoid country-specific scripts. I’ll ensure the recipe shows how to replace the country code and handle categories dynamically.

I’ll proceed with updating docs/examples.md with a single reusable Python example and open a PR shortly.

Also make sure that the script prints that a country code argument is provided if it is not added. For example:

python3 vacanza.py
You need to provide a country code as argument, e.g.: vacanza.py us

[davidhedlund]

@akg5053 Also, it would be helpful if the same script was added to README.md.

[pareshjoshij]

Hi @davidhedlund,

I'd like to verify if I understood the requirements correctly. Is this the right approach?

Technically, we can implement a single generic script that accepts a country code as a command-line argument. The logic would dynamically check for supported_categories for that country and generate the corresponding .ics files.

If the user runs the script without an argument, it will print the specific error message showing an example (e.g., python3 examples/vacanza.py IN).

We will then place this script in examples/vacanza.py and include the documentation/usage in both docs/examples.md and README.md.

Is this the correct approach?

[davidhedlund]

Is this the correct approach?

Yes!

Naming it holidays.py or vacanza-holidays.py would better reflect the repository name in the script. The vacanzy.py suggestion was just a quick way to make it unique.