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

[digiDevemon]

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! 👍