I always thought that the "deprecated" directive is used if the term of removing the deprecated feature is not set yet, and the "deprecated-removed" directive is used if it is set. After removing the feature both directives are replaced with the "versionchanged" directive which only specifies the version of removing, not version of deprecation. But after reading the devguide [1] I am no longer so confident. The devguide clearly describes it as specifying version at which the feature "is" removed, not "will be" removed. Maybe I always used this directive incorrectly? Or its meaning was changed with time? Or I incorrectly understand the devguide wording? Or devguide is incorrect? Before 3.8 I only seen "deprecated-removed" with future removing version. The first use "deprecated-removed" for feature which is already deleted happened in 3.8 (maybe the directive was just not updated), and there are now many uses for features removed in asyncio in 3.10. What was the initial meaning of "deprecated-removed", how it should be used now, and is the devguide correct? [1] https://devguide.python.org/documenting/?highlight=deprecated-removed#paragr...
Hi Serhiy, For me, "deprecated" should be used if the removal is *not* planned: the feature is too popular, and removing it would break too much 3rd party code. "deprecated-removal" should be used if the feature removal *is* planned. IMO it's ok if we forget to remove the feature and keep it longer than expected. But it should help users to raise their awareness that the removal *will* happen. Having a release version gives a deadline. Victor On Wed, Sep 8, 2021 at 12:37 PM Serhiy Storchaka <storchaka@gmail.com> wrote:
I always thought that the "deprecated" directive is used if the term of removing the deprecated feature is not set yet, and the "deprecated-removed" directive is used if it is set. After removing the feature both directives are replaced with the "versionchanged" directive which only specifies the version of removing, not version of deprecation.
But after reading the devguide [1] I am no longer so confident. The devguide clearly describes it as specifying version at which the feature "is" removed, not "will be" removed. Maybe I always used this directive incorrectly? Or its meaning was changed with time? Or I incorrectly understand the devguide wording? Or devguide is incorrect?
Before 3.8 I only seen "deprecated-removed" with future removing version. The first use "deprecated-removed" for feature which is already deleted happened in 3.8 (maybe the directive was just not updated), and there are now many uses for features removed in asyncio in 3.10.
What was the initial meaning of "deprecated-removed", how it should be used now, and is the devguide correct?
[1] https://devguide.python.org/documenting/?highlight=deprecated-removed#paragr...
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/SWBM2N4E... Code of Conduct: http://python.org/psf/codeofconduct/
-- Night gathers, and now my watch begins. It shall not end until my death.
participants (2)
-
Serhiy Storchaka -
Victor Stinner