Merge pull request #1818 from sgaist/issue/1646

feature: implement lines before imports

docs/configuration/options.md

@@ -491,6 +491,18 @@ Ensures the output doesn't save if the resulting file contains syntax errors.
 - --ac
 - --atomic
 
+## Lines Before Imports
+
+How many lines to add before an import section
+
+**Type:** Int
+**Default:** `-1`
+**Python & Config File Name:** lines_before_imports
+**CLI Flags:**
+
+- --lbi
+- --lines-before-imports
+
 ## Lines After Imports
 
 **No Description**

isort/main.py

@@ -484,6 +484,9 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         dest="indent",
         type=str,
     )
+    output_group.add_argument(
+        "--lbi", "--lines-before-imports", dest="lines_before_imports", type=int
+    )
     output_group.add_argument(
         "--lai", "--lines-after-imports", dest="lines_after_imports", type=int
     )

isort/output.py

@@ -217,6 +217,9 @@ def sorted_imports(
             else:
                 formatted_output[imports_tail:0] = [""]
 
+            if config.lines_before_imports != -1:
+                formatted_output[:0] = ["" for line in range(config.lines_before_imports)]
+
     if parsed.place_imports:
         new_out_lines = []
         for index, line in enumerate(formatted_output):

isort/settings.py

@@ -179,6 +179,7 @@ class _Config:
     use_parentheses: bool = False
     order_by_type: bool = True
     atomic: bool = False
+    lines_before_imports: int = -1
     lines_after_imports: int = -1
     lines_between_sections: int = 1
     lines_between_types: int = 0

tests/integration/test_hypothesmith.py

@@ -40,6 +40,7 @@ def configs(**force_strategies: st.SearchStrategy) -> st.SearchStrategy[isort.Co
         "sections",
         "known_future_library",
         "forced_separate",
+        "lines_before_imports",
         "lines_after_imports",
         "lines_between_sections",
         "lines_between_types",

tests/integration/test_setting_combinations.py

@@ -29,6 +29,7 @@ def configs() -> st.SearchStrategy[isort.Config]:
         "known_local_folder",
         "extra_standard_library",
         "forced_separate",
+        "lines_before_imports",
         "lines_after_imports",
         "add_imports",
         "lines_between_sections",
@@ -558,6 +559,7 @@ def _raise(*a):
         use_parentheses=True,
         order_by_type=True,
         atomic=False,
+        lines_before_imports=-1,
         lines_after_imports=-1,
         lines_between_sections=1,
         lines_between_types=0,
@@ -865,6 +867,7 @@ def _raise(*a):
                 "use_parentheses": False,
                 "order_by_type": True,
                 "atomic": False,
+                "lines_before_imports": -1,
                 "lines_after_imports": -1,
                 "lines_between_sections": 1,
                 "lines_between_types": 0,
@@ -1421,6 +1424,7 @@ def test_isort_is_idempotent(config: isort.Config, disregard_skip: bool) -> None
         use_parentheses=True,
         order_by_type=True,
         atomic=False,
+        lines_before_imports=-1,
         lines_after_imports=-1,
         lines_between_sections=1,
         lines_between_types=0,
@@ -1728,6 +1732,7 @@ def test_isort_is_idempotent(config: isort.Config, disregard_skip: bool) -> None
                 "use_parentheses": False,
                 "order_by_type": True,
                 "atomic": False,
+                "lines_before_imports": -1,
                 "lines_after_imports": -1,
                 "lines_between_sections": 1,
                 "lines_between_types": 0,

tests/unit/test_isort.py

@@ -1630,6 +1630,19 @@ def test_order_by_type() -> None:
     )
 
 
+def test_custom_lines_before_import_section() -> None:
+    """Test the case where the number of lines to output after imports has been explicitly set."""
+    test_input = "from a import b\nfrom c import d\nfoo = 'bar'\n"
+
+    # default case is no line added before the import
+    assert isort.code(test_input) == ("from a import b\nfrom c import d\n\nfoo = 'bar'\n")
+
+    # test again with a custom number of lines before the import section
+    assert isort.code(test_input, lines_before_imports=2) == (
+        "\n\nfrom a import b\nfrom c import d\n\nfoo = 'bar'\n"
+    )
+
+
 def test_custom_lines_after_import_section() -> None:
     """Test the case where the number of lines to output after imports has been explicitly set."""
     test_input = "from a import b\nfoo = 'bar'\n"