Skip to content

fix: say when a config file is skipped for lack of TOML support - #374

Open
Eljees wants to merge 1 commit into
PyCQA:masterfrom
Eljees:fix/268-say-when-toml-support-is-missing
Open

fix: say when a config file is skipped for lack of TOML support#374
Eljees wants to merge 1 commit into
PyCQA:masterfrom
Eljees:fix/268-say-when-toml-support-is-missing

Conversation

@Eljees

@Eljees Eljees commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Closes #268.

What is left of #268

#371 fixed the crash half of this: with neither tomllib nor the tomli backport
importable, _do_read_toml_configuration used to blow up with NameError, and it now
returns early instead. That closed #368.

The complaint in #268 is the other half, and it is still exact — the early return is
completely silent:

if tomllib is None:
    # ... skip reading TOML configuration rather than crashing ... See #368.
    return

A pyproject.toml is ignored without a word, including one passed explicitly with
--config. From the outside the run simply reformats differently than asked, which is
what the reporter described: "it does not read the configuration from the config file,
simply omits it even if it's explicitly specified."

This is reachable on a supported configuration

  • pyproject.toml declares python = "^3.10"
  • tomli is an optional extra: tomli = {version = "^2.0.0", python = "<3.11", optional = true}
  • the CI matrix in ci.yml still runs 3.10 and pypy3.9, both below 3.11

So a plain pip install docformatter on Python 3.10 reads no TOML configuration at all,
and says nothing about it.

Fix

One line to stderr naming the file that was not read, and how to get TOML support.
The behaviour itself is unchanged — the settings are still skipped. Whether they should
instead be honoured some other way is a separate question and not something I wanted to
decide inside a bug fix.

There is an alternative worth mentioning: making tomli a required dependency for
python < 3.11 is a one-line change in pyproject.toml and would remove the situation
entirely. I did not do that because it changes the dependency graph for every user, which
felt like your call rather than mine. Happy to switch to that instead if you prefer it.

Tests

TestMissingTomlSupport in tests/test_configuration_functions.py:

test before after
test_says_so_when_toml_support_is_missing fails (stderr is empty) passes
test_stays_quiet_when_toml_support_is_present passes passes

The second is the control — on the happy path stderr has to stay empty, and it does, both
before and after.

Verification

Run in a clean venv with the dependency set from [testenv] in tox.ini:

result
master (d5c7b77), whole suite 551 passed, 3 skipped
this branch, whole suite 553 passed, 3 skipped (551 + the 2 new)
new failures against master none
black --check, isort --check on the changed source clean
docformatter --check --config ./pyproject.toml on its own source exit 0

tests/ is excluded in .pre-commit-config.yaml, so the added test block was formatted
on its own and the test diff is additions only.

…A#268)

PyCQA#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 PyCQA#368. What is left is PyCQA#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.
@Eljees

Eljees commented Aug 15, 2026

Copy link
Copy Markdown
Contributor Author

Flagging one thing so the red check is not read as mine: Run linters on code base fails here, and it fails on master at d5c7b77 with the same three hooks and the same messages —

  • fix end of files rewriting CHANGELOG.md
  • pydocstyle D301 on src/docformatter/classify.py:481
  • mypy [assignment] on src/docformatter/configuration.py:46

I pulled both job logs and diffed them; the failing set is identical. The six test jobs (3.10 through 3.14 and pypy3.9) are green.

The mypy one is worth a word since it sits in the file this PR edits: line 46 is the tomllib = None fallback from #371, and mypy objects to assigning None to something it has already inferred as a module. It is red on master today, so I left it alone. If you would like it cleared in the same pass, the usual shape is

tomllib: ModuleType | None = None

with from types import ModuleType — say the word and I will add it here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant