Seth Michael Larson: Deprecations via warnings don’t work for Python libraries
Last weekurllib3 v2.6.0 was releasedwhich contained removals for several APIs that we've known were problematic since 2019 andhave been deprecated since 2022. The deprecations were marked in the documentation, changelog, and what I incorrectly believed would be the most meaningful signal to users:with aDeprecationWarningbeing emittedfor each use for the API.
The API that urllib3 recommended users use instead has the same features and no compatibility issues between urllib3 1.x and 2.x:
This API was emitting warnings for over 3 years in a top-3 Python package by downloads urging libraries and users to stop using the API andthat was not enough. We still received feedback from users that this removal was unexpected and was breaking dependent libraries. We ended upadding the APIs backand creating a hurried release to fix the issue.
It's not clear to me that waiting longer would have helped, either. The libraries that were impacted are actively developed, like the Kubernetes client, Fastly client, and Airflow and I trust that if the message had reached them they would have taken action.
My conclusion from this incident is thatDeprecationWarningin its current state does not work for deprecating APIs, at least for Python libraries. That is unfortunate, asDeprecationWarningand thewarningsmoduleare easy-to-use, language-“blessed”, and explicit without impacting users that don't need to take action due to deprecations. Any other method of deprecating API features is likely to be home-grown and different across each project which is far worse for users and project maintainers.
Possible solutions?
DeprecationWarningis called out in the“ignored by default” listfor Python. I could ask for more Python developers to run with warnings enabled, but solutions in the form of “if only we could all just” are a folly. Maybe the answer is for each library to create its own “deprecation warning” equivalent just to not be in the “ignored by default” list:
Maybe the answer is to do away with advance notice and adopt SemVer with many major versions, similar to how Cryptography operates for API compatibility. Let me know if you have other ideas.
Thanks for keeping RSS alive! ♥
https://sethmlarson.dev/deprecations-via-warnings-dont-work-for-python-libraries?utm_campaign=rss
