python - Python3 submodules setup does not update paths when run with -m switch

Question

I have the following project structure:

server/
   server.py
   __init__.py

   sockets/
      module.py
      __init__.py

I set PYTHONPATH to one directory above server (for example /home/user/server contains server, PYTHONPATH is set /home/user).

The main file is server.py; it imports modules:

import sockets
from sockets.module import Module

When I run python3 $PYTHONPATH/server/server.py directly it works perfectly. However when I call python3 -m server.server.py it fails, despite the fact that it is explicitly recommended to avoid Python path hell, but it fails to find the the module, with an ugly message:

/usr/bin/python3: Error while finding spec for 'server.server.py' (<class 'ImportError'>: No module named 'sockets')

Why does the module import fail to import submodules? How to properly setup sub-packages?

Answer 1

The behaviour is entirely correct; sockets is not a top-level module. However, when you use $PYTHONPATH/server/server.py, Python also adds $PYTHONPATH/server/ to the Python search path, so now sockets is a top-level module. You should never directly run files in a package.

Import sockets relative to the current package:

from . import sockets
from .sockets.module import Module 

or use fully-qualified imports:

from server import sockets
from server.sockets.module import Module 

Also see the Interface Options section of the Python Setup and Usage section in the fine manual:

If the script name refers directly to a Python file, the directory containing that file is added to the start of sys.path, and the file is executed as the __main__ module.

Note that the -m switch takes a python identifier, not a filename, so use:

python -m server.server

leaving of the .py extension.