On Jun 24, 2007, at 2:43 PM, Paul Pogonyshev wrote:
> 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 = \
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__
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!