python - order of import for modules

I'm not sure where (or whether) this information is in the documentation - a quick check in the import system docs didn't turn it up - but PEP 420 says the following:

While looking for a module or package named "foo", for each directory in the parent path:

  • If <directory>/foo/__init__.py is found, a regular package is imported and returned.
  • If not, but <directory>/foo.{py,pyc,so,pyd} is found, a module is imported and returned. The exact list of extension varies by platform and whether the -O flag is specified. The list here is representative.
  • If not, but <directory>/foo is found and is a directory, it is recorded and the scan continues with the next directory in the parent path.
  • Otherwise the scan continues with the next directory in the parent path.

If the scan completes without returning a module or package, and at least one directory was recorded, then a namespace package is created.

So according to PEP 420, if a package and a non-package module are found in the same directory with the same name, the package wins.


Based on @JonKiparsky 's suggestion, I dug through importlib a bit, and finally found importlib._bootstrap.FileFinder.find_spec, which does indeed explicitly check for a directory before looking for valid files that fit the package name. Glad to see @user2357112 's answer, though, that this is supposed to be defined behavior, and isn't just happenstance.