[Biopython-dev] Warnings from epydoc

[Peter]

Hi all,

Something that I could have mentioned when I built the beta is there
are a lot of warnings from epydoc.  Ignoring a few from deprecated
modules etc, there is a whole class as follows:

Warning: Module Bio.KDTree.KDTree is shadowed by a variable with the same name.
Warning: Module Bio.PDB.DSSP is shadowed by a variable with the same name.
Warning: Module Bio.PDB.FragmentMapper is shadowed by a variable with
the same name.
Warning: Module Bio.PDB.NeighborSearch is shadowed by a variable with
the same name.
Warning: Module Bio.PDB.PDBIO is shadowed by a variable with the same name.
Warning: Module Bio.PDB.PDBList is shadowed by a variable with the same name.
Warning: Module Bio.PDB.PDBParser is shadowed by a variable with the same name.
Warning: Module Bio.PDB.ResidueDepth is shadowed by a variable with
the same name.
Warning: Module Bio.PDB.StructureAlignment is shadowed by a variable
with the same name.
Warning: Module Bio.PDB.Superimposer is shadowed by a variable with
the same name.
Warning: Module Bio.PDB.Vector is shadowed by a variable with the same name.
Warning: Module Bio.PDB.parse_pdb_header is shadowed by a variable
with the same name.
Warning: Module Bio.SVDSuperimposer.SVDSuperimposer is shadowed by a
variable with the same name.
Warning: Module Bio.SCOP.Residues is shadowed by a variable with the same name.

One visible side effect of this in the epydoc output is these modules
get shown with an apostrophe suffix for disambiguation.

On another point, I think some of the imports used in Bio.PopGen are
making epydoc unhappy:

+-------------------------------------------------------------------------------------------------
| In /usr/local/lib/python2.5/site-packages/Bio/PopGen/SimCoal/Cache.py:
| Import failed (but source code parsing was successful).
|     Error: ImportError: No module named PopGen.SimCoal.Controller (line 14)
|
+-------------------------------------------------------------------------------------------------
| In /usr/local/lib/python2.5/site-packages/Bio/PopGen/SimCoal/Async.py:
| Import failed (but source code parsing was successful).
|     Error: ImportError: No module named PopGen.SimCoal.Controller (line 16)
|

Taking Bio/PopGen/SimCoal/Cache.py as an example, currently this has:

from PopGen.SimCoal.Controller import SimCoalController
from PopGen import Config

Perhaps this should be changed to either local imports:

from Controller import SimCoalController
import Config

or full imports:

from Bio.PopGen.SimCoal.Controller import SimCoalController
from Bio.PopGen import Config

(Neither tested yet).

I don't know if the current imports have any downsides (apart from
upsetting epydoc), as the current code works and the unit tests pass.

Peter