[Python-Dev] Deprecation policy

[Brett Cannon]

On Mon, Oct 24, 2011 at 06:17, Antoine Pitrou <solipsis at pitrou.net> wrote:
> On Mon, 24 Oct 2011 15:58:11 +0300
> Ezio Melotti <ezio.melotti at gmail.com> wrote:
>>
>> I suggest to follow the following process:
>>    1) deprecate something and add a DeprecationWarning;
>>    2) decide how long the deprecation should last;
>>    3) use the deprecated-remove[1] directive to document it;
>>    4) add a test that fails after the update so that we remember to
>> remove it[2];
>
> This sounds like a nice process.

I have thought about this extensively when I did the stdlib reorg for
Python 3, and the only difference from approach Ezio's is proposing
was I was thinking of introducing a special deprecate() function to
warnings or something that took a Python version argument so it would
automatically turn into an error once the version bump occurred. But
then I realized other apps wouldn't necessarily care, so short of
adding an argument which let people specify a different version number
to compare against, I kind of sat on the idea. I also thought about
specifying when to go from PendingDeprecationWarning to
DeprecationWarning, but as has been suggested,
PendingDeprecationWarning is not really useful to the core anymore
since

But adding something to test.support for our tests which requires a
specified version # would also work and be less invasive to users, eg.

  with test.support.deprecated(remove_in='3.4'): deprecated_func()

And obviously if we don't plan on removing the feature any time soon,
the test can specify Python 4.0 as the removal version. But the
important thing is to require some specification in the test so we
don't forget to stick to our contract of when to remove something.

P.S.: Did we ever discuss naming py3k Python 4 instead, in honor of
King Arthur from Holy Grail not being able to ever count straight to
three (eg. the holy hand grenade scene)? Maybe we need to have the
next version of Python be Python 6 since the Book of Armaments says
you should have 4, and 5 is right out. =)

-Brett

>
>> PendingDeprecationWarnings:
>> * AFAIK the difference between PDW and DW is that PDW are silenced by
>> default;
>> * now DW are silence by default too, so there are no differences;
>> * I therefore suggest we stop using it, but we can leave it around[3]
>
> Agreed as well.
>
>> [3]: we could also introduce a MetaDeprecationWarning and make
>> PendingDeprecationWarning inherit from it so that it can be used to
>> pending-deprecate itself.  Once PendingDeprecationWarning is gone, the
>> MetaDeprecationWarning will become useless and can then be used to
>> meta-deprecate itself.
>
> People may start using MetaDeprecationWarning to deprecate their
> metaclasses. It sounds wrong to deprecate it.
>
> Regards
>
> Antoine.
>
>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
>