classification
Title: Contrary to documentation, relative imports cannot pass through the top level
Type: enhancement Stage: resolved
Components: Documentation, Interpreter Core Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Malcolm Smith, brett.cannon, docs@python, eric.snow, nanjekyejoannah, ncoghlan
Priority: normal Keywords: patch

Created on 2017-07-03 19:14 by Malcolm Smith, last changed 2019-04-24 15:45 by ncoghlan. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 12831 merged nanjekyejoannah, 2019-04-14 19:44
PR 12938 merged miss-islington, 2019-04-24 15:14
Messages (7)
msg297608 - (view) Author: Malcolm Smith (Malcolm Smith) Date: 2017-07-03 19:14
https://docs.python.org/3/reference/simple_stmts.html#the-import-statement defers the full specification of relative imports to PEP 328. PEP 328 gives the example "from ...sys import path" in a second-level package, and notes "while that last case is legal, it is certainly discouraged".

However, in the current implementation it actually isn't legal. Using a stdlib second-level package to test:

Python 3.5.3 (default, Apr 10 2017, 07:53:16)  [GCC 6.3.0 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import xml.dom
>>> __package__ = "xml.dom"
>>> from . import minidom  # Works fine
>>> from ...sys import path
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: attempted relative import beyond top-level package

Either the documentation or the implementation should be fixed.
msg297796 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2017-07-06 03:58
That part of the PEP was never implemented - relative imports have never been allowed to cross package boundaries in practice (which is also why "from . import sys" doesn't work as an equivalent to "import sys" at the interactive prompt or in a top level module).

Rather than amending the PEP, my inclination is to drop that cross-reference from the documentation, and instead add a new subsection to https://docs.python.org/3/reference/import.html covering "Package relative imports"

The key section that needs to be extracted is https://www.python.org/dev/peps/pep-0328/#guido-s-decision (minus the part about cross-package relative imports being permitted).

The following section about __name__ is also worth including but needs to be updated to account for __package__ (added by PEP 366), and __spec__ (added by PEP 451).
msg340288 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-04-15 16:00
I actually opened a PR with the relevant documentation suggested by @ncoghlan but what am wondering is. 

when @ncoghlan says That part of the PEP was never implemented - relative imports have never been allowed to cross package boundaries in practice, does it mean we dont need this to work anymore as was earlier put in the PEP?  In which case this issue will be closed if my PR is merged or we should actually implement it to complete everything the PEP specified?
msg340299 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-04-15 18:27
RE: "does it mean we dont need this to work anymore as was earlier put in the PEP?"

Correct, we aren't going to implement that part of the PEP ever.
msg340303 - (view) Author: Joannah Nanjekye (nanjekyejoannah) * (Python committer) Date: 2019-04-15 19:14
Great, thanks for clarity.
msg340780 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-04-24 15:14
New changeset 70bf713617e15fad390ed953e48b3c65d9bc90ec by Nick Coghlan (Joannah Nanjekye) in branch 'master':
bpo-30840: Document relative imports (#12831)
https://github.com/python/cpython/commit/70bf713617e15fad390ed953e48b3c65d9bc90ec
msg340787 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-04-24 15:44
New changeset 4d0233ec656bc7e7814e5f6f484e79a50a0daf91 by Nick Coghlan (Miss Islington (bot)) in branch '3.7':
bpo-30840: Document relative imports (GH-12831) (GH-12938)
https://github.com/python/cpython/commit/4d0233ec656bc7e7814e5f6f484e79a50a0daf91
History
Date User Action Args
2019-04-24 15:45:18ncoghlansetstatus: open -> closed
type: behavior -> enhancement
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.8, - Python 3.5, Python 3.6
2019-04-24 15:44:23ncoghlansetmessages: + msg340787
2019-04-24 15:14:57miss-islingtonsetpull_requests: + pull_request12862
2019-04-24 15:14:46ncoghlansetmessages: + msg340780
2019-04-15 19:14:12nanjekyejoannahsetmessages: + msg340303
2019-04-15 18:27:39brett.cannonsetmessages: + msg340299
2019-04-15 16:00:02nanjekyejoannahsetnosy: + nanjekyejoannah
messages: + msg340288
2019-04-14 19:44:55nanjekyejoannahsetkeywords: + patch
stage: patch review
pull_requests: + pull_request12756
2017-07-06 03:58:09ncoghlansetmessages: + msg297796
2017-07-06 03:27:49r.david.murraysetnosy: + eric.snow, docs@python, brett.cannon, ncoghlan

assignee: docs@python
components: + Documentation
versions: + Python 3.6, Python 3.7
2017-07-03 19:14:52Malcolm Smithcreate