Documentation page for configuration file

[pawamoy]

Each time I want to try pylint again, I face the same issue: I go to the official documentation to search for information about the configuration file, but can't seem to find anything easily.

Obviously, I go to "User Guide -> Configuration" (https://pylint.readthedocs.io/en/latest/user_guide/options.html) but this is not at all what I expect. There's nothing about the the pylintrc file, or the available configuration options like max-line-length. To know if pylint supported pyproject.toml, I had to read the "Running Pylint" section 😕

Then I tell myself, "the options names must be the same on the CLI and in the [tool.pylint] section", so I write this:

[tool.pylint]
max-line-length = 120
disable = ["C0330"]

...but it doesn't seem to be taken into account. Should I replace - with _? Should options be in a sub-table? Where do I find this information?

Answers are: I don't know. The search feature on the documentation doesn't help. I eventually went to the FAQ: https://pylint.readthedocs.io/en/latest/faq.html#how-do-i-find-the-option-name-for-pylintrc-corresponding-to-a-specific-command-line-option. So now I know I can get the option name for --max-line-length by generating the pylintrc file, and copy-pasting it into pyproject.toml. I see that disable actually takes the verbose name and not the code (I have to scroll my buffer back to get the name).

But it still does not work 😕

How one should write the [tool.pylint] section?

Am I the only one having a hard time with pylint's documentation structure?

EDIT: found the answers in the changelog: http://pylint.pycqa.org/en/latest/whatsnew/2.5.html. Section must be named [tool.pylint.'MESSAGES CONTROL'] or similar. This feature has not been released yet.

[PCManticore]

Thanks for the feedback. Our documentation definitely needs some attention.

[BenQuigley]

Just to finish resolving @pawamoy's problem (which I also just ran into), a correct format would be:

[tool.pylint.'MESSAGES CONTROL']
max-line-length = 120
disable = "C0330, R0201"

Added R0201 to show disabling more than one error. It seems that triple-quoted docstrings can be used for a multiline string and that this works for the pylint disable list. But if OP leaves their disable in the list format (with those square brackets), then pylint will say something like:

Traceback (most recent call last):
  File "/usr/lib/python3.8/runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.8/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/home/OP/.local/lib/python3.8/site-packages/pylint/__main__.py", line 18, in <module>
    pylint.run_pylint()
  File "/home/OP/.local/lib/python3.8/site-packages/pylint/__init__.py", line 22, in run_pylint
    PylintRun(sys.argv[1:])
  File "/home/OP/.local/lib/python3.8/site-packages/pylint/lint/run.py", line 300, in __init__
    linter.load_config_file()
  File "/home/OP/.local/lib/python3.8/site-packages/pylint/config.py", line 785, in load_config_file
    for option, value in parser.items(section):
  File "/usr/lib/python3.8/configparser.py", line 859, in items
    return [(option, value_getter(option)) for option in orig_keys]
  File "/usr/lib/python3.8/configparser.py", line 859, in <listcomp>
    return [(option, value_getter(option)) for option in orig_keys]
  File "/usr/lib/python3.8/configparser.py", line 855, in <lambda>
    value_getter = lambda option: self._interpolation.before_get(self,
  File "/usr/lib/python3.8/configparser.py", line 395, in before_get
    self._interpolate_some(parser, option, L, value, section, defaults, 1)
  File "/usr/lib/python3.8/configparser.py", line 412, in _interpolate_some
    p = rest.find("%")
AttributeError: 'list' object has no attribute 'find'

[FlorianLudwig]

Testing with pylint 2.6

[tool.pylint.messages_control] does work as well as [tool.pylint.'MESSAGES CONTROL']. Which looks a bit nicer to me :)

Example config:

[tool.pylint.messages_control]

max-line-length = 88

disable = [
  "missing-docstring",
  "unused-argument",
  "no-value-for-parameter",
  "no-member",
  "no-else-return",
  "bad-whitespace",
  "bad-continuation",
  "line-too-long",
  "fixme",
  "protected-access",
  "too-few-public-methods",
]

[tool.pylint.design]
# limiting the number of returns might discourage
# the use of guard clauses. So we increase the
# allowed number of returns from 6 to 8
max-returns = 8

[Palisand]

To tell what options belong to which section, you can generate an rc file (--generate-rcfile).

[FORMAT]

# Maximum number of lines in a module.
max-module-lines=1000

[tool.pylint.format]
max-module-lines = 1000

[ThatXliner]

I have

[tool.pylint.MASTER]
load-plugins = "pylint_websockets"

With Pylint failing with

AttributeError: 'str' object has no attribute 'items'

[Pierre-Sassoulas]

@ThatXliner this look like a crash, please open another issue as this was relates to documentation.

[ThatXliner]

@ThatXliner this look like a crash, please open another issue as this was relates to documentation.

Ok, I was just making sure that I have the configuration set up correct and that it wasn't my fault.

[ThatXliner]

Nevermind, I just realized it was my mistake. I placed the configuration in the middle of another field 😬

[Pierre-Sassoulas]

This is not "your fault" as pylint outright crash and is not helpful at all in the error it gives :) We're trying to make this kind error more understandable for toml in #4580 / #4720 , feel free to come make suggestions if you like (and in particular giving the offending code that was crashing in your case was very helpful) !

[Pierre-Sassoulas]

There will be a new message bad-configuration-section in 2.12, there is sadly still an issue with top level dictionary or option not in the right top level section that will fail silently. A lot of progress was done in #4720 and #5287 to make it easier to test configurations, so it will now be easier to make this part of the code evolve, and we're aiming to fix this in the future in the follow up issue #5259. This still need to be documented as if you don't know what to do at all you won't even encounter those errors.

[mbdevpl]

Just in case anybody else wonders about the load-plugins in pyroject.toml, from my experiments both of the below seem to work:

[tool.pylint.MASTER]
load-plugins = 'pylint.extensions.mccabe,pylint.extensions.redefined_variable_type,pylint.extensions.broad_try_clause'

[tool.pylint.MASTER]
load-plugins = [
    'pylint.extensions.mccabe',
    'pylint.extensions.redefined_variable_type',
    'pylint.extensions.broad_try_clause'
]

... but of course the 2nd one looks so much better :)

Similar flexibility seems to be allowed by other fields that expect comma-separated lists, and interestingly in pydocstyle as well... Although I'm not sure if that's intended/guaranteed in any way. But if it is, it may be useful to add this to docs, as it offers a more convenient migration path from old config formats than having to reformat everything.

E.g. both of these work:

[tool.pydocstyle]
ignore = 'D102,D103'

[tool.pydocstyle]
ignore = ['D102', 'D103']

[Pierre-Sassoulas]

Thank to @DanielNoord's amazing work, all the possible options were documented in #6346, the result is here , there's also a better error handling yet again with the migration from optparse to argparse being complete. You can also generate a sample configuration file with --generate-toml-config as documented here. I'm going to close. Please open a new more specific issue if something is not clear enough in the configuration documentation.