[RonnyPfannschmidt]

AI-authored. I asked an agent (Claude Opus 5 via Claude Code) to look into
the help-text wrapping after reviewing #15021. The investigation, the
comparisons against other libraries, the patch, the tests and this text are
its work. I read it and I'm posting it.

Supersedes #15021, which fixes a narrower symptom on top of a base that is
itself wrong.

Background

87423d3 (#6817, @blueyed) taught the help formatter to keep explicit line
breaks, so that a help text can be written as a list instead of being reflowed
into one blob. It did that by splitting on newlines and wrapping each line
separately. That commit's own message names the cost:

This might also result in unexpected changes (hard wrapping), when line
endings where used unintentionally, e.g. with:

help="""
    some long
    help text
    """

The line.strip() in _split_lines is what holds that back. It works, but it
cannot distinguish source indentation from indentation that carries meaning, so
it flattens both:

control the thing                       control the thing
  * fast: skip the expensive...    →    * fast: skip the expensive validation
  * slow: run every check...            pass entirely and hope for the best

A wrapped item is now indistinguishable from a new one. Blank lines vanish too,
since textwrap.wrap("") returns no lines — that is the symptom #15021 reports.

The other half

There are two independent wrapping implementations. helpconfig.showhelp()
passes the whole help text to textwrap.wrap, so newlines degrade to ordinary
whitespace and the structure is lost completely. pytest's own ini option:

  parametrize_long_str_id_strategy (string):
                        strategy for long str/bytes parameter values in
                        auto-generated ids - short (default): values over 100
                        chars fall back to argname+index - sha256: replace value
                        with its sha256 hex digest - legacy: keep the full value
                        (for temporary backward compatibility) - disallow: raise
                        an error requesting explicit ids

Core has exactly one CLI option (--assert) and one ini option (that one) with
newlines in their help, so this path is where the only currently visible
breakage is.

This change

textwrap.dedent is the right tool for what strip() was reaching for: it
removes exactly the common source indentation, and keeps what is relative to it.
Each line then wraps carrying its own indent, and a list item's continuation
lines hang under the item's text. Both call sites share one _split_help_text,
so the ini path stops rotting separately.

  parametrize_long_str_id_strategy (string):
                        strategy for long str/bytes parameter values in
                        auto-generated ids
                        - short (default): values over 100 chars fall back to
                          argname+index
                        - sha256: replace value with its sha256 hex digest
                        - legacy: keep the full value (for temporary backward
                          compatibility)
                        - disallow: raise an error requesting explicit ids

Details worth a reviewer's eye:

• The first line is stripped rather than dedented. It usually sits inline after
  the opening quotes, so it contributes no common prefix and plain dedent on
  the whole text would find "" and do nothing.
• Blank lines are kept but trimmed at both ends, where they would only offset
  the text from the option it documents.
• _format_action strips trailing whitespace, because argparse pads a blank
  help line out to the help column.
• break_on_hyphens=False matches what showhelp already passed, and stops
  auto-generated splitting mid-word.

On reusing something instead

Checked, none fit:

• stdlib — textwrap has only TextWrapper, which is single-paragraph by
  construction: initial_indent/subsequent_indent are two fixed strings for
  the whole call. argparse's RawTextHelpFormatter preserves structure but does
  not wrap at all.
• click — wrap_text(preserve_paragraphs=True) sounds right and is not. It
  re-flows paragraph interiors, so pytest's bullet list collapses into exactly
  the run-on above; its \b escape disables wrapping outright, so items just
  overflow the terminal.
• rich — Text gets the model right, but gives continuation lines no indent
  (so it does not fix the actual bug), and is a large dependency for help
  formatting.

Checklist

• Include new tests or update existing tests when applicable.
• Allow maintainers to push and squash when merging my commits.
• Create a new changelog file in the changelog directory.
• AI tools were used; they are credited in a Co-authored-by commit trailer.