Future version incompatibility warning

[arkid15r]

This is a starting point for the discussion of holidays package future backward incompatibility.

This is a future version incompatibility warning from Python Holidays library v{version}
to inform you about an upcoming change in our API versioning strategy that may affect your
project's dependencies. Starting from version 1.0 onwards, we will be following a loose form of
Semantic Versioning (SemVer) to provide clearer communication regarding any potential breaking
changes.

This means that while we strive to maintain backward compatibility, there might be occasional
updates that introduce breaking changes to our API. To ensure the stability of your projects,
we highly recommend pinning the version of our API that you rely on. You can pin your current
holidays v0.x dependency (e.g., holidays=={version}) or limit it (e.g., holidays<1.0) in order to
avoid potentially unwanted upgrade to the version 1.0 when it's released (ETA 2024Q4 - 2025Q1).

If you have any questions or concerns regarding this change, please don't hesitate to reach out
to us via https://github.com/vacanza/python-holidays/discussions/1800.

There will be no action required for those who has already taken care of the version pinning (or limiting it to <1.0) or will have it done within the nearest 6 months. We're going to provide migration guides and assist with actual code changes for other open source projects that depend on holidays.

[Lukas0907]

Is there any way to acknowledge/disable the warning? It shows up in the warnings summary section of pytest.

[Lukas0907]

I was actually thinking about an environment variable, similar to how SQLAlchemy handles warnings. But of course this works, thank you.

[arkid15r]

I was actually thinking about an environment variable, similar to how SQLAlchemy handles warnings. But of course this works, thank you.

PYTHONWARNINGS="ignore::DeprecationWarning:holidays"

[phillipuniverse]

What's the way to ignore this without ignoring all DeprecationWarnings from holidays?

[jonaslb]

This seems more specific: ignore::DeprecationWarning:holidays.deprecations.v1_incompatibility

[arkid15r]

Right, this is available starting from v0.60

[zettelbee]

Does this upgrade mean that there will be a stable version? Where can I find more information about it?

[arkid15r]

Thanks for the question, @digiDevemon!

The main idea is to move on from v0 version and be able to follow the SemVer versioning convention:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

I'll update the warning with SemVer link.

[sneha14]

@arkid15r ,
Hi, thanks for the heads up on the upcoming changes! Will there be updated documentation available to help with the transition to version 1.0, especially for those who need to migrate their code? Thanks!

[arkid15r]

@arkid15r , Hi, thanks for the heads up on the upcoming changes! Will there be updated documentation available to help with the transition to version 1.0, especially for those who need to migrate their code? Thanks!

Hi @sneha14,
Yes the documentation will be updated accordingly and I also plan to create a migration guide with old/new approach examples for smoother transitioning.

[jonaslb]

While adopting version 1 seems a completely reasonable change, I think it's not good form to fire a warning about it, when that warning has no way of being fixed other than ignoring all holidays deprecation warnings. Now you cannot use DeprecationWarning in the future, because you've just asked everyone to turn them off. Anyway, thanks for the library, I'm just a little unhappy about this warning that I cannot "fix".

[arkid15r]

@jonaslb @phillipuniverse I'll look into improving this in v0.60

Sorry for the poor implementation as it seems it's impossible to filter this out even by using FutureIncompatibilityWarning

[xavier]

It's fine to expect some breaking changes in a 0.x package. It's up to users to wrap their dependencies to guard against such changes.

This unactionable warning at import time is overzealous. By now, the team must have an idea of which parts of the API are stabler than others and could raise a DeprecationWarning when some unstable feature is being used.

Once 1.0 is out, this import time warning could be restored to the final 0.x release to nudge users to upgrade to the version with a stable API.

[arkid15r]

The point is that we don't want to introduce any breaking changes in v0 even though SemVer allows that.

The warning isn't unactionable, it asks users to take care of their holidays dependency in advance by limiting version upgrades to <1.0. This way they'll avoid a potential v1 incompatible upgrade surprise.

You can suppress the warning by ignore::DeprecationWarning:holidays.deprecations.v1_incompatibility path.

[jonaslb]

The warning isn't unactionable,

It is, because this warning is raised unconditionally, for no other reason than "to be on the safe side". Silencing it is merely an unusual, ugly and impractical workaround.

All other warnings I've seen in my life have been actual warnings relating to suboptimal/deprecated code, and were fixable by code adaptations. Generally, for major version bumps on other libraries, there can be deprecation warnings, but they're only used upon usage of deprecated APIs.

[xavier]

My previous attempts at silencing this warning were unsuccessful but the rule which you provided in you reply is working so I'll take that. Thanks! 👍

[electroly]

This is, in April 2025 and holidays v0.71, still showing up in pytest warnings. The length of this message dwarfs all of my actual test output. I'm already using the latest version of holidays and it's already pinned. I've done everything and I still have to see a giant warning from this minor dependency every time I run my tests. Please reconsider the way that this warning is done; this isn't a past-tense issue to consider for next time, it's happening right now and you can still change it in the next release.

[arkid15r]

Would adding ignore::DeprecationWarning:holidays.deprecations.v1_incompatibility ignore work for you?

[electroly]

It does work and we've added this to our test script, but we're annoyed by having to do it. holidays is a transitive dependency of some major Python packages and all of the users of those packages are getting your holidays warning because there's no way for one of your reverse dependencies to say "yes, I've taken care of this, the holidays package is properly pinned, please stop showing the warning" without making the end user squelch it themselves. I don't think this was a good way to do this, and I'm not even sure the effort was necessary--everyone already assumed this was semver, and that moving from 0.x to 1.x is the start of stability. That's true for roughly every package in the Python universe.

[Peque]

@arkid15r Since there is no ETA for V1 (and it has already shifted previously), it would be great to remove the warning for now. 😊

You can add it back in a few months when there is a realistic ETA or, alternatively, you may want to consider switching to semantic versioning earlier? In example, start using 0.72.0. As @electroly has mentioned, most packages in the Python ecosystem use semantic versioning and everyone would expect a switch to 1.x.x to possibly break something. If their application is critical enough, they would have pinned a specific version of holidays already, or they would have their own tests that would fail if behavior changes even without breaking the API.

[arkid15r]

@electroly @Peque thanks for the feedback! We'll discuss it and most likely get rid of the warning as suggested.

[arkid15r]

It was disabled in yesterday's (v0.72) release.

[electroly]

Thank you kindly. Much appreciated!

[arkid15r]

Thanks for the feedback and helping us progress smoothly!