Add order_by_qualified_sort option

Add support for hackings preferred sort order. Instead of

  from foo import baz
  from foo.bar import wow

order by fully qualified paths:

  from foo.bar import wow
  from foo import baz

Signed-off-by: Stephen Finucane <stephen@that.guru>

Author: stephenfin

docs/configuration/options.md

@@ -803,6 +803,16 @@ Order imports by type, which is determined by case, in addition to alphabeticall
 - --ot
 - --order-by-type
 
+## Order By Qualified Name
+
+Order imports by their full module path. That is, `from foo.bar import wow` would be ordered before `from foo import baz` (since `foo.bar.wow` < `foo.baz`).
+
+**Type:** Bool  
+**Default:** `False`  
+**Config default:** `false`  
+**Python & Config File Name:** order_by_qualified_name  
+**CLI Flags:** **Not Supported**
+
 ## Atomic
 
 Ensures the output doesn't save if the resulting file contains syntax errors.

isort/output.py

@@ -66,7 +66,13 @@ def sorted_imports(
             from_modules = sorting.sort(
                 config,
                 from_modules,
-                key=lambda key: sorting.module_key(key, config, section_name=section),
+                key=lambda key: sorting.module_key(
+                    f"{key}.{min(from_modules[key])}"
+                    if config.order_by_qualified_name and from_modules[key]
+                    else key,
+                    config,
+                    section_name=section,
+                ),
                 reverse=config.reverse_sort,
             )
 

isort/settings.py

@@ -173,6 +173,7 @@ class _Config:
     balanced_wrapping: bool = False
     use_parentheses: bool = False
     order_by_type: bool = True
+    order_by_qualified_name: bool = False
     atomic: bool = False
     lines_before_imports: int = -1
     lines_after_imports: int = -1

tests/unit/test_isort.py

@@ -1676,6 +1676,29 @@ def test_order_by_type() -> None:
     )
 
 
+def test_order_by_qualified_name() -> None:
+    # Without option: sorted by module name ("foo" < "foo.bar")
+    test_input = "from foo.bar import wow\nfrom foo import baz\n"
+    assert isort.code(test_input, order_by_qualified_name=False) == (
+        "from foo import baz\nfrom foo.bar import wow\n"
+    )
+    # With option: sorted by fully qualified path ("foo.bar.wow" < "foo.baz")
+    assert isort.code(test_input, order_by_qualified_name=True) == (
+        "from foo.bar import wow\nfrom foo import baz\n"
+    )
+    # Multiple imports from the same module use the first alphabetically
+    test_input = "from foo import zebra\nfrom foo.bar import wow\n"
+    assert isort.code(test_input, order_by_qualified_name=True) == (
+        "from foo.bar import wow\nfrom foo import zebra\n"
+    )
+    # Multiple imports on one line: key uses the first import name alphabetically
+    # "from foo import qux, zebra" -> key "foo.qux" > "foo.bar.wow"
+    test_input = "from foo import qux, zebra\nfrom foo.bar import wow\n"
+    assert isort.code(test_input, order_by_qualified_name=True) == (
+        "from foo.bar import wow\nfrom foo import qux, zebra\n"
+    )
+
+
 @pytest.mark.parametrize("has_body", [True, False])
 def test_custom_lines_before_import_section(has_body: bool) -> None:
     """Test the case where the number of lines to output before imports has been explicitly set."""