Deprecated xmllib module
Hmph. The xmllib module has been deprecated since Py2.0 but is not listed in PEP 4. Question: Do we have to keep it for another two years because of that omission? It seems somewhat silly to keep an obsolete, supplanted module that doesnt full support XML 1.0. Raymond
Raymond Hettinger wrote:
Hmph. The xmllib module has been deprecated since Py2.0 but is not listed in PEP 4.
Question: Do we have to keep it for another two years because of that omission?
It seems somewhat silly to keep an obsolete, supplanted module that doesn't full support XML 1.0.
it's better to be somewhat silly than to be arrogant and stupid. if python-dev cares about existing users, xmllib should stay in there until 3.0. </F>
Raymond Hettinger wrote:
Hmph. The xmllib module has been deprecated since Py2.0 but is not listed in PEP 4.
Question: Do we have to keep it for another two years because of that omission?
It seems somewhat silly to keep an obsolete, supplanted module that doesn’t full support XML 1.0.
I mostly agree with Fredrik. What good does removal of xmllib do? It's not that it is causing any maintenance burden, so we could just leave it in. Whether this means that we keep xmllib until P3k, I don't know. As for PEP 4: I don't know whether it needs to be listed there. It appears that the PEP is largely unmaintained (I, personally, do not really maintain it). So one option would be to just stop using PEP 4 for recording deprecations, since we now have the warnings module. If we want to keep PEP 4, we need to follow the procedures it requires (or modify them if we don't like them). Regards, Martin
As for PEP 4: I don't know whether it needs to be listed there. It appears that the PEP is largely unmaintained (I, personally, do not really maintain it). So one option would be to just stop using PEP 4 for recording deprecations, since we now have the warnings module.
+1 Raymond
It seems somewhat silly to keep an obsolete, supplanted module that doesnt full support XML 1.0.
I mostly agree with Fredrik. What good does removal of xmllib do?
A few thoughts: * Deprecated modules just get moved to the lib-old directory. If someone has ancient code relying on the module, it is a somewhat trivial maintenance step to add lib-old to their PYTHONPATH. IOW, I fail to see the harm. * For this particular module, xmllib, about six years will have elapsed between its original deprecation in Py2.0 and us taking it out in a Py2.5 release. * The number one current python complaint is the state of the standard library: http://www.internetnews.com/dev-news/article.php/3441931 . Some of this may just be the fruits of AMK's highly publicized journal entry; however, I think the concerns about library quality will persist. * The average quality of the library improves as we take out junk (the tzparse module for example) and put in high quality modules like logging, csv, decimal, etc. * After working through the tutorial, another huge task for aspiring intermediate Python programmer is to learn about the standard library. That task is made much difficult by the presence of obsolete, incomplete, and/or supplanted modules. For example, the high quality, actively maintained email package supplants several older, incomplete, or non-actively maintained modules. The library would be cleaner, more presentable, and easier to use if the old ones were to fall by the wayside. * Ideally, the library will develop in a way that doesn't have a cluttered concept space. This will help get it back to the point where you can hold it in your head all at once and still be able to think about the problem domain. Keeping cruft impedes that goal. my two cents, Raymond
Raymond Hettinger wrote:
* Deprecated modules just get moved to the lib-old directory. If someone has ancient code relying on the module, it is a somewhat trivial maintenance step to add lib-old to their PYTHONPATH. IOW, I fail to see the harm.
I have never considered this as an official policy. For example, when deprecated C modules are removed, they are never moved to lib-old.
* For this particular module, xmllib, about six years will have elapsed between its original deprecation in Py2.0 and us taking it out in a Py2.5 release.
Correct. For regex, much more time has passed (it is deprecated since 1.5 or something).
* The number one current python complaint is the state of the standard library: http://www.internetnews.com/dev-news/article.php/3441931 . Some of this may just be the fruits of AMK's highly publicized journal entry; however, I think the concerns about library quality will persist.
I agree. Removing old modules might change this, indeed: the complaint about unstability and incompatibility might then become the number one complaint :-)
* The average quality of the library improves as we take out junk (the tzparse module for example) and put in high quality modules like logging, csv, decimal, etc.
I am not convinced that all these more recent modules are really higher quality than the modules that have been added ten years ago. Some are (especially those which has seen extensive testing before being integrated), some are not (especially those added in an ad-hoc manner). Regards, Martin
On Sunday 05 December 2004 21:40, Raymond Hettinger wrote:
* The number one current python complaint is the state of the standard library: http://www.internetnews.com/dev-news/article.php/3441931 . Some of this may just be the fruits of AMK's highly publicized journal entry; however, I think the concerns about library quality will persist.
* The average quality of the library improves as we take out junk (the tzparse module for example) and put in high quality modules like logging, csv, decimal, etc.
We can't win - if we remove it, we'll get massive numbers of complaints bitching about us breaking backwards compatibility. I think the solution is to make sure the library docs say, very clearly, in big words at the top of the relevant page "DON'T DO NEW CODE WITH THIS MODULE". Perhaps Fred can make latex2html output a <blink> tag around it <wink>. The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger? Should the global module index should grow a "(deprecated)" line next door to the module name of the modules that are known to be old and kinda awful (such as xmllib)? Or make a seperate category - normal modules, and modules-that-are-only-kept-for-backwards compat? I suspect that rfc822 will end up in that latter category, rather than ever being removed (at least, until 3.0). I went through just my own code, and found an amazing amount of use of that module. Python has a reputation for stability and not forcing people to rewrite their code - I think that this is a good thing. IOW, I think breaking code is far worse than some folks whining that some of the stdlib is old and crufty. Alternately, we could lock the folks complaining about the stdlib's state in a room with the folks who complain that every new thing has "wrecked the language that they knew and loved" and let them fight it out.
* After working through the tutorial, another huge task for aspiring intermediate Python programmer is to learn about the standard library. That task is made much difficult by the presence of obsolete, incomplete, and/or supplanted modules.
Surely this one is something that can be fixed in the documentation by marking obsolete modules as such, or making the marking much clearer? Anthony
Anthony Baxter wrote:
The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger?
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
Alternately, we could lock the folks complaining about the stdlib's state in a room with the folks who complain that every new thing has "wrecked the language that they knew and loved" and let them fight it out.
That sounds like a fair and democratic way of solving the issue. Regards, Martin
Martin v. Löwis wrote:
Anthony Baxter wrote:
The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger?
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
I like this solution. And if anyone cares about having good docs still for a deprecated module they can just read the docstrings. We don't get new people using it but others don't have to change their code. And as for the mention of dropping PEP 4, I agree with the running consensus that it isn't needed thanks to the warning module. Do we need to have a more formal vote to drop PEP 4, or should one the PEP maintainers just delete it? -Brett
On Sun, 2004-12-05 at 18:49, Brett C. wrote:
And as for the mention of dropping PEP 4, I agree with the running consensus that it isn't needed thanks to the warning module. Do we need to have a more formal vote to drop PEP 4, or should one the PEP maintainers just delete it?
There's really no such thing as "dropping" a PEP, but in any event, we should still keep PEP 4 to document the procedure for deprecating modules. It just doesn't need to list any modules (i.e. remove the sections labeled Obsolete modules, Deprecated modules, and Undeprecated modules). -Barry
Brett C. wrote:
And as for the mention of dropping PEP 4, I agree with the running consensus that it isn't needed thanks to the warning module. Do we need to have a more formal vote to drop PEP 4, or should one the PEP maintainers just delete it?
I would do what Barry suggests: rephrase the module to document the deprecation/removal procedure. This, of course, needs consensus/pronouncement, too, but I think I would put the following aspects into it: Requirements ============ Removal of module needs proper advance warning for users; the module should be removed only if - continued usage poses a security threat to the application using it, or - there are no reported usages of the module anymore for quite some time - the module is unmaintained (i.e. there are serious outstanding unfixed bugs for it), and there are alternatives which are maintained. There must be a way for users to stop removal of the module, e.g. by volunteering to maintain an unmaintained module. Deprecation =========== If a module is candidate for removal, it must be deprecated first. In order to deprecate the module 1. a warning must be added to the module, indicating the expected version when the module is removed, and a reference to the PEP 2. a comment must be added just above the warning, giving a the date and version of deprecation, and a rationale for removal (e.g.: no known users, is security risk) 3. the module documentation must be removed from the Python documentation (alternatively: moved into a "deprecated" section) Undeprecation ============= A module can be undeprecated if the deprecation reasons turns out to be invalid, e.g. if users of the module appear when the module was believed to have no users, or if a maintainer shows up for a previously unmaintained module. This fact must be recorded in the module; the original state (documentation, no warning) be restored. Removal ======= If the module has been deprecated for atleast a year and atleast a version, it can be removed. Removal should move it to old-libs for pure Python modules; a removal procedure for pure C modules has not been defined yet. If the module was deprecated because it was unmaintained, the module should only be removed if there have been no recent reports about usage of the module. Bug reports against deprecated modules ====================================== If a bug is reported against a deprecated module, the bug report can be closed without further consideration, pointing to the deprecation status. If a patch is submitted against the module, it should be considered whether the patch could undeprecate the module; if not, it can be rejected with the same rationale. If this policy can be agreed, I will replace PEP4 with it. Modules that have currently deprecation messages in them often fail to identify the Python version in which removal will occur. For modules that have been deprecated since 2.1, I would suggest to remove them for 2.5, with the option of bringing them back in 2.5.1 if people complain. Regards, Martin
On Mon, 2004-12-06 at 16:28, "Martin v. Löwis" wrote: Martin, +1 on everything you wrote, with one minor quibble.
Removal ======= If the module has been deprecated for atleast a year and atleast a version, it can be removed. Removal should move it to old-libs for pure Python modules; a removal procedure for pure C modules has not been defined yet.
I wonder if the one year/one version rule is too short. Given that new versions come about every 18 months, I'd probably give it a 2 year/one version limit.
Modules that have currently deprecation messages in them often fail to identify the Python version in which removal will occur. For modules that have been deprecated since 2.1, I would suggest to remove them for 2.5, with the option of bringing them back in 2.5.1 if people complain
+1 here too. -Barry
Barry Warsaw wrote:
On Mon, 2004-12-06 at 16:28, "Martin v. Löwis" wrote:
Martin, +1 on everything you wrote, with one minor quibble.
Removal ======= If the module has been deprecated for atleast a year and atleast a version, it can be removed. Removal should move it to old-libs for pure Python modules; a removal procedure for pure C modules has not been defined yet.
I wonder if the one year/one version rule is too short. Given that new versions come about every 18 months, I'd probably give it a 2 year/one version limit.
+1 I'd make that 2 years / 2 versions, though. -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Dec 13 2004)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
2004-12-06: Released eGenix mx Extensions for Python 2.4 ::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::
I would do what Barry suggests: rephrase the module to document the deprecation/removal procedure. This, of course, needs consensus/pronouncement, too, but I think I would put the following aspects into it:
Requirements ============ Removal of module needs proper advance warning for users; the module should be removed only if - continued usage poses a security threat to the application using it, or - there are no reported usages of the module anymore for quite some time - the module is unmaintained (i.e. there are serious outstanding unfixed bugs for it), and there are alternatives which are maintained. There must be a way for users to stop removal of the module, e.g. by volunteering to maintain an unmaintained module.
The effect of coding this into the PEP is to make deprecation unnecessarily involved. Also, the list of reasons is insufficiently comprehensive. In the past we've gotten along fine with discussing a situation on python-dev and either reaching a consensus or having Guido give an okay.
2. a comment must be added just above the warning, giving a the date and version of deprecation, and a rationale for removal (e.g.: no known users, is security risk)
We should only talk in terms of versions. Dates are irrelevant and confusing. In the last version of the PEP, it was far from clear the significane of deprecating or removing on date xx-xx-xx. All that matters is the version the warning first appears and the version where the module is removed.
Modules that have currently deprecation messages in them often fail to identify the Python version in which removal will occur. For modules that have been deprecated since 2.1, I would suggest to remove them for 2.5, with the option of bringing them back in 2.5.1 if people complain.
I do not think the version number messages are useful. When someone imports a file and gets a warning, they know a deprecation is pending and to stop writing code with that module. Further, I want to avoid the previous PEP 4 situation where one nit or another wasn't followed to the letter so we had to keep the module around for another two versions. It can and should be as simple as having us agree to deprecation, inserting a warning, and then removing it two versions later. Also, we need to shy away from the idea of having 2.5.1 with different capabilities than 2.5. This sort of thing is a portability disaster. Anthony, please speak up. General comments: I had thought the purpose of rewording the PEP was just to take out language naming specific modules and to add language on using the warning module. Instead, it looks like an attempt to make it much more difficult and slow to deprecate a module. If so, I would like to understand what situation is motivating it. Is there some module that had been deprecated but should not have been? Why the change in procedure? It doesn't affect me personally (I haven't proposed any modules for deprecation and do not have any in mind); however, I think the discussion should take place in the broader context of what we intend to do with the standard library -- do we want regex still there in 2010. Also, as proposed, the PEP lists many forces against deprecation and none of the forces for it. If that is the reality, then we could just never deprecate anything because someone, somewhere is bound to be irritated by it. That would certainly simplify the discussion. Going back to specifics, it may be worthwhile to think through the reason we kept the xmllib code but not whrandom. Both were documented, non-buggy, tested, marked as deprecated for a long time, and it was within the realm of possibility that some code still used them. Also, the PEP should discuss the use of the lib-old directory and it should include Barry's link to old documentation. Raymond
One other thought: In deciding how long to leave module in, we should consider that Python books are updated infrequently, if at all. It would be a bummer if code in them stopped working as advertised. Raymond
Raymond Hettinger wrote:
One other thought: In deciding how long to leave module in, we should consider that Python books are updated infrequently, if at all. It would be a bummer if code in them stopped working as advertised.
Correct. Thanks for reminding me - that is indeed a reasoning that is typically brought up by book authors, so I should have brought it up myself :-) Of course, developers would first see the deprecation warning, which would tell them that their books are outdated. However, if the code is removed, they get an import error, which leaves them guessing what the problem might have been. Regards, Martin
On Tuesday 07 December 2004 11:43, Raymond Hettinger wrote:
Modules that have currently deprecation messages in them often fail to identify the Python version in which removal will occur. For modules that have been deprecated since 2.1, I would suggest to remove them for 2.5, with the option of bringing them back in 2.5.1 if people complain.
[...]
Also, we need to shy away from the idea of having 2.5.1 with different capabilities than 2.5. This sort of thing is a portability disaster. Anthony, please speak up.
Sorry - been a bit busy the last few days. Raymond is right here - there's no way we can or should do this. A bugfix release contains _bugfixes_. Making new modules available in a bugfix is a sucky sucky approach. Worse - once we remove a module, it should _stay_ removed. Otherwise, we're going to end up with crap like: if sys.version < (2,5) or sys.version >= (2,6): import froggie else: # froggie was removed in 2.5 and reinstated in 2.6 from compat import froggie and people will be shipping their own versions of the code to get around our misfeature. -- Anthony Baxter <anthony@interlink.com.au> It's never too late to have a happy childhood.
Raymond Hettinger wrote:
The effect of coding this into the PEP is to make deprecation unnecessarily involved.
Can you please explain why you consider this involvement unnecessary? I think it is important that we do not prematurely remove (or even deprecate) modules that are still being actively used.
Also, the list of reasons is insufficiently comprehensive. In the past we've gotten along fine with discussing a situation on python-dev and either reaching a consensus or having Guido give an okay.
I don't think we "got along", but rather "got away". Discussion on python-dev does not cause sufficient user involvement, IMO. And indeed, some people (even on python-dev) think that we *never* should deprecate any modules, as it breaks existing code. They might not be as vocal as supporters of early removal of "ugly" code, but I think their opinion is just as valuable.
We should only talk in terms of versions. Dates are irrelevant and confusing.
Why is a date confusing? I think everybody on Earth understands the notion of a date, there is nothing confusing in this notion. Why are they irrelevant? If we release Python 2.5 next month (and stop developing 2.4), are we entitled to remove all features that were scheduled for removal? I think not: users would have not gotten sufficient advance warning. Users need *time* to react on proposed feature changes.
In the last version of the PEP, it was far from clear the significane of deprecating or removing on date xx-xx-xx. All that matters is the version the warning first appears and the version where the module is removed.
No. It also matters how much time users have had to react.
I do not think the version number messages are useful. When someone imports a file and gets a warning, they know a deprecation is pending and to stop writing code with that module.
Yes, but what about code that currently uses the module? People will not start rewriting (perhaps they aren't the authors in the first place) just because they see a deprecation warning. Instead, they will silence the warning, and go on. If we plan to remove the feature at some point, we need to give these users an indication that they need to act beyond silencing the warning. Such actions could be - have the author of the software update it appropriately - look for a replacement software - ask for an extension of the grace period on python-dev Currently, users do not really have these options, since they do not have an indication that action on their side is really needed if they want their software continue to work with future Python versions.
Further, I want to avoid the previous PEP 4 situation where one nit or another wasn't followed to the letter so we had to keep the module around for another two versions.
Why do you want to avoid that situation? What is the problem with waiting for two more versions? No harm is done in doing so.
It can and should be as simple as having us agree to deprecation, inserting a warning, and then removing it two versions later.
I strongly disagree with that position.
I had thought the purpose of rewording the PEP was just to take out language naming specific modules and to add language on using the warning module. Instead, it looks like an attempt to make it much more difficult and slow to deprecate a module.
I want the PEP to be followed. For that, it needs to be precise, and the procedures need to be agreed upon (or, if we cannot agree, it needs to be Pronounced).
If so, I would like to understand what situation is motivating it. Is there some module that had been deprecated but should not have been?
Deprecation is fine for all the modules so far. Generating the warning is a bit of a problem, removal would be a serious problem, for the following modules: - regex - xmllib - whrandom since I expect that these modules are still widely used, in existing code, by users who are not the authors of that code. This is a problem, since these users cannot do anything about the usage of the deprecated code. They just find that the software that ran happily with the previous Python version first shouts at them in the next Python version, then totally breaks with the subsequent version. They will hate Python for that.
Why the change in procedure?
I think we agree that the previously-documented procedure needs to be changed - it was not followed.
It doesn't affect me personally (I haven't proposed any modules for deprecation and do not have any in mind); however, I think the discussion should take place in the broader context of what we intend to do with the standard library -- do we want regex still there in 2010.
As to the latter question: Definitely. We don't want regex to be used for new code, and we want developers to fully understand that, but we also do want code that currently works correctly with regex continue to do so in 2010. The only exception would be that 2010 no code is left in active use that uses regex, which I doubt.
Also, as proposed, the PEP lists many forces against deprecation and none of the forces for it.
That is not true. Security flaws are giving priority. They can only be undeprecated if the reason for deprecation goes away, which means that somebody fixes the security flaw.
If that is the reality, then we could just never deprecate anything because someone, somewhere is bound to be irritated by it. That would certainly simplify the discussion.
Well, we do want to move developers to the new direction. However, many people use Python code who are *not* developers. We need to take their concerns into account as well.
Going back to specifics, it may be worthwhile to think through the reason we kept the xmllib code but not whrandom. Both were documented, non-buggy, tested, marked as deprecated for a long time, and it was within the realm of possibility that some code still used them.
Indeed. If it is in the realm of possibility that code still uses a module, and that this would not raise security concerns, the module should not be removed.
Also, the PEP should discuss the use of the lib-old directory and it should include Barry's link to old documentation.
I'm happy to adjust details of the procedures - but it seems we disagree on the principles. Regards, Martin
I'm happy to adjust details of the procedures - but it seems we disagree on the principles.
Further, I want to avoid the previous PEP 4 situation where one nit or another wasn't followed to
Not really. I have no objection to making module deprecation/removal rare or even not doing it at all. Personally, I've never asked for a module deprecation and don't expect to. I also agree that more public participation is a wise step. I would just like to see a clean, actionable PEP. To me, the draft text outlined a timid, faltering process that would be hard to follow, prone to reversal, and accomplish little. I especially find burdensome the obligation to undo a deprecation the moment some random user sends a grumpy email. Instead, there should be a clear decision to deprecate or not. If that entails a comp.lang.python.announce notice and comment period, so be it. Once a decision is made, document it, add a warning, and wait. Once a couple versions pass, some useful action needs to take place. If the code is left in-place and the doc index is just re-arranged, then we would have been better off not doing anything at all. Ideally, the PEP should also provide some informational value. It should list Barry's link as a reference for old docs. It should describe the appropriate use of lib-old (like whrandom) vs. renaming a module (like stringold) vs. leaving it in-place (like xmllib) vs. removing the module The questions of dates was somewhat minor. I was unclear on the implication of, for example, "remove on 15Jan2005". Since Py2.5 won't go out for at least a year, does that mean that the work can't be done now while I have time instead of later when I don't. The only time the removal becomes visible is when a new version goes out the door. Further, if a version is going to have something removed, we should do it at the outset rather than just before a release goes out the door (to allow for early surfacing of any issues). the
letter so we had to keep the module around for another two versions.
Why do you want to avoid that situation? What is the problem with waiting for two more versions? No harm is done in doing so.
If we really don't care whether it gets done, then we shouldn't bother in the first place. Raymond
There is one other issue that should get addressed, modules in limbo. I'm concerned about the old email modules. They haven't been deprecated and may stay around for a good while. However, some SF requests have been passed over on the basis that the modules are supplanted and will be phased out. I don't think it is good to leave active modules as orphans. Raymond
On Tue, 2004-12-07 at 03:12, Raymond Hettinger wrote:
I'm concerned about the old email modules. They haven't been deprecated and may stay around for a good while. However, some SF requests have been passed over on the basis that the modules are supplanted and will be phased out. I don't think it is good to leave active modules as orphans.
I would like to add deprecation warnings to some of the old email-related modules for Python 2.5, but I doubt we can remove any of them until Python 3.0 (or 2014, whichever comes first <wink>). -Barry
Raymond Hettinger wrote:
Instead, there should be a clear decision to deprecate or not. If that entails a comp.lang.python.announce notice and comment period, so be it. Once a decision is made, document it, add a warning, and wait.
Ok, that might be reasonable.
Once a couple versions pass, some useful action needs to take place. If the code is left in-place and the doc index is just re-arranged, then we would have been better off not doing anything at all.
I disagree. The primary purpose (move developers to the alternative approach) is achieved as soon as the warning is added, and the documentation is deleted. Whether the module is actually deleted is of minor importance: it costs nothing to continue including it; disk space is cheap.
The questions of dates was somewhat minor. I was unclear on the implication of, for example, "remove on 15Jan2005". Since Py2.5 won't go out for at least a year, does that mean that the work can't be done now while I have time instead of later when I don't. The only time the removal becomes visible is when a new version goes out the door.
You could remove it now, but if we release Py2.5 in two months, you would have to put it back in. So if you don't have time then, maybe somebody else will. If nobody has time to remove the module, the next release will ship with it, again - no big issue.
Further, if a version is going to have something removed, we should do it at the outset rather than just before a release goes out the door (to allow for early surfacing of any issues).
That is true.
If we really don't care whether it gets done, then we shouldn't bother in the first place.
What do you mean by "bother"? Not put the deprecation warning in? We do want users to move to the new approach of doing something. However, two version are just not enough - it may take 10 or 20 years to remove a widely used feature (e.g. the string module). That it will take so long does not mean we should not start the process *now* - if we start the process in five years, it will *still* take 10 or 20 years. Just be patient. Regards, Martin
Instead, there should be a clear decision to deprecate or not. If that entails a comp.lang.python.announce notice and comment period, so be it. Once a decision is made, document it, add a warning, and wait.
Ok, that might be reasonable.
Once a couple versions pass, some useful action needs to take place. If the code is left in-place and the doc index is just re-arranged,
Please word the PEP accordingly. then we
would have been better off not doing anything at all.
I disagree. The primary purpose (move developers to the alternative approach) is achieved as soon as the warning is added, and the documentation is deleted. Whether the module is actually deleted is of minor importance: it costs nothing to continue including it; disk space is cheap.
The questions of dates was somewhat minor. I was unclear on the implication of, for example, "remove on 15Jan2005". Since Py2.5 won't go out for at least a year, does that mean that the work can't be done now while I have time instead of later when I don't. The only time
That is reasonable. Please make that goal/assumption explicit in the PEP. the
removal becomes visible is when a new version goes out the door.
You could remove it now, but if we release Py2.5 in two months, you would have to put it back in. So if you don't have time then, maybe somebody else will. If nobody has time to remove the module, the next release will ship with it, again - no big issue.
Okay. Again, please say that in the PEP.
Further, if a version is going to have something removed, we should do it at the outset rather than just before a release goes out the door (to allow for early surfacing of any issues).
That is true.
That should also be recommended in the PEP.
If we really don't care whether it gets done, then we shouldn't bother in the first place.
What do you mean by "bother"? Not put the deprecation warning in? We do want users to move to the new approach of doing something. However, two version are just not enough - it may take 10 or 20 years to remove a widely used feature (e.g. the string module). That it will take so long does not mean we should not start the process *now* - if we start the process in five years, it will *still* take 10 or 20 years. Just be patient.
I see. That also may useful to include in the motivation section of the PEP. With these adjustments, I think the PEP will be fine. Also, be sure get rid of the mid-version undo (see Anthony's note) and to address the situation with Python books. I look forward to a revised draft. Raymond
One other question occurred to me for "deprecate X in favour of Y" situations - should the deprecation warning added to X point developers towards Y? Also, should the PEP include example wordings for deprecation warnings, rather than being completely freeform? Martin listed some information that should be included, but it seems an example or two would make it easy to get right. E.g.: Unmaintained, with a maintained alternative: "Due to lack of maintenance, this module has been deprecated in favour of module Y and will be removed in Python 2.6 (see PEP 4 for information on the deprecation process)" Security problems, no alternative: "Due to security concerns, this module has been deprecated and will be removed in Python 2.6 (see PEP 4 for information on the deprecation process)" Cheers, Nick. -- Nick Coghlan | ncoghlan@email.com | Brisbane, Australia --------------------------------------------------------------- http://boredomandlaziness.skystorm.net
On Tuesday 07 December 2004 04:46 am, Nick Coghlan wrote:
One other question occurred to me for "deprecate X in favour of Y" situations - should the deprecation warning added to X point developers towards Y?
Not sure about the warning, but the documentation certainly should. When the mapping from the old module to the new is not obvious and trivial, sufficient information should be included in the documentation for the old module to make it fairly easy to perform the conversion. (Placing this in the docs for the old module ensures that it goes away when the documentation for the old module goes away, and the docs for the new module need never be loaded with information about the old module.)
Also, should the PEP include example wordings for deprecation warnings, rather than being completely freeform? Martin listed some information that should be included, but it seems an example or two would make it easy to get right.
Examples would be good, though specific wording should not be proscribed. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
""Martin v. Löwis"" <martin@v.loewis.de> wrote in message news:41B556FE.20504@v.loewis.de... As a (currently) casual user of Python, this is my view of the standard library dilemma and its solution: 1. It is too small: I may someday want to use a module not yet added. 2. It is too big: I cannot keep everything in mind at once and cannot remember, without referring back to the lib manual or pydev, which modules are currently or slated to become deprecated. 3. I do not wish to have other people's code broken,or books made obsolete, without sufficient reason (ie, the code is actively dangerous versus merely broken or superceded). My preferred solution is to apply the 'out of sight, out of mind' principle. 1. Move obsolete modules to a separate directory (lib_old sounds fine) and put that directory in pythonpath. When I ran Python (1.3) from a 20 meg disk, I would have preferred complete removal, but with 60+ gigs, the small extra space is no longer an issue. If someone needs the space or wants to guarantee non-use of old modules, deleting lib_old is easy enough. 2. Remove the docs for obsolete modules from the main part of the current lib reference. Sub-choices for legacy chapters are either complete removal or segregation into a separate document or apppendix to current one. Terry J. Reedy
Martin v. Löwis wrote:
Anthony Baxter wrote:
The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger?
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
If we went down this path, I would suggest we include a list of deprecated modules in the docs to forestall "where is the documentation for these modules?" questions. Such a list would also make life easier for anyone stuck with maintaining legacy Python code. E.g. X.X Deprecated modules The following modules exist in the standard library solely for backwards compatibility with older versions of Python. They are no longer supported, and should not be used for new code. Anyone maintaining code using these modules should refer to the documentation for the Python version listed in the table below. Module Name | Last documented in: ------------------------------------- lib1 | Python 2.2 lib2 | Python 2.3 etc. . . I'd also suggest including a link to this list at the bottom of the global module index.
Alternately, we could lock the folks complaining about the stdlib's state in a room with the folks who complain that every new thing has "wrecked the language that they knew and loved" and let them fight it out.
That sounds like a fair and democratic way of solving the issue.
If we sold tickets, it could even be a nice little earner for the PSF ;) Cheers, Nick. -- Nick Coghlan | ncoghlan@email.com | Brisbane, Australia --------------------------------------------------------------- http://boredomandlaziness.skystorm.net
"Martin v. Löwis" <martin@v.loewis.de> writes:
Anthony Baxter wrote:
The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger?
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
+1, at least for *hiding* the documentation of xmllib + similar modules. I'm not sure wholesale removal is really a good idea. It's like the new "Non-essential Built-in Functions" section of the lib ref. Cheers, mwh -- <Acapnotic> jemfinch: What's to parse? A numeric code, perhaps a chicken, and some arguments -- from Twisted.Quotes
On Mon, 06 Dec 2004 12:12:48 +0000, Michael Hudson <mwh@python.net> wrote:
"Martin v. Löwis" <martin@v.loewis.de> writes:
Anthony Baxter wrote:
The library docs for, e.g. xmllib already say deprecated at the top - maybe it should be larger?
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
+1, at least for *hiding* the documentation of xmllib + similar modules. I'm not sure wholesale removal is really a good idea.
1) Move the deprecated documentation into a separate book. 2) Don't include the "Deprecated Modules Reference" in the standard distribution, but make it available as a separate download. -- Carlos Ribeiro Consultoria em Projetos blog: http://rascunhosrotos.blogspot.com blog: http://pythonnotes.blogspot.com mail: carribeiro@gmail.com mail: carribeiro@yahoo.com
Carlos Ribeiro wrote:
On Mon, 06 Dec 2004 12:12:48 +0000, Michael Hudson <mwh@python.net> wrote:
+1, at least for *hiding* the documentation of xmllib + similar modules. I'm not sure wholesale removal is really a good idea.
1) Move the deprecated documentation into a separate book.
2) Don't include the "Deprecated Modules Reference" in the standard distribution, but make it available as a separate download.
What about the idea of pointing to the last version of the docs that contained the relevant documentation? Cheers, Nick. -- Nick Coghlan | ncoghlan@email.com | Brisbane, Australia --------------------------------------------------------------- http://boredomandlaziness.skystorm.net
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
+1, at least for *hiding* the documentation of xmllib + similar modules. I'm not sure wholesale removal is really a good idea.
1) Move the deprecated documentation into a separate book.
2) Don't include the "Deprecated Modules Reference" in the standard distribution, but make it available as a separate download.
-1 We are trying to remove clutter, not keep it in perpetuity. Leaving the docs means continuing to have to test it, field bug reports, be aware of its existence, etc. Do not keep this on a respirator. Let it die in peace. Raymond
On Mon, 2004-12-06 at 07:44, Raymond Hettinger wrote:
We are trying to remove clutter, not keep it in perpetuity. Leaving the docs means continuing to have to test it, field bug reports, be aware of its existence, etc.
Do not keep this on a respirator. Let it die in peace.
Old documentation lives on in http://www.python.org/doc/versions.html which seems sufficient for looking up deprecated modules. -Barry
On Sun, 2004-12-05 at 18:54 +0100, "Martin v. Löwis" wrote:
I think it would be better to *remove* the xmllib documentation. Existing code which needs the module will continue to work even without documentation, and new code is unlikely to be written for a module that has no documentation, and where importing the module gives a DeprecationWarning.
Not sure I'm a registered voter, but I'll chip in with a +1 If someone needs the documentation for xmllib it will still be available in the older versions. Eirik.
On Sun, 2004-12-05 at 05:40, Raymond Hettinger wrote:
* The number one current python complaint is the state of the standard library: http://www.internetnews.com/dev-news/article.php/3441931 . Some of this may just be the fruits of AMK's highly publicized journal entry; however, I think the concerns about library quality will persist.
I don't know if I'd use one quote from this article to infer that standard library issues are the #1 complaint. But besides that, there's no question IMO that the standard library should be the place where future Python development efforts are focused (not exclusively, but predominately).
* The average quality of the library improves as we take out junk (the tzparse module for example) and put in high quality modules like logging, csv, decimal, etc.
* After working through the tutorial, another huge task for aspiring intermediate Python programmer is to learn about the standard library. That task is made much difficult by the presence of obsolete, incomplete, and/or supplanted modules.
You don't have to remove modules to make this happen. Few developers find modules by doing an 'ls' on Lib -- they look to the library reference docs, books, and existing code. So for example, the re-org I did on the string module docs for 2.4 should help, because now you can't look up a string function such as atoi() without seeing that it's deprecated. A developer writing new code hopefully wouldn't even waste time learning about those functions, and instead hop right to the preferred string methods. Yet, there's no push in the community to actually remove those deprecated functions from string.py.
For example, the high quality, actively maintained email package supplants several older, incomplete, or non-actively maintained modules. The library would be cleaner, more presentable, and easier to use if the old ones were to fall by the wayside.
Yes, but there's still /a lot/ of work to do to update the existing standard library to use the email package. We debated this during 2.4 and decided we can't even add deprecation warnings to things like rfc822.py until we do.
* Ideally, the library will develop in a way that doesn't have a cluttered concept space. This will help get it back to the point where you can hold it in your head all at once and still be able to think about the problem domain. Keeping cruft impedes that goal.
Agreed, but I think it's mostly going to be an organic process over time. -Barry
A report on the zope@zope.org list suggests that Python 2.4 is not fully compatible with Zope 2.7.3. Has any tested against Zope?
--On Sonntag, 5. Dezember 2004 10:30 Uhr -0800 Dennis Allison <allison@sumeru.stanford.EDU> wrote:
A report on the zope@zope.org list suggests that Python 2.4 is not fully compatible with Zope 2.7.3. Has any tested against Zope?
To which report do you refer? The only thing I mentioned is that there has not been any audit for Python 2.4 + Zope 2.7 as with Python 2.3 + Zope 2.6/2.7. -aj
On Sun, 5 Dec 2004 05:40:16 -0500, Raymond Hettinger <python@rcn.com> wrote:
* Deprecated modules just get moved to the lib-old directory. If someone has ancient code relying on the module, it is a somewhat trivial maintenance step to add lib-old to their PYTHONPATH. IOW, I fail to see the harm.
In principle, that's a good idea, but I don't know if it's really practical. I fear that the distribution would end up simply adding lib-old to the PYTHONPATH anyway :-) But some variations may be worth considering: 1) Deprecated modules would first generate a warning (as it is today). On future versions, instead of being removed, the level of the warning would be raised, causing a fatal exception (an ImportError?), unless explicitly configured otherwise (using a config file or some similar mechanism). I believe that the current warnings module already provides a good basis for this implementation. (IOW - the module would still be there, and could be activated, but it's "off" by default. Turning it on again has to be easy, though. And the message on "ImportError" have to meaningful for non-technical users, allowing for easier support in these situations) 2) Split the documentation: the "old-and-deprecated" modules would be listed separated from the active & recommended ones, as a different section, or even as a separate book. That would be a clear sign to new users to keep in mind while they read the documentation, perhaps more effective than writing the deprecation warning on the top of the page. My half-a-cent. -- Carlos Ribeiro Consultoria em Projetos blog: http://rascunhosrotos.blogspot.com blog: http://pythonnotes.blogspot.com mail: carribeiro@gmail.com mail: carribeiro@yahoo.com
* The average quality of the library improves as we take out junk (the tzparse module for example) and put in high quality modules like logging, csv, decimal, etc.
Yes and no. The added modules have to be relevant to what users want to do. While (relatively) minor stuff like csv and decimal are good ideas, of course, logging is kind of an "insider's" module. What many more users want, however, are things like an XML parser, or a CSS parser, or a usable HTTP server, or... The fact that XML 1.1 can't be parsed with already-written Python is a *big* strike against. So removing highly demanded functionality like XML parsing, and adding specialist modules such as csv, do not overall help what users see as the quality of the standard library. Bill
On Sun, 2004-12-05 at 03:36, "Martin v. Löwis" wrote:
I mostly agree with Fredrik. What good does removal of xmllib do? It's not that it is causing any maintenance burden, so we could just leave it in. Whether this means that we keep xmllib until P3k, I don't know.
As for PEP 4: I don't know whether it needs to be listed there. It appears that the PEP is largely unmaintained (I, personally, do not really maintain it). So one option would be to just stop using PEP 4 for recording deprecations, since we now have the warnings module. If we want to keep PEP 4, we need to follow the procedures it requires (or modify them if we don't like them).
I agree. We don't need to use PEP 4 for listing module deprecation schedules. It would be better if we included that information in the DeprecationWarning. Probably nobody reads PEP 4 when they get a DeprecationWarning, but everyone reads the message that's printed, so if it said something like "This module is deprecated and slated for removal in Python 2.6", I think we'd be providing better information to our users. -Barry
Martin v. Löwis wrote:
As for PEP 4: I don't know whether it needs to be listed there. It appears that the PEP is largely unmaintained (I, personally, do not really maintain it). So one option would be to just stop using PEP 4 for recording deprecations, since we now have the warnings module. If we want to keep PEP 4, we need to follow the procedures it requires (or modify them if we don't like them).
There is a need for a central place where deprecations are posted. You can't tell people to go hunt the standard lib for uses of the warning module in order for them to catch up with the current state of affairs. One thing that we shouldn't forget is that Python users do not necessarily upgrade to new Python releases every time there's a new release. Production users of Python will often skip a release or two depending on their needs, time frames and audit cycles. It is very important for them to know that module or other technology will be deprecated two releases down the road, so that they can accomodate for these changes today. -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Dec 13 2004)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
2004-12-06: Released eGenix mx Extensions for Python 2.4 ::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::
participants (17)
-
"Martin v. Löwis" -
Andreas Jung -
Anthony Baxter -
Barry Warsaw -
Bill Janssen -
Brett C. -
Carlos Ribeiro -
Dennis Allison -
Eirik Mikkelsen -
Fred L. Drake, Jr. -
Fredrik Lundh -
M.-A. Lemburg -
Michael Hudson -
Nick Coghlan -
Raymond Hettinger -
Raymond Hettinger -
Terry Reedy