Nick Coghlan <ncogh...@gmail.com> added the comment:

Regarding question 1 (_start_server docstring):

I have no problem with docstrings on private functions in general. It just 
means they're for the benefit of developers of the module itself rather than 
users of the module. However, in this case, I would move the "example use" out 
of the docstring and into a comment following the docstring.

Regarding questions 2 & 5 (code structure and deprecations):

This whole patch would have been a *lot* easier if the server and GUI 
implementations in pydoc had been properly private from the start. A look at 
the docs makes it fairly obvious that these are meant to be implementation 
details of the command line invocation, but the way they were written meant 
they were exposed as a public standard library API. As a result, we have to 
jump through a lot of hoops to replace them with the new back end.

Since we don't want to maintain the old GUI client or the associated web server 
backend, the deprecations are needed so we can delete them entirely in 3.3. The 
situations Raymond is talking about are cases where we come up with a "better" 
API, but an old API is popular and not really all that flawed within its 
original scope (e.g. getopt vs optparse vs argparse). In such cases, 
deprecation gains us little and causes a lot of hassle. However, in a case like 
this, where people shouldn't have been using the old API anyway and there's a 
mountain of code we want to get rid of, deprecating the associated API is the 
right thing to do.

The nested code structure is a reaction to the concern that caused all the 
additional difficulty - by squirreling all the implementation details away 
inside a small number of functions that are named with leading underscores, we 
eliminate the temptation to rely on the current location of these classes. For 
3.3, I'd like to pursue Ron's idea of pulling the text server out and placing 
it in http.server for general use, with pydoc then retrieving it from there.

Regarding questions 3 & 4 (repetition of bltinlink and HTML dodginess):

Those two sound like issues that should be fixed.

----------

_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue2001>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to