top-level lint options grouped under [tool.ruff.lint]

[AlessandroMiola]

Hi everybody,
I'm trying to adopt ruff for the first time and I'd like to configure pyproject.toml in a future-proof fashion.

If I correctly understood, according to #8449:

• linter-specific configurations will be nested under [tool.ruff.lint]
• top-level lint options will be deprecated as consequence of Add lint section to Ruff configuration #7549, thus requiring them to be nested under [tool.ruff.lint] as well.

This said, I'm probably misunderstanding what is meant for top-level lint options. I was supposing them to be the ones listed in https://docs.astral.sh/ruff/settings/#top-level, but the following

[tool.ruff]
...
[tool.ruff.lint]
select = [
  # default
  "E",      # pycodestyle error
  "F",      # flake8 error
  # extra
  "A",      # builtin shadowing
  "B",      # flake8 bugbear
  "BLE",    # aboid bare excepts
  "C4",     # simplify comprehensions
  "DTZ",    # datetime errors
  "FBT",    # avoid boolean trap
  "G",      # logging format
  "I",      # isort imports
  "N",      # conform to PEP8 naming rules
  "RET",    # return values
  "S",      # bandit
  "TRY",    # exceptions antipatterns
  "UP",     # upgade syntax
  "W",      # pycodestyle warning
  "YTT",    # wrong usage of sys.info
]
show-source = true

makes ruff fail with

Cause: TOML parse error at line 66, column 1
 |
 | [tool.ruff.lint]
 | ^^^^^^^^^^^^^^^^^
unknown field `show-source`

while moving show-source = true below [tool.ruff] makes it work as per documentation in https://docs.astral.sh/ruff/settings/#show-source.

So, wrapping up, I'm wondering whether someone could shed some light on what top level lint options are. Perhaps [per_file_ignores, select, ignore, flake8_annotations, flake8_bugbear, flake8_builtins, flake8_errmsg, flake8_pytest_style, flake8_tidy_imports, mccabe, pep8_naming, pydocstyle] as per the changes made to crates/flake8_to_ruff/src/converter.rs in #7549?

Hope the doubt has some sense, I'm still a beginner!
Thank you in advance:)

[zanieb]

Hi! Glad to see you're using Ruff :)

I think most of the confusion is that we have some future plans that aren't covered in the documentation. For example, show-source is an option for the ruff check command which is not quite specific to the linter (see #8232). Additionally, we're planning on removing that options entirely in the future (see #4189). So there are a couple reasons that option wasn't moved.

We expect some options to remain at the top-level as well as at the lint level, such as file selection options (e.g. include) or options that apply to both the linter and formatter (e.g. line_length).

I hope this helps! Feel free to ask more questions. There should be deprecation warnings for anything that's changing before it breaks. We're a fast moving young project so I don't expect there to be any perfectly future-proof configuration.

[charliermarsh]

Yeah, the docs aren't up-to-date on this unfortunately -- we're working on it! It's very reasonable to just keep putting everything in the top-level (under [tool.ruff]) for now to avoid confusion.

If you're looking for guidance, though, you can put everything under [tool.ruff.lint] except settings that apply to both tools (most commonly: target-version, preview, line-length).

So per-file-ignores, select, etc., which only apply to the linter, and not the formatter, would go under [tool.ruff.lint].