[Python-Dev] question/comment about documentation of relative imports

[Darren Dale]

I have a couple questions/comments about the use of PEP 328-style
relative imports. For example, the faq at
http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practices-for-using-import-in-a-module
reads:

"Never use relative package imports. If you’re writing code that’s in
the package.sub.m1 module and want to import package.sub.m2, do not
just write from . import m2, even though it’s legal. Write from
package.sub import m2 instead. See PEP 328 for details."

There is no explanation to support the claim that relative imports
should "never" be used. It seems to me that someone read the following
in PEP 328::

   from .moduleY import spam
   from .moduleY import spam as ham
   from . import moduleY
   from ..subpackage1 import moduleY
   from ..subpackage2.moduleZ import eggs
   from ..moduleA import foo
   from ...package import bar
   from ...sys import path

   Note that while that last case is legal, it is certainly
discouraged ("insane" was the word Guido used).

... and interpreted it to mean that relative imports are in general
discouraged. I interpreted it to mean that relative imports should not
be used to import from python's standard library.

There are cases where it is necessary to use relative imports, like a
package that is included as a subpackage of more than one other
project (when it is not acceptable to add an external dependency, for
example due to version/compatibility issues). There is some additional
context on relative imports in the programming faq for python-2.7 at
http://docs.python.org/faq/programming.html#what-are-the-best-practices-for-using-import-in-a-module
:

"Never use relative package imports. If you’re writing code that’s in
the package.sub.m1 module and want to import package.sub.m2, do not
just write import m2, even though it’s legal. Write from package.sub
import m2 instead. Relative imports can lead to a module being
initialized twice, leading to confusing bugs. See PEP 328 for
details."

Is there some documentation explaining why the module may be
initialized twice? I don't see it in PEP 328. Is this also the case
for python-3, or does it only apply to the old-style (pre-PEP 328)
relative imports in python-2? If relative imports are truly so
strongly discouraged, then perhaps warnings should also be included in
places like http://docs.python.org/library/functions.html#__import__ ,
and especially http://docs.python.org/tutorial/modules.html#intra-package-references
and http://www.python.org/dev/peps/pep-0328/ (which, if I have
misinterpreted, is ambiguously written. Though I doubt this is the
case).

There is also this warning against relative imports in PEP 8:

    - Relative imports for intra-package imports are highly discouraged.
      Always use the absolute package path for all imports.
      Even now that PEP 328 [7] is fully implemented in Python 2.5,
      its style of explicit relative imports is actively discouraged;
      absolute imports are more portable and usually more readable.

... but one could argue, as I just have, that relative imports are
more portable, not less. In a sense, the statement "explicit relative
imports is actively discouraged" is objectively false. They are
passively discouraged. If they were actively discouraged, perhaps
performing a relative import would raise a warning, or maybe distutils
would raise a warning at install time, or maybe an additional import
would be required to enable them. Up until now, I was not aware that
use of PEP 328 relative imports might be discouraged. I'm still
unclear as to why they might be discouraged. I recently helped convert
a popular package to use PEP 328 relative imports. Would the python
devs consider this a mistake?


Thanks,
Darren