[Python-Dev] patching pydoc?

[Terry Reedy]

"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

> this is the code of pydoc, starting at line 1457
>
> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
> def doc(thing, title='Python Library Documentation: %s', forceload=0):
>    """Display text documentation, given an object or a path to an 
> object."""
>    try:
>        object, name = resolve(thing, forceload)
>        desc = describe(object)
>        module = inspect.getmodule(object)
>        if name and '.' in name:
>            desc += ' in ' + name[:name.rfind('.')]
>        elif module and module is not object:
>            desc += ' in module ' + module.__name__
>        if not (inspect.ismodule(object) or
>                inspect.isclass(object) or
>                inspect.isroutine(object) or
>                isinstance(object, property)):
>            # If the passed object is a piece of data or an instance,
>            # document its available methods instead of its value.
>            object = type(object)
>            desc += ' object'
>        pager(title % desc + '\n\n' + text.document(object, name))
>    except (ImportError, ErrorDuringImport), value:
>        print value
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
>
> this is the suggested code
>
> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
> def render_doc(thing, title='Python Library Documentation: %s', 
> forceload=0):
>    """generate the text"""
>    object, name = resolve(thing, forceload)
>    desc = describe(object)
>    module = inspect.getmodule(object)
>    if name and '.' in name:
>        desc += ' in ' + name[:name.rfind('.')]
>    elif module and module is not object:
>        desc += ' in module ' + module.__name__
>    if not (inspect.ismodule(object) or
>            inspect.isclass(object) or
>            inspect.isroutine(object) or
>            isinstance(object, property)):
>        # If the passed object is a piece of data or an instance,
>        # document its available methods instead of its value.
>        object = type(object)
>        desc += ' object'
>    return title % desc + '\n\n' + text.document(object, name)
>
> def doc(*args, **kwargs):
>    """Display text documentation, given an object or a path to an 
> object."""
>    try:
>        text = render_doc(*args, **kwargs)
>        pager(text)
>    except (ImportError, ErrorDuringImport), value:
>        print value
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: 
> http://mail.python.org/mailman/options/python-dev/python-python-dev%40m.gmane.org
>