Add the files option (#7496)

* Add the ``files`` option

* [tests] Cover ``files`` option via the config testing framework

Replace the single unit test for the new ``files`` option with functional
configuration files (TOML + INI) and focused tests that use
``run_using_a_configuration_file``. Extend the helper with a
``file_to_lint=None`` mode so a config can supply files via the ``files``
option itself without positional args forcing an override.

---------

Co-authored-by: Pierre Sassoulas <[email protected]>

Author: DanielNoord

doc/whatsnew/fragments/5701.other

@@ -0,0 +1,7 @@
+You can now set the ``files`` option in configuration files and on the command line.
+Passing files without the ``--files`` flag is still supported. This allows to set
+``files`` to ``files = my_source_directory`` and invoking ``pylint`` with only
+the ``pylint`` command similar to how other CLI tools allow to do so.
+The help message can always be invoked with ``pylint -h`` or ``pylint --help``.
+
+Closes #5701

pylint/config/config_initialization.py

@@ -30,7 +30,7 @@ def _config_initialization(  # pylint: disable=too-many-statements
     reporter: reporters.BaseReporter | reporters.MultiReporter | None = None,
     config_file: None | str | Path = None,
     verbose_mode: bool = False,
-) -> list[str]:
+) -> None:
     """Parse all available options, read config files and command line arguments and
     set options accordingly.
     """
@@ -153,17 +153,20 @@ def _config_initialization(  # pylint: disable=too-many-statements
     linter._directory_namespaces[Path().resolve()] = (linter.config, {})
 
     # parsed_args_list should now only be a list of inputs to lint.
-    # All other options have been removed from the list.
-    return list(
-        chain.from_iterable(
-            # NOTE: 'or [arg]' is needed in the case the input file or directory does
-            # not exist and 'glob(arg)' cannot find anything. Without this we would
-            # not be able to output the fatal import error for this module later on,
-            # as it would get silently ignored.
-            glob(arg, recursive=True) or [arg]
-            for arg in parsed_args_list
+    # All other options have been removed from the list. If there are any
+    # positional arguments, they override any `files` set in the configuration
+    # file.
+    if parsed_args_list:
+        linter.config.files = list(
+            chain.from_iterable(
+                # NOTE: 'or [arg]' is needed in the case the input file or directory does
+                # not exist and 'glob(arg)' cannot find anything. Without this we would
+                # not be able to output the fatal import error for this module later on,
+                # as it would get silently ignored.
+                glob(arg, recursive=True) or [arg]
+                for arg in parsed_args_list
+            )
         )
-    )
 
 
 def _order_all_first(config_args: list[str], *, joined: bool) -> list[str]:

pylint/lint/base_options.py

@@ -413,6 +413,18 @@ def _make_linter_options(linter: PyLinter) -> Options:
                 "messages.",
             },
         ),
+        (
+            "files",
+            {
+                "type": "csv",
+                "default": [],
+                "help": "The files to lint. The flag can also be omitted as pylint will "
+                "try to lint any file passed as argument. This can be used to set files "
+                "to a directory in a configuration file and invoke pylint by only typing "
+                "pylint on the command line. Any file passed as argument will overwrite any "
+                "file set in the configuration file.",
+            },
+        ),
     )
 
 

pylint/lint/run.py

@@ -175,7 +175,7 @@ def __init__(
         if self._is_pylint_config:
             _register_generate_config_options(linter._arg_parser)
 
-        args = _config_initialization(
+        _config_initialization(
             linter, args, reporter, config_file=self._rcfile, verbose_mode=self.verbose
         )
 
@@ -195,7 +195,7 @@ def __init__(
         disable_all_msg_set = set(
             msg.symbol for msg in linter.msgs_store.messages
         ) - set(msg[1] for msg in linter.default_enabled_messages.values())
-        if not args or (
+        if not linter.config.files or (
             len(linter.config.enable) == 0
             and set(linter.config.disable) == disable_all_msg_set
         ):
@@ -225,13 +225,13 @@ def __init__(
             try:
                 with open(self._output, "w", encoding="utf-8") as output:
                     linter.reporter.out = output
-                    linter.check(args)
+                    linter.check(linter.config.files)
                     score_value = linter.generate_reports(verbose=self.verbose)
             except OSError as ex:
                 print(ex, file=sys.stderr)
                 sys.exit(32)
         else:
-            linter.check(args)
+            linter.check(linter.config.files)
             score_value = linter.generate_reports(verbose=self.verbose)
         if linter.config.clear_cache_post_run:
             clear_lru_caches()

pylint/testutils/configuration_test.py

@@ -133,11 +133,18 @@ def get_expected_output(
 
 
 def run_using_a_configuration_file(
-    configuration_path: Path | str, file_to_lint: str = __file__
+    configuration_path: Path | str, file_to_lint: str | None = __file__
 ) -> Run:
-    """Simulate a run with a configuration without really launching the checks."""
+    """Simulate a run with a configuration without really launching the checks.
+
+    Pass ``file_to_lint=None`` to omit the positional argument, e.g. when
+    testing a configuration that supplies the files to lint via the
+    ``files`` option.
+    """
     configuration_path = str(configuration_path)
-    args = ["--rcfile", configuration_path, file_to_lint]
+    args = ["--rcfile", configuration_path]
+    if file_to_lint is not None:
+        args.append(file_to_lint)
     # Do not actually run checks, that could be slow. We don't mock
     # `PyLinter.check`: it calls `PyLinter.initialize` which is
     # needed to properly set up messages inclusion/exclusion

tests/config/functional/ini/pylintrc_with_files.ini

@@ -0,0 +1,4 @@
+# Check that we can set the ``files`` option in an INI configuration file.
+# See https://github.com/pylint-dev/pylint/issues/5701
+[MAIN]
+files = src,tests/regression

tests/config/functional/toml/toml_with_files.toml

@@ -0,0 +1,8 @@
+# Check that we can set the ``files`` option in a TOML configuration file.
+# See https://github.com/pylint-dev/pylint/issues/5701
+
+[tool.pylint.main]
+files = [
+    "src",
+    "tests/regression",
+]

tests/config/test_config.py

@@ -242,3 +242,39 @@ def test_enable_before_disable_all_takes_effect() -> None:
         / "toml_with_specific_enable_before_disable_all.toml",
     )
     assert toml_runner.linter.is_message_enabled("fixme")
+
+
+def test_files_option_parsed_from_toml() -> None:
+    """The ``files`` option is read from a TOML configuration file."""
+    runner = run_using_a_configuration_file(
+        HERE / "functional" / "toml" / "toml_with_files.toml",
+        file_to_lint=None,
+    )
+    assert runner.linter.config.files == ["src", "tests/regression"]
+
+
+def test_files_option_parsed_from_ini() -> None:
+    """The ``files`` option is read from an INI configuration file."""
+    runner = run_using_a_configuration_file(
+        HERE / "functional" / "ini" / "pylintrc_with_files.ini",
+        file_to_lint=None,
+    )
+    assert runner.linter.config.files == ["src", "tests/regression"]
+
+
+def test_files_option_overridden_by_positional_args() -> None:
+    """Positional CLI arguments override ``files`` set in a config file."""
+    runner = run_using_a_configuration_file(
+        HERE / "functional" / "toml" / "toml_with_files.toml",
+        file_to_lint=str(EMPTY_MODULE),
+    )
+    assert runner.linter.config.files == [str(EMPTY_MODULE)]
+
+
+def test_files_option_overridden_by_files_flag() -> None:
+    """The ``--files`` CLI flag overrides ``files`` set in a config file."""
+    config_path = HERE / "functional" / "toml" / "toml_with_files.toml"
+    runner = Run(
+        ["--rcfile", str(config_path), "--files", str(EMPTY_MODULE)], exit=False
+    )
+    assert runner.linter.config.files == [str(EMPTY_MODULE)]