Re: [Epydoc-devel] how to document methods imported from other modules?

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

On Jun 24, 2007, at 2:43 PM, Paul Pogonyshev wrote:
> Hi,
>
> My package supports Python 2.3 onwards.  However, I do provide some
> methods that are only available on 2.5.  [...]
> Question is: can I somehow pretend that my_cool_context_manager() is
> defined with Main class, so it is documented in that class?

The problem here is that epydoc's source code parser sees the import  
statement for my_cool_context_manager, so naturally it assumes that's  
an imported object that should be documented elsewhere.  There are a  
few possible work-arounds, none of which I'm entirely happy with.   
One is to use --introspect-only to disable source code parsing.   
Without the source code parsing, epydoc has no way to know that you  
imported the function (since you're explicitly modifying the  
function's __module__), so it will document it as part of your Main  
class.  The remaining work-arounds involve "hiding" the import from  
epydoc's source code parser.  For example, you could use the  
__import__ function instead of an import statement:

     my_cool_context_manager = \
         __import__('_helper_2_5').my_cool_context_manager

If it were a module-level function, rather than a class function,  
then you could get the desired behavior by explicitly defining  
__all__ and listing the imported object there -- epydoc treats an  
object as 'locally defined' (not imported) if it's listed explicitly  
in __all__, even if epydoc can tell that it's really imported.  This  
is useful for modules whose sole purpose is to collect together  
objects that are actually defined in other 'private' modules.   
Perhaps something could be done similar here -- epydoc could look for  
a class variable __all__, and treat anything listed there as if it  
weren't imported.  For consistency, epydoc would also treat member  
variables as private iff they are not listed in the class __all__  
variable.

Would that solution work for you?  If so, I'll add a feature request  
for this on the epydoc sourceforge page.  Unfortunately, I probably  
won't have time to implement it myself in the near future.  But of  
course, patches are always welcome!

-Edward