classification
Title: Withdraw anti-recommendation of relative imports from documentation
Type: behavior Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: andymaier, docs@python, dsdale24, eric.araujo, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2010-10-05 20:18 by dsdale24, last changed 2014-10-06 14:21 by python-dev. This issue is now closed.

Messages (6)
msg118031 - (view) Author: Darren Dale (dsdale24) Date: 2010-10-05 20:18
Old-style relative imports have been strongly discouraged in some sections of the python documentation. This was discussed on the python-dev mailing list. Executive summary: "The issue is implementing a PEP with nice support for relative imports, and then documenting that it should never be used." To which Guido responded:

---
"Isn't this mostly historical? Until the new relative-import syntax was
implemented there were various problems with relative imports. The
short-term solution was to recommend not using them. The long-term
solution was to implement an unambiguous syntax. Now it is time to
withdraw the anti-recommendation. Of course, without going overboard
-- I still find them an acquired taste; but they have their place."
---

It was suggested I open a ticket and suggest specific changes. They are listed below:

The faq at
http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practices-for-using-import-in-a-module
could go from:

"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."

to:

"Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. See PEP 328 for details."



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
could go from:

"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."

to:

"Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Support for relative imports has recently been improved, and the use of the old-style relative imports is strongly discouraged. See PEP 328 for details."

There is also this warning against relative imports in PEP 8, that could go from:

   - 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.

to:

   - While the python community generally prefers absolute imports,
     relative imports may be useful in certain circumstances. Now that
     PEP 328 [7] is fully implemented in Python 2.5 and later, the
     older style of implicit relative imports is strongly discouraged.
msg118038 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-10-05 22:30
Note that of the versions still getting doc updates, only 2.7 still supports the old style relative imports.
msg119059 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-10-18 18:24
Thanks for the report and suggestions.  I agree to the gist of your changes, but I wouldn’t remove the explanation of implicit relative imports (the part starting with “If you’re writing code”).
msg222162 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-03 08:43
Hi, I would like to revive this issue, and have a few comments:

1. In Darren's original proposal, I suggest to say "implicit (old-style) relative imports" instead of "old-style relative imports", because that is the term used in the Python Tutorial (the description of the ´import´ statement in 2.7 does not mention implicit relative imports at all).

2. It seems to me that David's suggestion is already reflected in the original proposal. Or maybe I don't understand it right...

3. I agree with Éric's comment that implicit relative imports should still be explained. However, I'm not sure that needs to be done in the FAQ. After all, the FAQ does not explain absolute or explicit relative imports either, and spending more words on the discouraged approach than on the recommended approaches does not seem appropriate to me.

4. I have to say that I'm generally unhappy if I see PEPs mentioned as a specification ("See PEP 328 for details"). I have sympathy for referencing PEPs as background information and for the rationales they usually contain. Could we reference the description of the ´import´ statement for details, instead of referencing the PEP (in both FAQs)?

Andy
msg228691 - (view) Author: Roundup Robot (python-dev) Date: 2014-10-06 14:20
New changeset 8c33440d1f64 by Georg Brandl in branch '3.4':
Closes #10031: overhaul the "imports" section of the programming FAQ.
https://hg.python.org/cpython/rev/8c33440d1f64
msg228692 - (view) Author: Roundup Robot (python-dev) Date: 2014-10-06 14:21
New changeset 9d321235f1f9 by Georg Brandl in branch '2.7':
Closes #10031: overhaul the "imports" section of the programming FAQ.
https://hg.python.org/cpython/rev/9d321235f1f9
History
Date User Action Args
2014-10-06 14:21:56python-devsetmessages: + msg228692
2014-10-06 14:20:05python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg228691

resolution: fixed
stage: patch review -> resolved
2014-07-03 08:43:06andymaiersetnosy: + andymaier
messages: + msg222162
2010-10-18 18:24:54eric.araujosetversions: - Python 3.1, Python 3.2
nosy: + eric.araujo

messages: + msg119059

keywords: + patch
stage: patch review
2010-10-05 22:30:18r.david.murraysetversions: - Python 2.6, Python 3.3
nosy: + r.david.murray

messages: + msg118038

type: behavior
2010-10-05 20:18:09dsdale24create