gh-61310: Document package precedence over same-named modules (#153211)

Co-authored-by: TheD0ubleC <cc@scmd.cc>
Co-authored-by: Stan Ulbrych <stan@python.org>

diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 4c8811560de2e3f6eaf287a871db5f60f5eb8f88..2ff88cb6b1fed5408234fec2dc54dfac96f075c3 100644 (file)
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -665,6 +665,15 @@ shared libraries (e.g. ``.so`` files). When supported by the :mod:`zipimport`
 module in the standard library, the default path entry finders also handle
 loading all of these file types (other than shared libraries) from zipfiles.
 
+Within a single :term:`path entry`, the default path entry finders check for a
+:term:`regular package` first, then for extension modules, then for source
+files, and finally for bytecode files. For example, if the same directory
+contains both ``spam/__init__.py`` and ``spam.py``, ``import spam`` will
+import the package from ``spam/__init__.py``. A directory without an
+``__init__.py`` file is treated as a :term:`namespace package` portion only if
+no matching module is found. Note that this does not override the order of the
+:term:`import path`.
+
 Path entries need not be limited to file system locations.  They can refer to
 URLs, database queries, or any other location that can be specified as a
 string.