Add an option to disable sys.path patching.

update changelog + contributors

Address comment to add default for option

Add unit test for namespace package sys patching

fix unit test to avoid global side effects from imports

Update faq to explain namespace package issue with imports

Author: Mehdi Drissi

CONTRIBUTORS.txt

@@ -391,6 +391,7 @@ contributors:
 - Michael Hudson-Doyle <[email protected]>
 - Michael Giuffrida <[email protected]>
 - Melvin Hazeleger <[email protected]> (melvio)
+- Mehdi Drissi: Added an option to disable sys path patching
 - Matěj Grabovský <[email protected]>
 - Matthijs Blom <[email protected]>
 - Matej Marušák <[email protected]>

ChangeLog

@@ -785,6 +785,12 @@ Release date: 2021-11-24
   longer relies on counting if statements anymore and uses known if statements locations instead.
   It should not crash on badly parsed if statements anymore.
 
+* Add an option ``disable-path-patching`` to better support namespace packages.
+  This option is disabled by default as it has a trade off with being able
+  to lint uninstalled packages.
+
+  Closes #5266
+
 * Fix ``simplify-boolean-expression`` when condition can be inferred as False.
 
   Closes #5200

doc/faq.rst

@@ -280,12 +280,24 @@ behavior. Likewise, since negative values are still technically supported,
 ``evaluation`` can be set to a version of the above expression that does not
 enforce a floor of zero.
 
-6.2 I think I found a bug in Pylint. What should I do?
+6.2 I have import errors working with a namespace package. How can I fix it?
+------------------------------------------------------------------------------
+
+If you have an implicit namespace package (i.e. a package without ``__init__.py``)
+then pylint may not be able to determine base of the package. Normally when you run
+pylint it adjusts PYTHONPATH to include the parent directory of the package you are
+working in. For namespace packages you can disable path inference with
+``--disable-path-patching`` setting. For this to work you must have the namespace package
+installed in your environment or run pylint from the directory containing the package.
+
+
+
+6.3 I think I found a bug in Pylint. What should I do?
 -------------------------------------------------------
 
 Read :ref:`Bug reports, feedback`
 
-6.3 I have a question about Pylint that isn't answered here.
+6.4 I have a question about Pylint that isn't answered here.
 ------------------------------------------------------------
 
 Read :ref:`Mailing lists`

doc/whatsnew/2.14.rst

@@ -42,6 +42,12 @@ Extensions
 Other Changes
 =============
 
+* Add an option ``disable-path-patching`` to better support namespace packages.
+  This option is disabled by default as it has a trade off with being able
+  to lint uninstalled packages.
+
+  Closes #5266
+
 * Only raise ``not-callable`` when all the inferred values of a property are not callable.
 
   Closes #5931

pylint/lint/pylinter.py

@@ -536,6 +536,21 @@ def make_options() -> Tuple[Tuple[str, OptionDict], ...]:
                     ),
                 },
             ),
+            (
+                "disable-path-patching",
+                {
+                    "type": "yn",
+                    "metavar": "<y or n>",
+                    "default": False,
+                    "help": (
+                        "Disable the patching of sys.path when searching for "
+                        "modules. This is useful for implicit namespace packages where "
+                        "inferring base path of package is ambiguous. The downside is without "
+                        "patching, the files being linted must be importable from the location "
+                        "the script is run in interpreter."
+                    ),
+                },
+            ),
         )
 
     base_option_groups = (
@@ -1058,13 +1073,13 @@ def check(self, files_or_modules: Union[Sequence[str], str]) -> None:
                 )
 
             filepath = files_or_modules[0]
-            with fix_import_path(files_or_modules):
+            with fix_import_path(files_or_modules, self.config.disable_path_patching):
                 self._check_files(
                     functools.partial(self.get_ast, data=_read_stdin()),
                     [self._get_file_descr_from_stdin(filepath)],
                 )
         elif self.config.jobs == 1:
-            with fix_import_path(files_or_modules):
+            with fix_import_path(files_or_modules, self.config.disable_path_patching):
                 self._check_files(
                     self.get_ast, self._iterate_file_descrs(files_or_modules)
                 )

pylint/lint/utils.py

@@ -108,7 +108,6 @@ def preprocess_options(args, search_for):
 
 
 def _patch_sys_path(args):
-    original = list(sys.path)
     changes = []
     seen = set()
     for arg in args:
@@ -118,19 +117,25 @@ def _patch_sys_path(args):
             seen.add(path)
 
     sys.path[:] = changes + sys.path
-    return original
 
 
 @contextlib.contextmanager
-def fix_import_path(args):
+def fix_import_path(args, disable_path_patching: bool = False):
     """Prepare 'sys.path' for running the linter checks.
 
+    'disable_path_patching' if True will make this context manager a no-op.
+    The reason for disabling path patching is to allow running the linter
+    using default path which can be safer then patching the path for implicit
+    namespace packages.
+
     Within this context, each of the given arguments is importable.
     Paths are added to 'sys.path' in corresponding order to the arguments.
     We avoid adding duplicate directories to sys.path.
     `sys.path` is reset to its original value upon exiting this context.
     """
-    original = _patch_sys_path(args)
+    original = list(sys.path)
+    if not disable_path_patching:
+        _patch_sys_path(args)
     try:
         yield
     finally:

pylint/pyreverse/main.py

@@ -191,6 +191,21 @@
             help="set the output directory path.",
         ),
     ),
+    (
+        "disable-path-patching",
+        dict(
+            type="yn",
+            metavar="<y or n>",
+            default=False,
+            help=(
+                "Disable the patching of sys.path when searching for "
+                "modules. This is useful for implicit namespace packages where "
+                "inferring base path of package is ambiguous. The downside is without "
+                "patching, the files being linted must be importable from the location "
+                "the script is run in interpreter."
+            ),
+        ),
+    ),
 )
 
 
@@ -217,7 +232,7 @@ def run(self, args):
         if not args:
             print(self.help())
             return 1
-        with fix_import_path(args):
+        with fix_import_path(args, self.config.disable_path_patching):
             project = project_from_files(
                 args,
                 project_name=self.config.project,

pylint/testutils/_fake.py

@@ -0,0 +1,12 @@
+# 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
+
+"""This file is intended to only be used for testing namespace package importing.
+
+   Importing a file has a global side effect of adding a module to sys.modules.
+   As namespace packages are sensitive to sys.path, to test them we check
+   an intentional import error and a successful import. To avoid the imports
+   messing up the test environment, we need to make the import error use
+   a file that is never imported by any other test. This serves as that file.
+"""

tests/functional/n/namespace_package/pylint/__init__.py

@@ -0,0 +1,2 @@
+# pylint: disable=missing-docstring,unused-import
+from pylint.testutils import _fake  # [no-name-in-module]

tests/functional/n/namespace_package/pylint/testutils/__init__.py

@@ -0,0 +1 @@
+no-name-in-module:2:0::No name '_fake' in module 'pylint.testutils':HIGH

tests/functional/n/namespace_package/pylint/testutils/namespace_package.py

@@ -0,0 +1,2 @@
+# pylint: disable=missing-docstring,unused-import
+from pylint import lint

tests/functional/n/namespace_package/pylint/testutils/namespace_package.txt

@@ -0,0 +1,2 @@
+[master]
+disable-path-patching=yes