The doc for argparse.RawTextHelpFormatter states that it "maintains whitespace for all sorts of help text, including argument descriptions."  But the following example (which outputs "Foo", "Bar", and "Baz", each separated by exactly one empty line) shows that paragraphs separated by more than one empty line will only be separated in the output text by a single empty line.


import argparse
parser = argparse.ArgumentParser(
    prog='PROG',
    formatter_class=argparse.RawTextHelpFormatter,
    description='''\
Foo

Bar


Baz''')
parser.print_help()

It maintains *whitespace*, not the new lines. 
I've tested this using whitespaces and I think it keeps them according to the original description. See the image attached.

If that is the intended definition of "whitespace" in this context (I have no opinion on that so far), then the docs need amplification, because in general "whitespace" includes newlines.  On the other hand, this might be considered a bug in the code and not the docs.  However, changing it has backward compatibility implications, so we might go for a doc fix regardless.

I've seen this before, either in another bug/issue or a Stackoverflow question.

The basic change in RawTextHelpFormatter is to turn off the line wrapping for texts like the description.  Multiple newlines are preserved at this step.

But after assembling all the pieces (usage, description, help, epilog) the formatter strips out duplicate newlines.  This is needed because the process of assembly freely inserts newlines between the pieces, regardless of whether they are blank or not.  It can't, or at least doesn't try to, distinguish between newlines within a block like the description, and newlines between blocks.

If someone could come up with a simple patch, great.  Or a simple change to the doc wording.  But I don't think this issue merits a larger fix.

http://bugs.python.org/issue17113
argparse.RawDescriptionHelpFormatter should not delete blank lines

This provides more details on why this is happening.

I suggest using adding a space between newlines, thus: '\n \n'.  HelpFormatter.format_help is just looking for '\n\n'.

I've created a pull request. Could someone review it please?

New changeset 397c467c49385023de36411194d381ac993bae1a by R. David Murray (Elena Oat) in branch 'master':
bpo-31330: Clarify that RawTextHelpFormatter collapses repeated newlines. (#3272)
https://github.com/python/cpython/commit/397c467c49385023de36411194d381ac993bae1a

Thanks, Elena.

New changeset 82cae7c5be4175e2173e4d342825b5315a9d612a by R. David Murray (Miss Islington (bot)) in branch '2.7':
[2.7] bpo-31330: Clarify that RawTextHelpFormatter collapses repeated newlines. (GH-3272) (GH-3428)
https://github.com/python/cpython/commit/82cae7c5be4175e2173e4d342825b5315a9d612a

New changeset e89b35dd2b87e85978b91e3e2dbdea1fc76d6be4 by R. David Murray (Miss Islington (bot)) in branch '3.6':
[3.6] bpo-31330: Clarify that RawTextHelpFormatter collapses repeated newlines. (GH-3272) (GH-3429)
https://github.com/python/cpython/commit/e89b35dd2b87e85978b91e3e2dbdea1fc76d6be4