pydoc and imported modules

Discussion in 'Python' started by schpok, Apr 20, 2007.

  1. schpok

    schpok Guest

    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
     
    schpok, Apr 20, 2007
    #1
    1. Advertisements

  2. schpok

    Ron Adam Guest

    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, Apr 25, 2007
    #2
    1. Advertisements

  3. schpok

    Ron Adam Guest

    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, Apr 25, 2007
    #3
  4. 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
     
    Joshua Schpok, Apr 25, 2007
    #4
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.