[Python-Dev] pydoc - put it in the core

[Ka-Ping Yee]

Guido van Rossum wrote:
> Yes, wow!

Paul Prescod wrote:
> I apologize but I'm not clear on my responsibilities here, if any. I
> wrote a PEP for online help. I submitted a partial implementation.

Hi, guys.  Sorry i haven't been sending updates on what i'm doing.
Here's the current picture as i see it.

> Ping wrote a full implementation that basically supercedes mine.

My implementation is "full" in that it deploys and seems to work on
arbitrary modules as it stands, but it doesn't really supercede Paul's
because it leaves out the big piece of Paul's work that did conversion
from packaged HTML docs to plain text.

It also has the deficiency that it imports modules live; for untrusted
modules, this is a security risk.  I know Paul has been working on
stuff to compile a module into a kind of skeleton object that has all
the same name bindings but no live contents, and if that works reliably,
we should definitely try plugging that in.

> There are various ideas for improving it, but I think that we agree
> that the core is solid.

Yes.  I believe that as it stands, pydoc is useful enough to be a net
positive addition to the core.  inspect.py alone has been stable and
alpha-ready for some time, i believe.

Here is a summary of its status and work that remains.  pydoc has:

    inspecting live objects
    generating text docs from live objects
    generating HTML docs from live objects
    serving HTML docs from a little web server
    showing docs from the command line
    showing docs from within the interactive interpreter
    apropos-style module listing

It's missing the following, and Paul had stuff for this:

    inspecting unsafe modules
    generating text docs from packaged HTML (e.g. language reference)

It also needs these:

    generating docs from a file given on the command line (easy)
    more Windows and Mac testing and decisions
    various small bugfixes

This past week i've been messing around with Windows and Mac stuff,
trying to see whether it's possible to reliably spawn a webserver
and launch a web browser at the same time (this would seem to be a
good default action to do on GUI platforms).

In trying to do the latter i've found the webbrowser module pretty
unreliable, by the way.  For example, it relies on a constant delay
of 4 seconds to launch a new browser that can't be expected on all
platforms, and fails to launch Netscape 3 because it supplies an
illegal command-line option.  When i've found good cross-platform
ways to make this work i'll suggest some patches.

I've so far considered this project blocked only on cross-platform
testing -- do you agree?  While i know that inspecting unsafe modules
and processing packaged HTML are important features, i don't consider
them essential.


-- ?!ng