From d0051accd63aa562453b362e9ddcfd04e9e42704 Mon Sep 17 00:00:00 2001
From: Eljees <57435526+Eljees@users.noreply.github.com>
Date: Sat, 15 Aug 2026 23:31:03 +0300
Subject: [PATCH] fix: say when a config file is skipped for lack of TOML
 support (#268)

#371 stopped docformatter crashing with a NameError when neither tomllib
nor the tomli backport is importable, by returning early from
_do_read_toml_configuration. That fixed #368. What is left is #268: the
early return is completely silent, so a pyproject.toml -- including one
passed explicitly with --config -- is ignored without a word, and the run
looks like it simply chose to reformat differently.

This is reachable on a supported configuration. pyproject.toml declares
python = "^3.10", tomli is an optional extra for python < 3.11, and the CI
matrix still runs 3.10 and pypy3.9. A plain `pip install docformatter` on
3.10 therefore reads no TOML configuration at all.

Print one line to stderr naming the file that was not read and how to get
TOML support, and leave the behaviour itself alone -- whether the settings
should be honoured some other way is a separate question.
---
 src/docformatter/configuration.py     |  9 ++++-
 tests/test_configuration_functions.py | 48 +++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/src/docformatter/configuration.py b/src/docformatter/configuration.py
index 3fe45ee..fe6c74d 100644
--- a/src/docformatter/configuration.py
+++ b/src/docformatter/configuration.py
@@ -346,7 +346,14 @@ def _do_read_toml_configuration(self) -> None:
         if tomllib is None:
             # tomli/tomllib is not installed (Python < 3.11 without the tomli
             # backport); skip reading TOML configuration rather than crashing
-            # with a NameError. See #368.
+            # with a NameError, but say so instead of silently ignoring the
+            # user's settings. See #268 and #368.
+            print(
+                f"docformatter: {self.config_file} was not read because TOML "
+                "support is missing; on Python < 3.11 this needs the tomli "
+                'package: pip install "docformatter[tomli]"',
+                file=sys.stderr,
+            )
             return
         with open(self.config_file, "rb") as f:
             config = tomllib.load(f)
diff --git a/tests/test_configuration_functions.py b/tests/test_configuration_functions.py
index 0c63c39..e6740d0 100644
--- a/tests/test_configuration_functions.py
+++ b/tests/test_configuration_functions.py
@@ -699,3 +699,51 @@ def test_non_cap_from_setup_cfg(
             "diff": "true",
             "non-cap": '["qBittorrent", "iPad", "iOS", "eBay"]',
         }
+class TestMissingTomlSupport:
+    """Class for testing behaviour when no TOML parser is installed.
+
+    On Python < 3.11 the tomli backport is an optional extra, so a plain
+    ``pip install docformatter`` leaves docformatter unable to read
+    pyproject.toml.  Issue #268 is that this happens without a word.
+    """
+
+    @pytest.mark.unit
+    def test_says_so_when_toml_support_is_missing(self, tmp_path, capsys):
+        """Warn on stderr instead of silently dropping the settings."""
+        # Third Party Imports
+        import docformatter.configuration as configuration
+
+        config_file = tmp_path / "pyproject.toml"
+        config_file.write_text(
+            '[tool.docformatter]\nwrap-summaries = "120"\n', encoding="utf-8"
+        )
+
+        saved = configuration.tomllib
+        configuration.tomllib = None
+        try:
+            uut = Configurater(
+                ["/path/to/docformatter", "--config", str(config_file), ""]
+            )
+            uut.do_parse_arguments()
+        finally:
+            configuration.tomllib = saved
+
+        stderr = capsys.readouterr().err
+        assert str(config_file) in stderr
+        assert "tomli" in stderr
+        # The settings are still dropped; that part is by design (#368).
+        assert uut.args.wrap_summaries == 79
+
+    @pytest.mark.unit
+    def test_stays_quiet_when_toml_support_is_present(self, tmp_path, capsys):
+        """Say nothing on the happy path."""
+        config_file = tmp_path / "pyproject.toml"
+        config_file.write_text(
+            '[tool.docformatter]\nwrap-summaries = "120"\n', encoding="utf-8"
+        )
+
+        uut = Configurater(["/path/to/docformatter", "--config", str(config_file), ""])
+        uut.do_parse_arguments()
+
+        assert capsys.readouterr().err == ""
+        assert uut.args.wrap_summaries == 120