[Python-Dev] Backward incompatible API changes in the pydoc module

[Ron Adam]

On 11/08/2010 09:12 AM, exarkun at twistedmatrix.com wrote:
> On 11:44 am, ncoghlan at gmail.com wrote:
>> All,
>>
>> I was about to commit the patch for issue 2001 (the improvements to
>> the pydoc web server and the removal of the Tk GUI) when I realised
>> that pydoc.serve() and pydoc.gui() are technically public standard
>> library APIs (albeit undocumented ones).
>>
>> Currently the patch switches serve() to start the new server
>> implementation and gui() to start the server and open a browser window
>> for it.
>>
>> It occurred to me that, despite the "it's an application" feel to the
>> pydoc web server APIs, it may be a better idea to leave the two
>> existing functions alone (aside from adding DeprecationWarning), and
>> using new private function names to start the new server and the web
>> browser.
>>
>> Is following the standard deprecation procedure the better course
>> here, or am I being overly paranoid?
>
> Following the deprecation procedure here sounds awesome to me. Thanks
> for considering it, I hope you'll choose to go that way.

I want to be clear on what isn't changing.

All of the help() function features that python depends on and any of the 
code that is required for that is staying the same.

All of the static html document generating features and code that depend on 
that, is staying the same.  These static pages do not depend on any parts 
of pydoc after they are generated.

Those are the parts that are most likely to be used in other applications 
as well.


The new changes only effect the interactive browsing mode. The tk search 
box was removed.  By doing that, it enabled the browser interface, to be 
used on systems that don't have tk installed.

The html web server was rewritten and a search feature was added so that 
you can do the same searches in the web browser that you did in the tk 
search box.

Do you (or anyone) know of any programs that access pydocs tk search 
window, or it's server parts directly?  The server was so specific and 
included very specific pydoc html code, so it would have been very 
difficult for it to be used for anything else.  Any thoughts?

I think the main issues Nick is concerned with is the functions and options 
used to start pydoc in the interactive mode.

Cheers,
    Ron