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.

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

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?

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.

Great, thanks for clarity.

New changeset 70bf713 by Nick Coghlan (Joannah Nanjekye) in branch 'master':
bpo-30840: Document relative imports (bpo-12831)
70bf713

New changeset 4d0233e by Nick Coghlan (Miss Islington (bot)) in branch '3.7':
bpo-30840: Document relative imports (GH-12831) (GH-12938)
4d0233e