python packages versus pydoc -k

[Josh Stone]

Do we have any packaging requirements or guidelines for python modules
to behave nicely with pydoc?  I've seen this break a number of times,
and sometimes the bugs I've filed have been fixed, sometimes ignored.
Before I go through another round, I'd like to know if we have (or
should have) some official policy on this.

AIUI, pydoc works by importing the named module, then displaying its
docstrings.  Then "pydoc -k" does this for all modules in sys.path,
looking for the specified keyword.  A problem then arises if something
in the path does protect itself with 'if __name__ == "__main__":' to
know when it's acting as a module or a script.  (And if some module
really doesn't want to support normal importing, it should not be
installed in the path!)

For instance, right now I get:

> $ pydoc -k xyzzy
> lib2to3.fixes.fix_repr - Fixer that transforms `xyzzy` into repr(xyzzy).
> Traceback (most recent call last):
>   File "/usr/bin/pydoc", line 5, in <module>
>     pydoc.cli()
>   File "/usr/lib64/python2.7/pydoc.py", line 2292, in cli
>     apropos(val)
>   File "/usr/lib64/python2.7/pydoc.py", line 1992, in apropos
>     ModuleScanner().run(callback, key, onerror=onerror)
>   File "/usr/lib64/python2.7/pydoc.py", line 1973, in run
>     module = loader.load_module(modname)
> AttributeError: 'NoneType' object has no attribute 'load_module'

It's hard to track that down, but with "strace -e open" it looks like
somewhere in site-packages/rpm/.  I couldn't figure out exactly which
subpackage is triggering this.

> $ pydoc3 -k xyzzy
> lib2to3.fixes.fix_repr - Fixer that transforms `xyzzy` into repr(xyzzy).
> Usage: pydoc3 [options]
> A simple dialog based tool for basic configuration of Speech Dispatcher
> and problem diagnostics.
> 
> pydoc3: error: no such option: -k

This one is somewhere in site-packages/speechd, but again I'm not sure
which subpackage.

Of course, these are just the first exceptions I hit.  Experience shows
that fixing these will likely find more behind them.