pydoc and imported modules

[schpok]

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:ython
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

 

[Ron Adam]

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:ython
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

 

[Ron Adam]

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:ython
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

 

[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:ython (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:ython
implementations may not be exporting their interface.

Thanks for illuminating the problem,

Schpok