Implemented #1433: Provide helpful feedback in case a custom config f…

…ile is specified without a configuration.

CHANGELOG.md

@@ -5,6 +5,7 @@ NOTE: isort follows the [semver](https://semver.org/) versioning standard.
 Find out more about isort's release policy [here](https://pycqa.github.io/isort/docs/major_releases/release_policy/).
 
 ### 5.6.0 TBD
+  - Implemented #1433: Provide helpful feedback in case a custom config file is specified without a configuration.
   - Fixed #1463: Better interactive documentation for future option.
   - Fixed #1461: Quiet config option not respected by file API in some circumstances.
 

docs/configuration/config_files.md

@@ -75,3 +75,12 @@ indent_size = 4
 skip = build,.tox,venv
 src_paths=isort,test
 ```
+
+## Custom config files
+
+Optionally, you can also create a config file with a custom name, or directly point isort to a config file that falls lower in the priority order, by using [--settings-file](https://pycqa.github.io/isort/docs/configuration/options/#settings-path).
+This can be useful, for instance, if you want to have one configuration for `.py` files and another for `.pyx` - while keeping the config files at the root of your repository.
+
+!!! tip
+    Custom config files should place their configuration options inside an `[isort]` section and never a generic `[settings]` section. This is because isort can't know for sure
+    how other tools are utilizing the config file.

isort/settings.py

@@ -269,6 +269,14 @@ def __init__(
                 CONFIG_SECTIONS.get(os.path.basename(settings_file), FALLBACK_CONFIG_SECTIONS),
             )
             project_root = os.path.dirname(settings_file)
+            if not config_settings:
+                warn(
+                    f"A custom settings file was specified: {settings_file} but no configuration "
+                    "was found inside. This can happen when [settings] is used as the config "
+                    "header instead of [isort]. "
+                    "See: https://pycqa.github.io/isort/docs/configuration/config_files"
+                    "/#custom_config_files for more information."
+                )
         elif settings_path:
             if not os.path.exists(settings_path):
                 raise InvalidSettingsPath(settings_path)

tests/unit/test_ticketed_features.py

@@ -719,3 +719,30 @@ def test_isort_respects_quiet_from_sort_file_api_see_1461(capsys, tmpdir):
     out, error = capsys.readouterr()
     assert not error
     assert not out
+
+
+def test_isort_should_warn_on_empty_custom_config_issue_1433(tmpdir):
+    """Feedback should be provided when a user provides a custom settings file that has no
+    discoverable configuration.
+    See: https://github.com/PyCQA/isort/issues/1433
+    """
+    settings_file = tmpdir.join(".custom.cfg")
+    settings_file.write(
+        """
+[settings]
+quiet = true
+"""
+    )
+    with pytest.warns(UserWarning):
+        assert not Config(settings_file=str(settings_file)).quiet
+
+    isort.settings._get_config_data.cache_clear()
+    settings_file.write(
+        """
+[isort]
+quiet = true
+"""
+    )
+    with pytest.warns(None) as warning:
+        assert Config(settings_file=str(settings_file)).quiet
+    assert not warning