Skip to content

Preserve Click no-wrap paragraphs in docstrings - #395

Merged
weibullguy merged 1 commit into
PyCQA:masterfrom
jihtsan:codex/291-preserve-click-paragraphs
Oct 16, 2026
Merged

weibullguy merged 1 commit into
PyCQA:masterfrom
jihtsan:codex/291-preserve-click-paragraphs

Conversation

@jihtsan

@jihtsan jihtsan commented Oct 16, 2026

Copy link
Copy Markdown
Contributor

Click uses a standalone \b line to preserve a paragraph in command help. Formatting currently joins that marker with the next line, so Click rewraps the paragraph and can split manually arranged text or URLs.

Preserve paragraphs beginning with that marker, including a marker at the start of the docstring, while continuing to wrap surrounding prose. Keep explicit --force-wrap behavior. Cover literal and actual backspace markers, indentation, long URLs, adjacent paragraphs, negative cases and formatter idempotence.

Fixes #291.

Validation on macOS:

  • New regression cases on unchanged base: 13 failed, 3 passed; all 16 pass with this change.
  • Python 3.10.21: full suite 640 passed, 4 skipped.
  • Python 3.14.6: full suite 641 passed, 3 skipped.
  • Ruff 0.15.11, Black 26.3.1 (under Python 3.14), isort 8.0.1, mypy 1.20.1 and pydocstyle 6.3.0 pass on the affected files.
  • Actual Click 8.5.0 CliRunner help output is unchanged in four before/after scenarios, covering the original example and a first-paragraph marker, each with and without a long URL.

Commands: VIRTUAL_ENV=<venv> PATH=<venv>/bin:$PATH python -m pytest -q; targeted tests in tests/wrappers/test_description_wrapper.py and tests/formatter/test_do_format_code.py; python -m ruff check, python -m black --check, python -m isort --check-only, python -m mypy, python -m pydocstyle on the affected files. The two full Python suites were run serially because existing fixtures share a fixed temporary configuration path; an initial concurrent run interfered with that fixture, and the serial rerun passed.

Linux, Windows, PyPy and Python 3.11–3.13 were not executed locally. AI-assisted implementation and review; the runtime behavior and checks above were executed against this commit.

@weibullguy
weibullguy merged commit f4c46e3 into PyCQA:master Oct 16, 2026
7 checks passed
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.

Unexpected interaction with click rewrapping

2 participants