Do not append namespace packages to sys.path

ChangeLog

@@ -17,6 +17,13 @@ Release date: TBA
 
   Closes #4301
 
+* Improved recognition of namespace packages. They should no longer be added to ``sys.path``
+  which should prevent various issues with false positives.
+  Because of the difficulities with mirroring the python import mechanics we would gladly
+  hear feedback on this change.
+
+  Closes #5226, Closes #2648
+
 * ``BaseChecker`` classes now require the ``linter`` argument to be passed.
 
 * Fix a failure to respect inline disables for ``fixme`` occurring on the last line

doc/whatsnew/2.14.rst

@@ -81,6 +81,13 @@ Other Changes
 
   Closes #4301
 
+* Improved recognition of namespace packages. They should no longer be added to ``sys.path``
+  which should prevent various issues with false positives.
+  Because of the difficulities with mirroring the python import mechanics we would gladly
+  hear feedback on this change.
+
+  Closes #5226, Closes #2648
+
 * Update ``invalid-slots-object`` message to show bad object rather than its inferred value.
 
   Closes #6101

pylint/lint/utils.py

@@ -11,6 +11,8 @@
 from datetime import datetime
 from pathlib import Path
 
+from astroid import modutils
+
 from pylint.config import PYLINT_HOME
 from pylint.lint.expand_modules import get_python_path
 
@@ -71,12 +73,32 @@ def get_fatal_error_message(filepath: str, issue_template_path: Path) -> str:
     )
 
 
+def _is_part_of_namespace_package(filename: str) -> bool:
+    """Check if a file is part of a namespace package."""
+    filepath = Path(filename)
+    try:
+        modname = modutils.modpath_from_file(filename)
+    except ImportError:
+        modname = [filepath.stem]
+    if filepath.is_dir():
+        filepath = filepath / "__init__.py"
+
+    try:
+        spec = modutils.file_info_from_modpath(modname)
+    except ImportError:
+        return False
+
+    return modutils.is_namespace(spec)
+
+
 def _patch_sys_path(args: Sequence[str]) -> list[str]:
     original = list(sys.path)
     changes = []
     seen = set()
     for arg in args:
         path = get_python_path(arg)
+        if _is_part_of_namespace_package(path):
+            continue
         if path not in seen:
             changes.append(path)
             seen.add(path)

test_namespace_pkg/existing/__init__.py

@@ -0,0 +1,7 @@
+# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+# For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
+# Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt
+
+from existing import my_func  # type: ignore[attr-defined]
+
+my_func()

tests/lint/unittest_lint.py

@@ -9,6 +9,7 @@
 import argparse
 import os
 import re
+import subprocess
 import sys
 import tempfile
 from collections.abc import Iterable, Iterator
@@ -170,6 +171,16 @@ def test_more_args(fake_path, case):
         assert sys.path == fake_path
 
 
+def test_namespace_package_sys_path() -> None:
+    """Test that we do not append namespace packages to sys.path."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pylint", "test_namespace_pkg/"],
+        check=False,
+        stdout=subprocess.PIPE,
+    )
+    assert "Module import itself" not in result.stdout.decode("utf-8")
+
+
 @pytest.fixture(scope="module")
 def disable():
     return ["I"]