From 70c4ca365716eac6e1fde162f085e96b642b947d Mon Sep 17 00:00:00 2001 From: TheD0ubleC Date: Mon, 6 Jul 2026 22:54:07 +0800 Subject: [PATCH 1/2] gh-61310: Document package precedence over same-named modules --- Doc/reference/import.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 4c8811560de2e3f..09fd5f9ce60cc79 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -665,6 +665,13 @@ 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 file system path entry, the default finder checks for regular +packages before same-named modules. For example, if the same directory contains +both ``spam/__init__.py`` and ``spam.py``, ``import spam`` will import the +package from ``spam/__init__.py``. This does not override the order of +:data:`sys.path`: a module found in an earlier path entry still takes precedence +over a package found in a later one. + 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. From fd16e8aeaf6b8740295209e136d5963bc9a63aea Mon Sep 17 00:00:00 2001 From: YiYi <143760576+TheD0ubleC@users.noreply.github.com> Date: Tue, 7 Jul 2026 08:38:42 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20import.rst?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stan Ulbrych --- Doc/reference/import.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 09fd5f9ce60cc79..2ff88cb6b1fed54 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -665,12 +665,14 @@ 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 file system path entry, the default finder checks for regular -packages before same-named modules. For example, if the same directory contains -both ``spam/__init__.py`` and ``spam.py``, ``import spam`` will import the -package from ``spam/__init__.py``. This does not override the order of -:data:`sys.path`: a module found in an earlier path entry still takes precedence -over a package found in a later one. +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