GH-57015: Add argparse FlexiHelpFormatter #22129

davesteele · 2020-09-07T13:35:43Z

This adds the FlexiHelpFormatter class to argparse.

It supports wrapping text, while preserving paragraphs. Bullet lists are supported.

There are a number of differences, relative to the latest patch in the issue report:

single line feeds in a paragraph are allowed
the code is refactored to avoid duplication
test failure fixes (mostly whitespace)

Tests and documentation are included.

https://pypi.org/project/argparse-formatter/

https://bugs.python.org/issue12806

argparse: Hybrid help text formatter #57015

Issue: argparse: Hybrid help text formatter #57015

Unfortunately, argparse's proposed FlexiHelpFormatter does not yet exist, see python/cpython#22129.

ghost · 2024-02-27T18:55:18Z

All commit authors signed the Contributor License Agreement.

python-cla-bot · 2025-04-18T09:50:23Z

All commit authors signed the Contributor License Agreement.

Rebase to force CI retest. The "addres sanitizer" test is failing with a timeout, on test_multiprocessing_fork.WithProcessesTestQueue(). It is not likely that this branch contributed to that failure. https://github.com/python/cpython/pull/22129/checks?check_run_id=3033564406

savannahostrowski

Hey there - I just saw this has been opened for awhile but I think this is a great formatter addition. I have a couple of comment but I've played around with this quite a bit and it looks pretty solid!

savannahostrowski · 2025-12-14T19:20:16Z

Doc/library/argparse.rst

+     -h, --help  show this help message and exit
+
+
+.. versionadded:: 3.13


Suggested change

.. versionadded:: 3.13

.. versionadded:: 3.15

Commit 8e20754.

savannahostrowski · 2025-12-14T19:24:43Z

Doc/library/argparse.rst


 .. class:: RawDescriptionHelpFormatter
           RawTextHelpFormatter
+           FlexiHelpFormatter


I don't think that FlexiHelpFormatter is descriptive enough. I'd suggest something like:

Suggested change

FlexiHelpFormatter

ParagraphHelpFormatter

Changed to ParagraphHelpFormatter in 2b30019.

savannahostrowski · 2025-12-14T19:36:32Z

Lib/argparse.py

+        lines = self._para_reformat(text, width)
+        return "\n".join(lines)


Suggested change

lines = self._para_reformat(text, width)

return "\n".join(lines)

lines = self._para_reformat(text, width - len(indent))

return "\n".join(indent + line for line in lines)

As is, this eats any form of indentation that the user might have specified, which I think we want to preserve.

Commit 2a53ad4.

savannahostrowski · 2025-12-14T19:42:54Z

Doc/library/argparse.rst

 one. If you wish to preserve multiple blank lines, add spaces between the
 newlines.

+:class:`FlexiHelpFormatter` wraps description and help text like the default


We should also make it more clear that consecutive non-blank lines at the same indentation without supported bullet markers are merged into one paragraph. Users should add blank lines if they want to preserve formatting.

Addressed in ec6d2d7.

savannahostrowski · 2025-12-14T19:44:32Z

Doc/library/argparse.rst

+formatter, while preserving paragraphs and supporting bulleted lists. Bullet
+list items are marked by the use of the "*", "-", "+", or ">" characters, or a
+single non-whitespace character followed by a "."::


Suggested change

formatter, while preserving paragraphs and supporting bulleted lists. Bullet

list items are marked by the use of the "*", "-", "+", or ">" characters, or a

single non-whitespace character followed by a "."::

formatter, while preserving paragraphs and supporting bulleted lists. Bullet

list items are recognized by markers such as "*", "-", "+", or ">" characters, or

by alphanumeric sequences followed by "." or ")" (e.g. 1., a), iv.)::

Sorry, I nuked the last part of your change. I thought it was mine, and has trouble reading it.

savannahostrowski · 2025-12-14T19:47:18Z

Doc/library/argparse.rst

+   ...             * See?
+   ...         """)
+   >>> parser.print_help()
+   usage: PROG [-h] option


Suggested change

usage: PROG [-h] option

usage: PROG [-h] argument

Commit ae7c70f.

savannahostrowski · 2025-12-14T19:47:56Z

Doc/library/argparse.rst

+                 wrap:
+                     * See?
+
+   optional arguments:


Suggested change

optional arguments:

options:

Commit f64e966.

bedevere-app · 2025-12-14T19:49:34Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Co-authored-by: Savannah Ostrowski <savannah@python.org>

It led to headaches in unittest.

davesteele · 2025-12-19T18:38:22Z

I have made the requested changes; please review again.

bedevere-app · 2025-12-19T18:38:27Z

Thanks for making the requested changes!

@savannahostrowski: please review the changes made to this pull request.

the-knights-who-say-ni added the CLA signed label Sep 7, 2020

bedevere-bot added the awaiting review label Sep 7, 2020

davesteele changed the title ~~bpo12806: Add argparse FlexiHelpFormatter~~ bpo-12806: Add argparse FlexiHelpFormatter Sep 7, 2020

davesteele force-pushed the bpo12806-flexihelpformatter branch 2 times, most recently from d82ce68 to da19cdd Compare April 9, 2021 17:04

bedevere-bot added awaiting core review and removed awaiting review labels May 27, 2021

benjaminhwilliams added a commit to dials/dials_scratch that referenced this pull request Jun 23, 2021

Retain help text wrapping

0eac7e0

Unfortunately, argparse's proposed FlexiHelpFormatter does not yet exist, see python/cpython#22129.

davesteele force-pushed the bpo12806-flexihelpformatter branch from 96c0799 to 008764b Compare July 25, 2021 15:29

joshuacwnewton mentioned this pull request Nov 3, 2021

Argparse's default formatters are not sufficient for our formatting needs spinalcordtoolbox/spinalcordtoolbox#3562

Closed

GraylinKim mannequin mentioned this pull request Apr 10, 2022

argparse: Hybrid help text formatter #57015

Open

cbkerr mentioned this pull request May 20, 2022

Add links to the query api page in view and find --help glotzerlab/signac#761

Merged

6 tasks

ezio-melotti removed the CLA signed label Jul 13, 2022

rmartin16 mentioned this pull request Dec 14, 2022

Help text includes command descriptions, platforms, and output formats beeware/briefcase#1005

Merged

4 tasks

davesteele and others added 6 commits April 27, 2025 13:47

bpo12806: Add argparse FlexiHelpFormatter

ed9787c

Update FlexiFormatter release to v3.10

18b8311

FlexiHelpFormatter: Recognize "-" bullets

f692c57

Fix test

757311d

Update FlexiHelpFormatter release to 3.13

a21117a

davesteele force-pushed the bpo12806-flexihelpformatter branch from a3ac677 to a21117a Compare April 27, 2025 17:49

davesteele requested a review from savannahostrowski as a code owner April 27, 2025 17:49

savannahostrowski requested changes Dec 14, 2025

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting core review labels Dec 14, 2025

Merge branch 'main' into bpo12806-flexihelpformatter

8981432

savannahostrowski changed the title ~~bpo-12806: Add argparse FlexiHelpFormatter~~ GH-57015: Add argparse FlexiHelpFormatter Dec 14, 2025

davesteele and others added 10 commits December 14, 2025 21:01

Update Doc/library/argparse.rst

8e20754

Co-authored-by: Savannah Ostrowski <savannah@python.org>

Update Lib/argparse.py

2a53ad4

Co-authored-by: Savannah Ostrowski <savannah@python.org>

Update Doc/library/argparse.rst

329d906

Co-authored-by: Savannah Ostrowski <savannah@python.org>

Update Doc/library/argparse.rst

ae7c70f

Co-authored-by: Savannah Ostrowski <savannah@python.org>

Update Doc/library/argparse.rst

f64e966

Co-authored-by: Savannah Ostrowski <savannah@python.org>

Fix ParagraphHelpFormatter test

46e5e13

Avoid whitespace-only lines in _fill_text()

d45028d

It led to headaches in unittest.

Lint fixes in argparse

8619282

Rename FlexiHelpFormatter->ParagraphHelpFormatter

2b30019

Clarify paragraph def for ParagraphHelpFormatter

ec6d2d7

bedevere-app bot added awaiting change review and removed awaiting changes labels Dec 19, 2025

bedevere-app bot requested a review from savannahostrowski December 19, 2025 18:38

		-h, --help show this help message and exit


		.. versionadded:: 3.13

		lines = self._para_reformat(text, width)
		return "\n".join(lines)

Uh oh!

GH-57015: Add argparse FlexiHelpFormatter #22129

Are you sure you want to change the base?

GH-57015: Add argparse FlexiHelpFormatter #22129

Uh oh!

Conversation

davesteele commented Sep 7, 2020 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Feb 27, 2024 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot bot commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

savannahostrowski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Dec 14, 2025

Uh oh!

davesteele commented Dec 19, 2025

Uh oh!

bedevere-app bot commented Dec 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

davesteele commented Sep 7, 2020 •

edited by bedevere-app bot

Loading

ghost commented Feb 27, 2024 •

edited by ghost

Loading

python-cla-bot bot commented Apr 18, 2025 •

edited

Loading