Skip to content

fix: read rest-section-adorns from the configuration file - #373

Open
Eljees wants to merge 1 commit into
PyCQA:masterfrom
Eljees:fix/rest-section-adorns-config-key
Open

fix: read rest-section-adorns from the configuration file#373
Eljees wants to merge 1 commit into
PyCQA:masterfrom
Eljees:fix/rest-section-adorns-config-key

Conversation

@Eljees

@Eljees Eljees commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Problem

Every option is read back from the configuration file under its own hyphenated
command line name — in-place, wrap-summaries, pre-summary-space, non-cap
and the rest. --rest-section-adorns is the single exception: configuration.py
reads it as rest_section_adorns, with underscores.

docs/source/configuration.rst documents the hyphenated spelling:

The user can override this default list of characters by passing a regex from the
command line or setting the rest-section-adorns option in the configuration file.

So the spelling the documentation asks for is exactly the one that gets dropped —
silently. No error, no warning; the run just uses the default adornment regex.

Reproducer

# pyproject.toml
[tool.docformatter]
rest-section-adorns = "[!]{4,}"
>>> c = Configurater(["docformatter", "--config", "pyproject.toml", "x.py"])
>>> c.do_parse_arguments()
>>> c.flargs
{'rest-section-adorns': '[!]{4,}'}          # the file was parsed fine
>>> c.args.rest_section_adorns
'[!\\"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~]{4,}'  # ... and the value never arrives

Switching the key to rest_section_adorns in the same file makes it work, but that
spelling is not documented anywhere.

Why this looks like a typo rather than a convention

Mechanically comparing, for each add_argument block, the long option name against
the key it is read from gives one mismatch out of twenty-one:

--in-place                in-place                ok
--check                   check                   ok
...
--rest-section-adorns     rest_section_adorns     <-- mismatch
--wrap-summaries          wrap-summaries          ok
--wrap-descriptions       wrap-descriptions       ok
...

Fix

Read the documented hyphenated key first and keep the underscored one as a fallback,
so anyone who found the undocumented spelling by reading the source keeps working.

No documentation change is needed — the docs were already right.

Tests

TestRestSectionAdornsConfigKey in tests/test_configuration_functions.py, five cases:

test before after
test_hyphenated_key_is_honored fails passes
test_hyphenated_key_wins_over_underscored_key fails passes
test_underscored_key_is_still_honored passes passes
test_default_is_used_when_key_is_absent passes passes
test_command_line_overrides_the_configuration_file passes passes

The last three are controls: they are green before and after, which is what shows the
change is additive rather than a behaviour swap.

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 556 passed, 3 skipped (551 + the 5 new)
new failures against master none
source reverted, new tests kept 2 failed / 3 passed — the two that should fail
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 no existing test lines are touched — the test diff is
additions only.

Every command line option is read back from pyproject.toml / setup.cfg /
tox.ini under its own hyphenated name -- in-place, wrap-summaries,
pre-summary-space and so on. --rest-section-adorns is the one exception:
it is read under rest_section_adorns, with underscores.

docs/source/configuration.rst tells the user to set the
``rest-section-adorns`` option in the configuration file, so the spelling
the documentation asks for is the spelling that gets dropped. The file is
parsed correctly and the key does land in flargs; it is lost on the way to
the argument default, which makes it silent -- no error, no warning, just
the default adornment regex.

Read the documented hyphenated key first and keep the underscored one as a
fallback, so anyone who found the undocumented spelling by reading the
source keeps working.
@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, and this branch touches none of the three. The six test jobs (3.10 through 3.14 and pypy3.9) are green.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant