epydoc-devel

[Epydoc-devel] introspection misconception

[<oti...@ya...>]

Dear epydoc devels, thank you for maintaining epydoc, which is a software
I depend on daily basis :-)))
I'm running into a problem using epydoc with introspection, but I am not
sure if this is a bug, a feature or a misconception on my part. If I have a
python module organized as follows:

foo/
foo/__init__.py
foo/bar.py

where __init__.py consists of the following two lines:
from bar import FooBar
del bar

and bar.py of the following two lines:
class FooBar(object):
    """Nice Class"""
    pass

importing the above module in python shows:
>>> import foo
>>> dir(foo)
['FooBar', '__builtins__', '__doc__', '__file__', '__name__', '__path__']

which, as expected, shows the class 'FooBar' as the only non-private 
member of module 'foo' . If I now generate the API docs with epydoc using 
'parse-only' I get documentation for:
 foo, foo.bar, foo.bar.FooBar
whereas, using 'introspection-only' I was under the impression that I would
get docs for
 foo, foo.FooBar.
What happens instead is that for 'introspection-only', docs are generated 
for
 foo, foo.bar', foo.bar'.FooBar
with a warning that a variable shadows the module 'bar'. 

What am I missing here? I thought introspection meant that epydoc is
importing my module and introspecting it to find out all its members. But
with introspection only, one would never get to "foo.bar", which is not
available in the namespace of "foo". 
I am sorry if the question sounds odd, but  that's probably because I did
not understand how epydoc assigns names to objects. 
I'm attaching for convenience a tarball with the python modules and
the docs generated by epydoc with parsing and introspection.

thank you!

tiziano






      ____________________________________________________________________________________
Looking for last minute shopping deals?  
Find them fast with Yahoo! Search.  http://tools.search.yahoo.com/newsearch/category.php?category=shopping

Re: [Epydoc-devel] introspection misconception

[Edward L. <ed...@se...>]

>  I'm running into a problem using epydoc with introspection,
>  [...]
>  whereas, using 'introspection-only' I was under the impression that I would
>  get docs for
>   foo, foo.FooBar.
>  [...]
>  What am I missing here? [...]

A couple things: first, if you tell epydoc to document a package
directory, it will automatically document every module in that
package, regardless of whether it gets imported by the main module's
__init__.py file.  If you want to tell epydoc to document *just* the
package itself, and not any of the modules inside the package, you
should run epydoc on the __init__.py file, not on the package
directory.  I.e.:

    % epydoc --introspect-only foo/__init__.py

The second thing is that epydoc is generally careful about figuring
out where something is *actually* defined, and documenting it there;
99% of the time, when an object is imported, it's so that it can be
used, not to move it to a different namespace.  So in this case,
epydoc assumes that FooBar is getting imported into the foo module
just to be used, not to modify the API.  To tell epydoc that you want
FooBar to be listed in the foo module explicitly, you'll need to
define the __all__ variable in the foo module.  In your example case,
you would use:

    __all__ = ['FooBar']

If you make those two changes (defining __all__ in foo/__init__.py,
and running epydoc on foo/__init__.py), then you should get the
results you expect.

One final note, though...  Your package as defined has the following
potentially confusing behavior:

>>> import foo.bar
>>> print foo.bar
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'module' object has no attribute 'bar'

Of course, a persistent user can still access the module:

>>> import sys
>>> sys.modules['foo.bar']
<module 'foo.bar' from 'foo/bar.pyc'>

So I'm not sure I see the benefit of deleting 'bar' from the 'foo' namespace.

-Edward