pydoc and imported modules

[Joshua Schpok]

I see. To make sure all my modules imported * are included in the
pydocs, I'll add:
__all__ = dir()
to the end of my __init__.py file.

Sometimes I implement a module with submodules, and flatten them out
in __init__.py so the user sees it all as one single module. For
example, module 'foobar' may be implemented in _foo and _bar, though I
want their contents exposed in the single module 'foobar'. So my
__init__.py would look like:

from _foo import *
from _bar import *

I noticed their pydocs weren't getting expanded if they were a)
implemented in python, or b) bound using boost::python (regular c
bindings and pyrex work). Apparently these approaches don't add their
members to __all__. It's odd to me that you can still call _foo's
member 'baz' through the foobar namespace, as though it is a member of
foobar.

I'm not sure if this is something that needs to be changed in pydoc.
If __all__ represents the public interface of a module, that should be
the thing we document. I was confused that __all__ behavior varied
with implementation, and understand that my python and boost::python
implementations may not be exporting their interface.

Thanks for illuminating the problem,

Schpok

On 4/25/07, Ron Adam <rrr at ronadam.com> wrote:
> schpok at gmail.com wrote:
> > When I "from foo import *" in my __init__.py, sometimes module foo's
> > docs will be expanded in the pydocs. It seems to depend in what
> > language foo was implemented.
> >
> > For example, if you "from math import *" in your __init__.py, you will
> > see math's members will appear in the resulting pydocs, as though it's
> > part of your module. The behavior is consistent across the C modules I
> > am writing.
> >
> > However, if you "from foo import *" in your __init__.py, and foo is a
> > python file (not a module written in C), foo's members don't appear in
> > the resulting pydocs. This also seems to occur in some boost::python
> > bindings.
> >
> > What is expected behavior? How do ensure foo's docs do or don't appear
> > in help, regardless of their implementation language?
> >
> > Thanks,
> > Schpok
>
> Pydoc doesn't check the __module__ attribute of the items imported, it just
> displays what is in the modules name space as if it was defined in that module.
>
> In __init__.py files where an __all__ variable is defined, it won't show
> items that aren't in __all__.  This is probably what you are seeing.
>
> I'm currently rewriting pydoc, so what behavior would you like to see?
>
> Cheers,
>     Ron
>
>