Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo


#225 Class Factories and Sub-Modules

Edward Loper
inspection (59)
Chad Dombrova

with epydoc 3.0 beta1 when constructing new classes with the type command, the classes are not recognized by epydoc if the those new classes are added in a sub-module. the code examples will explain the problem better than i can.

there are two test setups:

this example was provided to show a setup that works correctly. if you run `epydoc --config epytest2.cfg` on this module, the resulting docs include the 3 new classes MyStr, MyList, and MyDict.


this example does not work properly. __init__.py imports the test sub-module which sets up the 3 new classes. if you open a python interpreter and type `import epytest`, the printouts show that the classes exist and are available to the epytest module. however, if you run `epydoc --config epytest.cfg` on this module, the resulting docs do not include the 3 new classes MyStr, MyList, and MyDict.

perhaps there is a better way to do what i want in my code that will avoid this problem, but the code does what i need it to do, but the documentation is not being generated properly.


  • Chad Dombrova
    Chad Dombrova

    test files

  • Edward Loper
    Edward Loper

    • status: open --> closed-works-for-me
  • Edward Loper
    Edward Loper

    Logged In: YES
    Originator: NO

    The problem here is that the class reports that it is defined in the module 'epytest.test'; so when epydoc sees it in epytest, it doesn't explicitly list it, because it thinks it's just an import. This usually makes sense -- just because you import a bunch of functions from another module (think "from os import *") doesn't mean you want them documented as part of your module.

    And the classes don't get documented where they "belong" (in epytest.test) because they're not bound to any variables there -- you injected them directly into epytest.

    Since you're programmatically generating the classes anyway, one solution is to manually set their __module__ to the module where you intend for them to live. In your case, that means adding the following line to your for loop:

    cls.__module__ = 'epytest'

    It's also worth noting that, unless you set __module__ like this (or adopt a different method for building these classes), modules like 'pickle' will probably have trouble with your classes too.

    Another solution (which wouldn't help pickle, but would allow epydoc to generate what you want) would be to define __all__ in epytest/__init__.py to be ['MyStr', 'MyList', 'MyDict']. If epydoc sees an object in __all__, it will include it in the docs for that module, even if it knows that it's really imported from somewhere else.

    I'm assuming that your example is a significant simplification of what you're actually trying to accomplish; in particular, that you have some good reason for wanting to generate the classes programatically rather than just using:

    class MyStr(str): 'this is a custom str'


    I'm closing this bug report, with the recommendation that you explicitly set __module__, or figure out another way to do what you're trying to do. Epydoc's behavior in this case seems pretty reasonable to me. If that doesn't work for you for some reason, feel free to re-open the bug.