[Python-ideas] Depreciation / Replacements -was- Re: Cleaner separation of help() and interactive help.

[Ron Adam]

On 02/19/2011 06:35 PM, Nick Coghlan wrote:
> On Sun, Feb 20, 2011 at 2:36 AM, Ron Adam<rrr at ronadam.com>  wrote:
>> But I don't think we can do all of this at one time for backward
>> compatibility reasons.(?)  So currently I'm looking for guidance on what and
>> how I can best go ahead with some parts of this.
>
> I believe the approach we ended up using for the HTML parts in 3.2
> (i.e. leave the "old" way around, but deprecated, for anyone using the
> undocumented-but-public APIs, while adding new APIs for the new,
> better way) should work in this case as well. It does delay the
> removal of the old code until 3.4, but it's the most conservative way
> to give people a chance to fix anything that breaks (the downside of
> course being that anyone using the APIs has to do some version
> specific tap-dancing to select which API to use).

The server replacement wasn't too bad as the old server and tkinter gui 
panel were not written so they could be used independently of pydoc.  The 
new server and supporting code was either made private or put inside a 
function body so they could changed easily and/or be moved out of pydoc and 
be made available for other modules to be used.  So what we did made sense 
in the context of what was done.

As we go further with updating pydoc, it's going to have a fair amount of 
re-factoring.  If we follow the same pattern as the server upgrade, much of 
the existing pydoc API will be renamed and/or removed.  I'm not sure that 
makes as much sense.

At what point is it better to depreciate the whole module and create a new 
replacement module?

And conversely, are there limits on how much, and how fast, a module can be 
changed?


Pydoc fortunately is almost exclusively used "as is" rather than as an 
extension module.  So it is less likely that re-factoring it will break 
other peoples programs.  (possible though)

With other modules, we'd probably freeze the current module and create a 
new one with a different name, if it was going to require major 
re-factoring.  In those cases, how long do the old modules versions stick 
around?

Cheers,
   Ron