Mailing List Archive

deprecated-removed
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#paragraph-level-markup


_______________________________________________
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/SWBM2N4EFPVQFP4TX6Q33L5OK2WPBFRU/
Code of Conduct: http://python.org/psf/codeofconduct/
Re: deprecated-removed [ In reply to ]
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#paragraph-level-markup
>
>
> _______________________________________________
> 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/SWBM2N4EFPVQFP4TX6Q33L5OK2WPBFRU/
> Code of Conduct: http://python.org/psf/codeofconduct/



--
Night gathers, and now my watch begins. It shall not end until my death.
_______________________________________________
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/STQ6JSRYODHMNIEYTYSCM3AZH3MSMRWC/
Code of Conduct: http://python.org/psf/codeofconduct/