Discussion: How should we import our utilities module?

[Damien Irving]

In the packaging chapter we currently say/do the following:

"For our scripts to work as a Python package, we only need to make one important change to the code itself: changing the syntax for how we import utilities. Currently, both collate.py and countwords.py contains this line:

import utilities

This is called an implicit relative import, because it is not clear whether there exists a Python package called utilities or there is a file in our local directory named utilities.py (as in our case). This ambiguity is not ideal and when making a package we need to be more explicit and write:

from zipf import utilities

"
...

The problem is that Read the Docs hates this and thus won't display collate and countwords in the module index:

WARNING: autodoc: failed to import module 'collate'; the following exception was raised: No module named 'zipf'
WARNING: autodoc: failed to import module 'countwords'; the following exception was raised: No module named 'zipf'

What should we do about this?

[Damien Irving]

This one needs to remain open - it wasn't resolved in #411.

[Damien Irving]

In the meeting on 13 August @gvwilson said he'd find a Python guru who might know the solution to this.

[Damien Irving]

Maybe if we added zipf to requirements.txt this issue would go away? The only way to test this (which I haven't done) would be to actually publish the zipf package to PyPI.

[Damien Irving]

Turns out the problem was that we removed our implicit relative imports, e.g.

import countwords

and replaced them with absolute imports, e.g.

from zipf import plotcounts

(Explicit relative imports like from . import plotcounts also break Sphinx and Read The Docs.)

If we stick with our original implicit relative imports everything is fine.