[Python-Dev] patching pydoc?

[tomer filiba]

> Giving the amount of hair-tearing over uuid and __index__, this seems like
> an especially bad day to ask for a new-feature variance in a time of
> feature freeze ;-).

yeah, i guess so.

> * Would making pager() a parameter of doc() make sense?

not at all.

> * I presume you gain the new functionality by directly calling the
> factored-out render_doc and printing thru your own pager.  Does everyone?

i don't quite get the question, but yes, i plan to call render_doc
instead of doc, getting the doc text, and printing it on my own console
using a pager/whatever.

about the signature, okay, it can easily be fixed. i didn't think about that
too much. about the other point -- ImportError etc -- i tried to go "dumb"
as much as possible and not make any change that would break
something. pydoc is poorly written anyway, and as ron adam noted,
there is a need for at least a cleaned-up version of pydoc, or even a
redesigned package. and it ought to be a package. it's a module of
~2000 lines. that's way too much for a module.

i made the minimal changes needed to separate the "generate text" part
from the "generate and display" part. and i kept all the semantics in tact
(including who handles the errors)

and therefore, i don't expect it to break any tests (after restoring the
original doc signature, that is). i'd hate to wait for 2.6 for such a small
change.

today my solution is to replace pydoc.pager by a fake pager that hands
over the result. this is of course not thread safe, as multiple threads
calling help() would mix their outputs. not very likely, but i'd love to
see this code go away asap.


thanks for the comments,
-tomer

> From: Terry Reedy <tjreedy <at> udel.edu>
> Subject: Re: patching pydoc?
> Newsgroups: gmane.comp.python.devel
> Date: 2006-07-28 18:29:50 GMT (5 hours and 27 minutes ago)
>
> "tomer filiba" <tomerfiliba <at> gmail.com> wrote in message
> news:1d85506f0607280635q3a693682l230c7821dc6f408f <at> mail.gmail.com...
> ...
> > therefore, i would like to split this behavior into two parts:
> > * render_doc - a function that returns the document text
> > * doc - a function that calls render_doc and sends it to the pager
> >
> > this way no existing code breaks (no existing function signatures
> > are changed) and i gain help on remote objects.
> > i hope people would be in favor, as it's not such a big change anyway.
> > is it possible to add to 2.5?
>
> Giving the amount of hair-tearing over uuid and __index__, this seems like
> an especially bad day to ask for a new-feature variance in a time of
> feature freeze ;-).
>
> Some quick questions:
> * I presume you gain the new functionality by directly calling the
> factored-out render_doc and printing thru your own pager.  Does everyone?
> * Would making pager() a parameter of doc() make sense?
> * Is pager() the only part of the original doc() that can generate
> ImportError, ErrorDuringImport?  If not, the try/except should be in
> render_doc also or instead.
> * Why generalize the doc() signature?  Bad calls will be traced as caught
> in render_doc instead of doc.  Couldn't that potentially break a bad_call
> test?
>
> Terry Jan Reedy