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.