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

[Ron Adam]

On 11/08/2010 05:44 AM, Nick Coghlan 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?

What do you think about adding a new _pydoc3.py module along with a 
pydoc3.py loader module with a basic user api.  The number 3, so that it 
match's python3.x.

We can then keep the old pydoc.py unchanged and be free to make a lot more 
changes to the _pydoc3.py file without having to be even a little paranoid.

Cheers,
    Ron