bug/surprise: adding an empty ruff.toml affects how import rules behaves

[kaddkaka]

Adding an ruff.toml to your project file structure affects how ruff finds and categorizes imports, and therefore how rule I001 behaves.

version: ruff 0.7.4

Detailed description

Without ruff.toml

Project structure:

$ tree
.
├── proj
│   ├── lib
│   │   └── bar.py
│   └── src
│       └── foo.py
└── pyproject.toml

File content:

File: proj/lib/bar.py


File: proj/src/foo.py
import banana
import lib.bar
import itertools

File: pyproject.toml
[tool.ruff]

Here lib.bar is identified as 'lib.bar' as Known(ThirdParty)

$ ruff check --select I -v --no-cache proj/src/foo.py
[2024-11-20][20:25:48][ruff::resolve][DEBUG] Using configuration file (via parent) at: /home/david/projects/bugreport_ruff_toml_dir/pyproject.toml
[2024-11-20][20:25:48][ruff::commands::check][DEBUG] Identified files to lint in: 4.268338ms
[2024-11-20][20:25:48][ruff::diagnostics][DEBUG] Checking: /home/david/projects/bugreport_ruff_toml_dir/proj/src/foo.py
[2024-11-20][20:25:48][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'banana' as Known(ThirdParty) (NoMatch)
[2024-11-20][20:25:48][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'lib.bar' as Known(ThirdParty) (NoMatch)
[2024-11-20][20:25:48][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'itertools' as Known(StandardLibrary) (KnownStandardLibrary)
[2024-11-20][20:25:48][ruff::commands::check][DEBUG] Checked 1 files in: 1.303531ms
proj/src/foo.py:1:1: I001 [*] Import block is un-sorted or un-formatted
  |
1 | / import banana
2 | | import lib.bar
3 | | import itertools
  |
  = help: Organize imports

Found 1 error.
[*] 1 fixable with the `--fix` option.

$ ruff check --select I --fix --no-cache proj/src/foo.py ; git diff
Found 1 error (1 fixed, 0 remaining).
diff --git a/proj/src/foo.py b/proj/src/foo.py
index 11710ea..ad0a354 100644
--- a/proj/src/foo.py
+++ b/proj/src/foo.py
@@ -1,3 +1,4 @@
+import itertools
+
 import banana
 import lib.bar
-import itertools

With an empty ruff.toml

$ touch proj/ruff.toml
$ tree
.
├── proj
│   ├── lib
│   │   └── bar.py
│   ├── ruff.toml
│   └── src
│       └── foo.py
└── pyproject.toml

Here the lib.bar import is identified as 'lib.bar' as Known(FirstParty)

$ ruff check --select I -v --no-cache proj/src/foo.py
[2024-11-20][20:28:25][ruff::resolve][DEBUG] Using configuration file (via parent) at: /home/david/projects/bugreport_ruff_toml_dir/pyproject.toml
[2024-11-20][20:28:25][ruff_workspace::pyproject][DEBUG] `project.requires_python` in `pyproject.toml` will not be used to set `target_version` when using `ruff.toml`.
[2024-11-20][20:28:25][ruff::commands::check][DEBUG] Identified files to lint in: 5.248828ms
[2024-11-20][20:28:25][ruff::diagnostics][DEBUG] Checking: /home/david/projects/bugreport_ruff_toml_dir/proj/src/foo.py
[2024-11-20][20:28:25][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'banana' as Known(ThirdParty) (NoMatch)
[2024-11-20][20:28:25][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'lib.bar' as Known(FirstParty) (SourceMatch("/home/david/projects/bugreport_ruff_toml_dir/proj"))
[2024-11-20][20:28:25][ruff_linter::rules::isort::categorize][DEBUG] Categorized 'itertools' as Known(StandardLibrary) (KnownStandardLibrary)
[2024-11-20][20:28:25][ruff::commands::check][DEBUG] Checked 1 files in: 1.36171ms
proj/src/foo.py:1:1: I001 [*] Import block is un-sorted or un-formatted
  |
1 | / import banana
2 | | import lib.bar
3 | | import itertools
  |
  = help: Organize imports

Found 1 error.
[*] 1 fixable with the `--fix` option.

$ ruff check --select I --fix --no-cache proj/src/foo.py ; git diff
Found 1 error (1 fixed, 0 remaining).
diff --git a/proj/src/foo.py b/proj/src/foo.py
index 11710ea..9b3f53b 100644
--- a/proj/src/foo.py
+++ b/proj/src/foo.py
@@ -1,3 +1,5 @@
+import itertools
+
 import banana
+
 import lib.bar
-import itertools

Additional wishes

This issue would have been easier to debug if ruff check -v also listed:

• which ruff.toml has been visitted
• which pyproject.toml has been visitted (even though ignore due to missing ruff section)

[kaddkaka]

Similar issue:

• Whether an import is treated as ThirdParty or FirstParty depends on whether the SAME config file is explicitly specified or implicitly discovered #14036
• Folder with module name detected as source leads to false I001 error #10519
• No way to exclude folders from first-party detection for import sorting? #9130
• isort counts third party imports as local when inside submodules with the same name #10266

[MichaReiser]

Thanks for your feedback on your ruff experience. I can see how this can be surprising. The behavior is intentional (not speaking about the linked issue) but probably hard to find. It is explained in the documentation of the src setting.

You can explicitly set the src setting to exclude the lib folder.

[kaddkaka]

So if I don't want this automatic behavior, what's my option?

[tool.ruff]
src = []

?

[kaddkaka]

And what about

ruff check -v should list:

• which ruff.toml has been visitted
• which pyproject.toml has been visitted (even though ignore due to missing ruff section)

Propose in separate issue?

[kaddkaka]

Or for a more complex file structure, what to do? Which folders should be marked as src folders?

$ tree
.
├── proj
│   ├── lib
│   │   └── bar.py
│   ├── src
│   │   └── foo.py
│   ├── test_suite_unittests
│   │   └── test_bar
│   │       └── test_unittets.py
│   └── test_suite_integration
│       └── test_bar
│           └── test_integration_with_X.py
├── tools
│   ├── Banana
│   │   ├── test
│   │   │   └── main.py
│   │   └── main.py
│   ├── Mango
│   │   └── main.py
│   └── Potato
│       └── main.py
└── pyproject.toml