Robin Dunn wrote:
>> But I'm sure you don't want *all* imported objects to be listed as if
>> they're defined locally.
>
> Actually, in this case I do want all of them.
For this one module, maybe, but not in general, right? So maybe what
you want is a module-level way of saying "treat imported objects as
locally defined" instead of an object-level one?
> For the docs my preference would be that "core" and "wx.core" does not
> show up anywhere, and that everything that lives in wx.core would just
> be documented as "wx.Whatever".
If "core" isn't listed in wx.__all__, then it will be treated as
"private." Combined with treaing all names in __all__ as locally
defined, this might do what you want. Alternatively, you might consider
renaming wx.core to wx._core (which will make it very clear to your
users that it's an implementation module, and shouldnt be used directly).
>> So epydoc needs some information source to decide which imported
>> objects it should pretend are defined locally.
>>
>> One option is to use __all__. In particular, any imported objects
>> listed in __all__ will be treated as if they were defined locally.
>
> With hundreds of objects per module that gets to be a little difficult
> to maintain... I'll keep it in mind though.
There's no reason that __all__ has to be defined using a list literal.
In particular, you might consider doing something like this:
# Import all objects from wx.core (the implementation module)
from wx.core import *
# Declare that all of the objects imported from wx.core are public
import wx.core
__all__ += [name for name in dir(wx.core)
if not name.startswith('__') and name.endswith('__')]
del wx.core
>> Another option is to define a new field for the module docstring, that
>> declares that an object should be treated as if it was defined
>> locally. Something like "@local: Window", although I'm not crazy
>> about that name.
>
> This too.
@local would presumably support the "*" syntax that's supported by
@group, @sort, and @undefined. In particular, you could just do:
@local: *
I think I like the __all__ solution better, though.
-Edward
|