ValueError: attempted relative import beyond top-level package

python-3.xpython-import

I was playing the the Python's import system in order to understand better how it works, and I encountered another problem. I have the following structure 

pkg/
    __init__.py
    c.py
    d.py

    subpkg/
        __init__.py
        a.py
        b.py

Inside a.py I have the following code:

from . import b
from .. import d

And inside c.py I have the following:

import subpkg.a

Now I receive the following error:

ValueError: attempted relative import beyond top-level package

But why? How can I solve it? I am running c.py from the IDLE, and pkg should be considered a package, since it has the __init__.py file.

The first import works fine, but it's the following that doesn't work:

from .. import d

Because I am attempting to import something from a parent package, but apparently I cannot, for some weird reason.

Best Answer

This had me question my insanity.

The problem stems from the confusion that people mistakenly take the relative import as path relative which is not.

Relative imports depend on the location of the file that is run.

This answer goes deeper into explaining how the python modules actually work, but to summarize.

  1. When a file is loaded, it is given a name:
    • If it was loaded as the top-level script (run directly), its name is __main__.
    • If it was loaded as a module (with import), its name is the filename, preceded by the names of any packages/subpackages of which it is a part, separated by dots - pkg.subpkg.a
  2. If you do a from .. there must be at least 2 dots in the file name. from ... - 3 dots.

Now comes the funny part.

If you run c.py directly, then it is given the name __main__ and a.py has subpkg.a.

As per the 2nd statement, you must have at least 2 dots in the name of subpkg.a to run from .. inside it.

The fix

Create a new file outside the pkg, say main.py

pkg/
    __init__.py
    c.py
    d.py

    subpkg/
        __init__.py
        a.py
        b.py
main.py

Inside main.py

import pkg.c

If we run main.py, it get's the name __main__, and a.py get's pkg.subpkg.a. As per the 2nd statement it now has 2 dots in the name and we can do the from ..

One more thing. Now that c.py is loaded as a module, we have to use from to load a.py.

from .subpkg import a
Related Topic