python packages versus pydoc -k

[Toshio Kuratomi]

On Wed, Mar 12, 2014 at 12:18:17PM -0700, Josh Stone wrote:
> 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.
> 
We don't currently have any official guidelines on this.

I know that pydoc can be broken.  Because of how it works I'm not certain
that we can fix it and keep it fixed.

> 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!)
> 
There's also packages that need a non-default version of a dependency in
order to work.  We've worked out ways to do this so that the module can be
imported when we use them in an application but it will probably break with
the way pydoc -k works.

setuptools entrypoints can break unrelated code.  It's probably another way
that pydoc -k could be broken.

[..]
> 
> Of course, these are just the first exceptions I hit.  Experience shows
> that fixing these will likely find more behind them.
>
Yeah, I think there's a never ending treadmill here.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.fedoraproject.org/pipermail/devel/attachments/20140312/d68dd7dd/attachment.sig>