argparse - CSS white-space: like control for individual text blocks

[paulj3]

BPO	22029
Nosy	@merwok, @jonashaag
Files	issue22029_1.patch issue22029_2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-07-22.04:46:53.053>
labels = ['type-feature', 'library']
title = 'argparse - CSS white-space: like control for individual text blocks'
updated_at = <Date 2019-04-26.20:21:07.658>
user = 'https://bugs.python.org/paulj3'

bugs.python.org fields:

activity = <Date 2019-04-26.20:21:07.658>
actor = 'BreamoreBoy'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2014-07-22.04:46:53.053>
creator = 'paul.j3'
dependencies = []
files = ['36023', '36187']
hgrepos = []
issue_num = 22029
keywords = ['patch']
message_count = 2.0
messages = ['223625', '223626']
nosy_count = 6.0
nosy_names = ['bethard', 'eric.araujo', 'denilsonsa', 'jonash', 'GraylinKim', 'paul.j3']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue22029'
versions = ['Python 3.5']

[paulj3]

A number of the issues seek to customize the wrapping behavior in HelpFormatter - beyond what the current Formatter subclasses offer.

http://bugs.python.org/issue13923 and http://bugs.python.org/issue12806 - want a wrapping method that preserves existing \n, while still wrapping long lines.

http://bugs.python.org/issue12806#msg144353 - suggests that this formatter is similar to CSS property white-space: pre-wrap.

http://bugs.python.org/issue9399 - wants to write a pre-formatted 'license' text using a 'version'-like Action.

http://bugs.python.org/issue13023 - wants to use 2 HelpFormatter subclasses at the same time (Raw and Defaults).

http://bugs.python.org/issue13023#msg144475: "Yeah, adding a formatter instance seems overkill for the usual case of wanting to preserve formatting of the epilog."

http://bugs.python.org/issue12284 - wants to put formatted examples in the epilog.

It might be easier to handle these issues if the user could designate how an individual text block (description, epilog, help) is to be formatted.

HTML has a '<pre>' tag, CSS has 'white-space:' attribute (with 5 styles of wrapping and white-space handling).

The usage example might be something like:

    parser = ArgumentParser(prog='PROG',
        description = NoWrap('This is a description...'),
        epilog = PreWrap('Multipoint epilog with examples...'),
        )
    parser.add_argument('-f', help='help with normal wrapping')

[paulj3]

One way of marking a string for special wrap handing is to make it an instance of a subclass of 'str'.

This patch adds class _WhitespaceStyle(str), and 5 subclasses corresponding to the possible values of the CSS whitespace:.

 Normal
 Pre
 NoWrap
 PreLine
 PreWrap 

Together they define methods:

_str_format() - apply % style formatting
format() - apply the py3 {} style formatting
_split_lines() - style specific split_lines (may or may not pass through text_wrap)
_fill_text() - style specific fill_text (again without without test_wrap)

All return a text object of the same class (as self). This make it possible to apply the % formatting to a string, and then apply the wrapping, without loosing class information:

Pre('sample text %(default)s')._str_format(dict(default='Boo'))._fill_text(30, '   ')

This subclass information is lost when the string pass through other 'str' operations, for example '\n'.join(). I needed to add _str_format because % formatting is applied to them before text_wrap.

The HelpFormatter has:

_str_format() - all the previous % formatting instances
_split_lines()
_fill_text()

These delegate the action to the respective white_space classes, or use the (default) Normal subclass if the text is a plain 'str'.

test_argparse.py has 2 test cases that use the 'Pre' class to replicate the behaviour of the Raw...HelpFormatter class tests. Undoubtedly it needs further tests to handle all of these new classes.

I haven't made any doc changes yet.

I wrote these classes based on the descriptions of what the CSS options do, but I have not tried to compare the handling of sample text. I can also imagine users wanting to refine the wrap handling further (e.g. http://bugs.python.org/issue12806).

I intend to write test files to show how these new classes could be used in the various issues that I listed in the previous post.

------------

Since I had to collect the % formatting cases into one _str_format() method (to preserve class information), I am also exploring the use of Py3 {} formatting.

Py3FormatHelpFormatter - a new Formatter class that redefines _str_format() to handle {} style formatting (if present). I put this in a separate class because there is a slight possibility that existing code has text that might be confused for Py3 style formatting, e.g.

    help='help text {default: %(default)s}'  

I think the issue of using Py3 formatting was raised and rejected. So I'm not committed to including this feature.