Add a --generate-toml-config option (#6199)

Author: DanielNoord

ChangeLog

@@ -85,6 +85,10 @@ Release date: TBA
 
   Closes #5205
 
+* Added the ``generate-toml-config`` option.
+
+  Ref #5462
+
 * Added new checker ``unnecessary-list-index-lookup`` for indexing into a list while
   iterating over ``enumerate()``.
 

doc/faq.rst

@@ -100,16 +100,16 @@ localized using the following rules:
 
 * ".pylint.d" directory in the current directory
 
-3.3 How do I find the option name (for pylintrc) corresponding to a specific command line option?
+3.3 How do I find the option name corresponding to a specific command line option?
 --------------------------------------------------------------------------------------------------------
 
-You can generate a sample pylintrc file with --generate-rcfile
+You can generate a sample configuration file with ``--generate-toml-config``.
 Every option present on the command line before this will be included in
-the rc file
+the toml file
 
 For example::
 
-    pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-rcfile
+    pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-toml-config
 
 3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
 ---------------------------------------------------------------------------------------

doc/intro.rst

@@ -53,5 +53,6 @@ The best way to tackle pylint's verboseness is to:
   all convention messages is simple as a ``--disable=C`` option added to pylint
   command.
 
-* create a custom configuration file, tailored to your needs. You can generate
-  one using pylint's command ``--generate-rcfile``.
+* manage the configuration through a configuration file. With the option
+  ``generate-toml-config`` you can create a piece of ``.toml`` text to put
+  in your ``pyproject.toml`` file.

doc/tutorial.rst

@@ -59,7 +59,7 @@ A couple of the options that we'll focus on here are: ::
 
   Commands:
     --help-msg=<msg-id>
-    --generate-rcfile
+    --generate-toml-config
   Messages control:
     --disable=<msg-ids>
   Reports:
@@ -273,7 +273,8 @@ example but go ahead and `read up`_ on them if you want.
  It would really be a pain to specify that regex on the command line all the time, particularly if we're using many other options.
  That's what a configuration file is for. We can configure our Pylint to
  store our options for us so we don't have to declare them on the command line.  Using a configuration file is a nice way of formalizing your rules and
- quickly sharing them with others. Invoking ``pylint --generate-rcfile`` will create a sample rcfile with all the options set and explained in comments.
+ quickly sharing them with others. Invoking ``pylint --generate-toml-config`` will create a sample ``.toml`` section with all the options set and explained in comments.
+ This can then be added to your ``pyproject.toml`` file or any other ``.toml`` file pointed to with the ``--rcfile`` option.
 
 That's it for the basic intro. More tutorials will follow.
 

doc/user_guide/run.rst

@@ -178,12 +178,12 @@ configuration file in the following order and uses the first one it finds:
 
 #. ``/etc/pylintrc``
 
-The ``--generate-rcfile`` option will generate a commented configuration file
+The ``--generate-toml-config`` option will generate a commented configuration file
 on standard output according to the current configuration and exit. This
 includes:
 
 * Any configuration file found as explained above
-* Options appearing before ``--generate-rcfile`` on the Pylint command line
+* Options appearing before ``--generate-toml-config`` on the Pylint command line
 
 Of course you can also start with the default values and hand-tune the
 configuration.

doc/whatsnew/2.14.rst

@@ -95,6 +95,10 @@ Other Changes
 
   Ref #5392
 
+* Added the ``generate-toml-config`` option.
+
+  Ref #5462
+
 * Fix false negative for ``bad-string-format-type`` if the value to be formatted is passed in
   as a variable holding a constant.
 

pylint/config/arguments_manager.py

@@ -10,11 +10,15 @@
 import copy
 import optparse  # pylint: disable=deprecated-module
 import os
+import re
 import sys
+import textwrap
 import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, TextIO, Tuple, Union
 
+import tomlkit
+
 from pylint import utils
 from pylint.config.argument import (
     _Argument,
@@ -595,3 +599,74 @@ def cb_set_provider_option(self, option, opt, value, parser):  # pragma: no cove
     def global_set_option(self, opt, value):
         """Set option on the correct option provider."""
         self._all_options[opt].set_option(opt, value)
+
+    def _generate_config_file(self) -> None:
+        """Write a configuration file according to the current configuration into stdout."""
+        toml_doc = tomlkit.document()
+        pylint_tool_table = tomlkit.table(is_super_table=True)
+        toml_doc.add(tomlkit.key(["tool", "pylint"]), pylint_tool_table)
+
+        for group in sorted(
+            self._arg_parser._action_groups,
+            key=lambda x: (x.title != "Master", x.title),
+        ):
+            # Skip the options section with the --help option
+            if group.title == "options":
+                continue
+
+            # Skip sections without options such as "positional arguments"
+            if not group._group_actions:
+                continue
+
+            group_table = tomlkit.table()
+            for action in sorted(
+                group._group_actions, key=lambda x: x.option_strings[0][2:]
+            ):
+                optname = action.option_strings[0][2:]
+
+                # We skip old name options that don't have their own optdict
+                try:
+                    optdict = self._option_dicts[optname]
+                except KeyError:
+                    continue
+
+                if optdict.get("hide_from_config_file"):
+                    continue
+
+                # Add help comment
+                help_msg = optdict.get("help", "")
+                assert isinstance(help_msg, str)
+                help_text = textwrap.wrap(help_msg, width=79)
+                for line in help_text:
+                    group_table.add(tomlkit.comment(line))
+
+                # Get current value of option
+                value = getattr(self.namespace, optname.replace("-", "_"))
+
+                # Create a comment if the option has no value
+                if not value:
+                    group_table.add(tomlkit.comment(f"{optname} ="))
+                    group_table.add(tomlkit.nl())
+                    continue
+
+                # Tomlkit doesn't support regular expressions
+                if isinstance(value, re.Pattern):
+                    value = value.pattern
+                elif isinstance(value, (list, tuple)) and isinstance(
+                    value[0], re.Pattern
+                ):
+                    value = [i.pattern for i in value]
+
+                # Add to table
+                group_table.add(optname, value)
+                group_table.add(tomlkit.nl())
+
+            assert group.title
+            pylint_tool_table.add(group.title.lower(), group_table)
+
+        toml_string = tomlkit.dumps(toml_doc)
+
+        # Make sure the string we produce is valid toml and can be parsed
+        tomllib.loads(toml_string)
+
+        print(toml_string)

pylint/config/callback_actions.py

@@ -245,6 +245,20 @@ def __call__(
         sys.exit(0)
 
 
+class _GenerateConfigFileAction(_AccessRunObjectAction):
+    """Generate a .toml format configuration file."""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: Union[str, Sequence[Any], None],
+        option_string: Optional[str] = "--generate-toml-config",
+    ) -> None:
+        self.run.linter._generate_config_file()
+        sys.exit(0)
+
+
 class _ErrorsOnlyModeAction(_AccessRunObjectAction):
     """Turn on errors-only mode.
 

pylint/lint/run.py

@@ -12,6 +12,7 @@
     _DoNothingAction,
     _ErrorsOnlyModeAction,
     _FullDocumentationAction,
+    _GenerateConfigFileAction,
     _GenerateRCFileAction,
     _ListCheckGroupsAction,
     _ListConfidenceLevelsAction,
@@ -104,6 +105,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "group": "Commands",
                         "help": "Specify a configuration file to load.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -114,6 +116,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "group": "Commands",
                         "help": "Specify an output file.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -135,6 +138,7 @@ def __init__(
                         "group": "Commands",
                         "help": "Display a help message for the given message id and "
                         "exit. The value may be a comma separated list of message ids.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -146,6 +150,7 @@ def __init__(
                         "group": "Commands",
                         "help": "Display a list of all pylint's messages divided by whether "
                         "they are emittable with the given interpreter.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -157,6 +162,7 @@ def __init__(
                         "group": "Commands",
                         "help": "Display a list of what messages are enabled, "
                         "disabled and non-emittable with the given configuration.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -167,6 +173,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "group": "Commands",
                         "help": "List pylint's message groups.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -177,6 +184,7 @@ def __init__(
                         "kwargs": {"Run": self},
                         "group": "Commands",
                         "help": "Generate pylint's confidence levels.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -187,6 +195,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "group": "Commands",
                         "help": "List available extensions.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -197,6 +206,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "group": "Commands",
                         "help": "Generate pylint's full documentation.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -210,6 +220,21 @@ def __init__(
                         "the current configuration. You can put other options "
                         "before this one to get them in the generated "
                         "configuration.",
+                        "hide_from_config_file": True,
+                    },
+                ),
+                (
+                    "generate-toml-config",
+                    {
+                        "action": _GenerateConfigFileAction,
+                        "kwargs": {"Run": self},
+                        "callback": Run._not_implemented_callback,
+                        "group": "Commands",
+                        "help": "Generate a sample configuration file according to "
+                        "the current configuration. You can put other options "
+                        "before this one to get them in the generated "
+                        "configuration. The config is in the .toml format.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -222,6 +247,7 @@ def __init__(
                         "help": "In error mode, checkers without error messages are "
                         "disabled and for others, only the ERROR messages are "
                         "displayed, and no reports are done by default.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -233,6 +259,7 @@ def __init__(
                         "short": "v",
                         "help": "In verbose mode, extra non-checker-related info "
                         "will be displayed.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -243,6 +270,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "help": "Load and enable all available extensions. "
                         "Use --list-extensions to see a list all available extensions.",
+                        "hide_from_config_file": True,
                     },
                 ),
                 (
@@ -253,6 +281,7 @@ def __init__(
                         "callback": Run._not_implemented_callback,
                         "help": "Show more verbose help.",
                         "group": "Commands",
+                        "hide_from_config_file": True,
                     },
                 ),
             ),

setup.cfg

@@ -51,6 +51,7 @@ install_requires =
     isort>=4.2.5,<6
     mccabe>=0.6,<0.8
     tomli>=1.1.0;python_version<"3.11"
+    tomlkit>=0.10.1
     colorama;sys_platform=="win32"
     typing-extensions>=3.10.0;python_version<"3.10"
 python_requires = >=3.7.2
@@ -135,6 +136,9 @@ ignore_missing_imports = True
 [mypy-git.*]
 ignore_missing_imports = True
 
+[mypy-tomlkit]
+ignore_missing_imports = True
+
 [mypy-sphinx.*]
 ignore_missing_imports = True