On Mon, Oct 24, 2011 at 06:17, Antoine Pitrou wrote:

On Mon, 24 Oct 2011 15:58:11 +0300 Ezio Melotti 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@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org

On Mon, Nov 28, 2011 at 7:53 PM, Xavier Morel wrote:

Not being too eager to kill APIs is good, but giving rise to this kind of living-dead APIs is no better in my opinion, even more so since Python has lost one of the few tools it had to manage them (as DeprecationWarning was silenced by default). Both choices are harmful to users, but in the long run I do think zombie APIs are worse.

But restricting ourselves to cleaning out such APIs every 10 years or so with a major version bump is also a potentially viable option. So long as the old APIs are fully tested and aren't actively *harmful* to creating reasonable code (e.g. optparse) then refraining from killing them before the (still hypothetical) 4.0 is reasonable. OTOH, genuinely problematic APIs that ideally wouldn't have survived even the 3.x transition (e.g. the APIs that the 3.x subprocess module inherited from the 2.x commands module that run completely counter to the design principles of the subprocess module) should probably still be considered for removal as soon as is reasonable after a superior alternative is made available. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia

Xavier Morel wrote:

Not being too eager to kill APIs is good, but giving rise to this kind of living-dead APIs is no better in my opinion, even more so since Python has lost one of the few tools it had to manage them (as DeprecationWarning was silenced by default). Both choices are harmful to users, but in the long run I do think zombie APIs are worse.

I would much rather have my code relying on "zombie" APIs and keep working, than to have that code suddenly stop working when the zombie is removed. Working code should stay working. Unless the zombie is actively harmful, what's the big deal if there is a newer, better way of doing something? If it works, and if it's fast enough, why force people to "fix" it? It is a good thing that code or tutorials from Python 1.5 still (mostly) work, even when there are newer, better ways of doing something. I see a lot of newbies, and the frustration they suffer when they accidentally (carelessly) try following 2.x instructions in Python3, or vice versa, is great. It's bad enough (probably unavoidable) that this happens during a major transition like 2 to 3, without it also happening during minor releases. Unless there is a good reason to actively remove an API, it should stay as long as possible. "I don't like this and it should go" is not a good reason, nor is "but there's a better way you should use". When in doubt, please don't break people's code. -- Steven

On Mon, Nov 28, 2011 at 11:14 PM, Steven D'Aprano wrote:

Xavier Morel wrote:

...

Not being too eager to kill APIs is good, but giving rise to this kind of living-dead APIs is no better in my opinion, even more so since Python has lost one of the few tools it had to manage them (as DeprecationWarning was silenced by default). Both choices are harmful to users, but in the long run I do think zombie APIs are worse.

I would much rather have my code relying on "zombie" APIs and keep working, than to have that code suddenly stop working when the zombie is removed. Working code should stay working. Unless the zombie is actively harmful, what's the big deal if there is a newer, better way of doing something? If it works, and if it's fast enough, why force people to "fix" it?

It is a good thing that code or tutorials from Python 1.5 still (mostly) work, even when there are newer, better ways of doing something. I see a lot of newbies, and the frustration they suffer when they accidentally (carelessly) try following 2.x instructions in Python3, or vice versa, is great. It's bad enough (probably unavoidable) that this happens during a major transition like 2 to 3, without it also happening during minor releases.

Unless there is a good reason to actively remove an API, it should stay as long as possible. "I don't like this and it should go" is not a good reason, nor is "but there's a better way you should use". When in doubt, please don't break people's code.

This is a great argument. But people want to see new, bigger better things in the standard library, and the #1 reason cited against this is "we already have too much". I think that's where the issue lies: Either lots of cool nice stuff is added and supported (we all want our favourite things in the standard lib for this reason), and or the old stuff lingers... I'm sure a while ago there was mention of a "staging" area for inclusion in the standard library. This attracts interest, stabilization, and quality from potential modules for inclusion. Better yet, the existing standard library ownership is somehow detached from the CPython core, so that changes enabling easier customization to fit other implementations (jpython, pypy etc.) are possible. tl;dr old stuff blocks new hotness. make room or separate standard library concerns from cpython

-- Steven _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/anacrolix%40gmail.com

On Tue, 29 Nov 2011 00:19:50 +0900 "Stephen J. Turnbull" wrote:

Deprecated features are pretty much irrelevant to the height of the bar for new features. The problem is that there are a limited number of folks doing long term maintenance of the standard library, and an essentially unlimited supply of one-off patches to add cool new features (not backed by a long term warranty of maintenance by the contributor).

Actually, we don't often get patches for new features. Many new features are implemented by core developers themselves. Regards Antoine.

Raymond Hettinger wrote:

How about we agree that actually removing things is usually bad for users. It will be best if the core devs had a strong aversion to removal. Instead, it is best to mark APIs as obsolete with a recommendation to use something else instead.

There is rarely a need to actually remove support for something in the standard library.

That may serve a notion of tidyness or somesuch but in reality it is a PITA for users making it more difficult to upgrade python versions and making it more difficult to use published recipes.

I'm strongly against breaking backwards compatiblity between minor versions (e.g. 3.2 and 3.3). If something is removed in this manner, the transition period should at least be very, very long. To me, deprecating an API means "this code will not get new features and possibly not even (big) fixes". It's important for the long term health of a project to be able to deprecate and eventually remove code that is no longer maintained. So, I think we should have a clear and working deprecation policy, and Ezio's suggestion sounds good to me. There should be a clean way to state, in both code and documentation, that something is deprecated, do not use in new code. Furthermore, deprecated code should actually be removed when the time comes, be it Python 4.0 or something else. Petri

On 28/11/2011 13:36, Petri Lehtinen wrote:

...

How about we agree that actually removing things is usually bad for users. It will be best if the core devs had a strong aversion to removal. Instead, it is best to mark APIs as obsolete with a recommendation to use something else instead.

There is rarely a need to actually remove support for something in the standard library.

That may serve a notion of tidyness or somesuch but in reality it is a PITA for users making it more difficult to upgrade python versions and making it more difficult to use published recipes. I'm strongly against breaking backwards compatiblity between minor versions (e.g. 3.2 and 3.3). If something is removed in this manner,

Raymond Hettinger wrote: the transition period should at least be very, very long.

We tend to see 3.2 -> 3.3 as a "major version" increment, but that's just Python's terminology. Nonetheless, our usual deprecation policy has been a *minimum* of deprecated for two releases and removed in a third (if at all) - which is about five years from deprecation to removal given our normal release rate. The water is muddied by Python 3, where we may deprecate something in Python 3.1 and remove in 3.3 (hypothetically) - but users may go straight from Python 2.7 to 3.3 and skip the deprecation period altogether... So we should be extra conservative about removals in Python 3 (for the moment at least).

To me, deprecating an API means "this code will not get new features and possibly not even (big) fixes". It's important for the long term health of a project to be able to deprecate and eventually remove code that is no longer maintained.

The issue is that deprecated code can still be a maintenance burden. Keeping deprecated APIs around can require effort just to keep them working and may actively *prevent* other changes / improvements. All the best, Michael Foord

So, I think we should have a clear and working deprecation policy, and Ezio's suggestion sounds good to me. There should be a clean way to state, in both code and documentation, that something is deprecated, do not use in new code. Furthermore, deprecated code should actually be removed when the time comes, be it Python 4.0 or something else.

Petri _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.u...

-- http://www.voidspace.org.uk/ May you do good and not evil May you find forgiveness for yourself and forgive others May you share freely, never taking more than you give. -- the sqlite blessing http://www.sqlite.org/different.html

On Tue, Nov 29, 2011 at 02:46:06PM +0200, Petri Lehtinen wrote:

Michael Foord wrote:

...

We tend to see 3.2 -> 3.3 as a "major version" increment, but that's just Python's terminology.

Even though (in the documentation) Python's version number components are called major, minor, micro, releaselevel and serial, in this order? So when the minor version component is increased it's a major version increment? :)

When the major version component is increased it's a World Shattering Change, isn't it?! ;-) Oleg. -- Oleg Broytman http://phdru.name/ phd@phdru.name Programmers don't die, they just GOSUB without RETURN.

On Nov 29, 2011, at 01:59 PM, Antoine Pitrou wrote:

Well, that's why I think the version number components are not correctly named. I don't think any of the 2.x or 3.x releases can be called "minor" by any stretch of the word. A quick glance at http://docs.python.org/dev/whatsnew/index.html should be enough.

Agreed, but it's too late to change it. I look at it as the attributes of the namedtuple being evocative of the traditional names for the digit positions, not the assignment of those positions to Python's semantics. -Barry

2011/11/29 Nick Coghlan :

On Wed, Nov 30, 2011 at 1:13 AM, Barry Warsaw wrote:

...

On Nov 29, 2011, at 01:59 PM, Antoine Pitrou wrote:

...

Well, that's why I think the version number components are not correctly named. I don't think any of the 2.x or 3.x releases can be called "minor" by any stretch of the word. A quick glance at http://docs.python.org/dev/whatsnew/index.html should be enough.

Agreed, but it's too late to change it.  I look at it as the attributes of the namedtuple being evocative of the traditional names for the digit positions, not the assignment of those positions to Python's semantics.

Hmm, I wonder about that. Perhaps we could add a second set of names in parallel with the "major.minor.micro" names: "series.feature.maint".

That would, after all, reflect what is actually said in practice: - release series: 2.x, 3.x  (usually used in a form like "In the 3.x series, X is true. In 2.x, Y is true) - feature release: 2.7, 3.2, etc - maintenance release: 2.7.2, 3.2.1, etc

I know I tend to call feature releases major releases and I'm far from alone in that. The discrepancy in relation to sys.version_info is confusing, but we can't make 'major' refer to a different field without breaking existing programs. But we *can* change:

...

...

...

sys.version_info sys.version_info(major=2, minor=7, micro=2, releaselevel='final', serial=0)

to instead read:

sys.version_info(series=2, feature=7, maint=2, releaselevel='final', serial=0)

while allowing 'major' as an alias of 'series', 'minor' as an alias of 'feature' and 'micro' as an alias of 'maint'. Nothing breaks, and we'd have started down the path towards coherent terminology for the three fields in the version numbers (by accepting that 'major' has now become irredeemably ambiguous in the context of CPython releases).

This idea of renaming all three fields has come up before, but I believe we got stuck on the question of what to call the first number (i.e. the one I'm calling the "series" here).

Can we drop this now? Too much effort for very little benefit. We call releases what we call releases. -- Regards, Benjamin

Am 29.11.2011 13:46, schrieb Petri Lehtinen:

Michael Foord wrote:

...

We tend to see 3.2 -> 3.3 as a "major version" increment, but that's just Python's terminology.

Even though (in the documentation) Python's version number components are called major, minor, micro, releaselevel and serial, in this order? So when the minor version component is increased it's a major version increment? :)

Yes. Georg