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

[Ron Adam]

On 02/22/2011 07:27 PM, Terry Reedy wrote:
> On 2/21/2011 1:56 PM, Ron Adam wrote:
>
>> 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)
>
> As I said somewhere on the tracker, the only (intended) public apis of the
> pydoc module are the help function and the command-line interface. I
> consider the rest private and subject to change.

I agree, but I've gotten different opinions on that.  It certainly would 
make it easier to re-factor if we can get a consensus on just what the 
public API is.

What do you think about extending help() so it is the only pydoc API? In 
other words, everything is done through the help function either by 
directly calling help(something) or by passing args from the command line 
to help, ... help(args.)  This already works, but not for everything.

Cheers,
    Ron