Implemented PyCQA#727: Ability to only add imports if existing import…

…s exist.

CHANGELOG.md

@@ -8,6 +8,7 @@ NOTE: isort follows the [semver](https://semver.org/) versioning standard.
   - Implemented #1331: Warn when sections don't match up.
   - Implemented #1261: By popular demand, `filter_files` can now be set in the config option.
   - Implemented #960: Support for respecting git ignore via "--gitignore" or "skip_gitignore=True".
+  - Implemented #727: Ability to only add imports if existing imports exist.
   - `# isort: split` can now be used at the end of an import line.
   - Fixed #1339: Extra indent is not preserved when isort:skip is used in nested imports.
 

docs/configuration/options.md

@@ -315,6 +315,18 @@ Removes the specified import from all files.
 - --rm
 - --remove-import
 
+## Append Only
+
+Only adds the imports specified in --add-imports if the file contains existing imports.
+
+**Type:** Bool  
+**Default:** `False`  
+**Python & Config File Name:** append_only  
+**CLI Flags:**
+
+- --append
+- --append-only
+
 ## Reverse Relative
 
 Reverse order of relative imports.
@@ -386,7 +398,7 @@ Balances wrapping to produce the most consistent line length possible
 
 ## Use Parentheses
 
-Use parentheses for line continuation on length limit instead of slashes. **NOTE**: This is separate from wrap modes, and only affects individual line to long wrapping, not sections of multiple imports.
+Use parentheses for line continuation on length limit instead of slashes. **NOTE**: This is separate from wrap modes, and only affects how individual lines that  are too long get continued, not sections of multiple imports.
 
 **Type:** Bool  
 **Default:** `False`  

isort/api.py

@@ -522,7 +522,7 @@ def _sort_imports(
                     import_section += line
                     indent = line[: -len(line.lstrip())]
                 elif not (stripped_line or contains_imports):
-                    if add_imports and not indent:
+                    if add_imports and not indent and not config.append_only:
                         if not import_section:
                             output_stream.write(line)
                             line = ""
@@ -586,6 +586,7 @@ def _sort_imports(
             raw_import_section: str = import_section
             if (
                 add_imports
+                and not config.append_only
                 and not in_top_comment
                 and not in_quote
                 and not import_section

isort/main.py

@@ -154,6 +154,14 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         help="Adds the specified import line to all files, "
         "automatically determining correct placement.",
     )
+    parser.add_argument(
+        "--append",
+        "--append-only",
+        dest="append_only",
+        action="store_true",
+        help="Only adds the imports specified in --add-imports if the file"
+        " contains existing imports.",
+    )
     parser.add_argument(
         "--ac",
         "--atomic",

isort/settings.py

@@ -130,6 +130,7 @@ class _Config:
     length_sort_sections: FrozenSet[str] = frozenset()
     add_imports: FrozenSet[str] = frozenset()
     remove_imports: FrozenSet[str] = frozenset()
+    append_only: bool = False
     reverse_relative: bool = False
     force_single_line: bool = False
     single_line_exclusions: Tuple[str, ...] = ()

tests/test_ticketed_features.py

@@ -198,3 +198,17 @@ def test_isort_warns_when_known_sections_dont_match_issue_1331():
             )
             == "THIRDPARTY"
         )
+
+
+def test_isort_supports_append_only_imports_727():
+    """Test to ensure isort provides a way to only add imports as an append.
+    See: https://github.com/timothycrosley/isort/issues/727.
+    """
+    assert isort.code("", add_imports=["from __future__ import absolute_imports"]) == ""
+    assert (
+        isort.code("import os", add_imports=["from __future__ import absolute_imports"])
+        == """from __future__ import absolute_imports
+
+import os
+"""
+    )