Thread: [Epydoc-devel] Easier class names lookup
Brought to you by:
edloper
From: Daniele V. <pi...@de...> - 2007-02-11 00:34:46
|
Hello, in r1448 i added a fallback rule for the DocIndex.find() method: if a class name is looked for, and such class has not been imported into the namespace it is referred from, then look for it into the documented modules. The class is returned only if its name is not ambiguous: if there exist more classes with the same name, a warning is emitted. The implemented check is efficient: about a single non recursive scan of all the documented modules to create a map from names to classes, and a dict lookup for each name that would have failed with the previous find() implementation. The rationale behind this rule is that in Python you don't have to know an object class in order to use it, as long as you receive an instance and you trust the caller he sent you a duck with the right number of legs. So people ends up writing: class Bar: def shootProtons(self, foo): """Frobnicate the world :Parameters: `foo` : `Foo` the required frobnicator """ foo.shoot() It often happens that Foo is defined in another module. If Foo were not imported in the module defining Bar, Epydoc would have failed linking `Foo` to the Foo class documentation. To overcome this it is possible to import the object in the namespace: from foomodule import Foo but if foomodule happens to use objects defined in the barmodule, there would be a cross modules import doomed to fail. Another alternative is to import the containing module: import foomodule but then the class should be referred as `foomodule.Foo` and, in case of refactoring all the references were to be updated; Furthermore the modules would be paired even if the code wouldn't require it. Yet another alternative would be to import all the classes in the __init__.py of the main package, but often you don't *need* them there, and this would block lazy imports. In a more generic sense, Epydoc should not ask the source to be adapted to be handled: it's fine to adapt docstrings, but code shouldn't be affected. -- Daniele Varrazzo - Develer S.r.l. http://www.develer.com |