diff -r 44f455e6163d Doc/library/argparse.rst --- a/Doc/library/argparse.rst Thu Jun 27 12:23:29 2013 +0200 +++ b/Doc/library/argparse.rst Thu Jul 31 18:21:20 2014 -0700 @@ -1867,6 +1867,112 @@ .. _upgrading-optparse-code: + +WhitespaceStyle +^^^^^^^^^^^^^^^ + +An alternative to changing the formatter_class_ is to +create a text block as :class:`str` subclass which implements the +desired formatting behavior (wrapping and whitespace compression). +This is akin to marking HTML text with a `
` tag, or the
+CSS white-space: option.
+
+Currently there are five classes, corresponding to the CSS options.
+
+.. class:: Normal
+ Pre
+ NoWrap
+ PreLine
+ PreWrap
+
+:class:`Normal` implements the default wrapping behavior,
+as performed by the :class:`HelpFormatter`, including white-space
+compression.
+
+:class:`Pre` is used for preformatted text, preserving all white space
+and new lines. If both the description_ and epilog_ texts are of type
+:class:`Pre`, the help_ display will be same as that produced by the
+:class:`RawDescriptionHelpFormatter`. If the argument help_ text is also
+of type :class:`Pre` the display will match that produced by
+:class:`RawTextHelpFormatter`.
+
+For convenience ``textwrap.dedent()`` is available as a method for each of
+these Style classes::
+
+>>> parser = argparse.ArgumentParser(
+ ... prog='PROG',
+ ... description=argparse.Pre('''\
+ ... Please do not mess up this text!
+ ... --------------------------------
+ ... I have indented it
+ ... exactly the way
+ ... I want it
+ ... ''').dedent())
+>>> parser.print_help()
+ usage: PROG [-h]
+
+ Please do not mess up this text!
+ --------------------------------
+ I have indented it
+ exactly the way
+ I want it
+
+ optional arguments:
+ -h, --help show this help message and exit
+
+
+With these classes it is possible to mix the formatting style of the
+different parts of the help_ text. For example, the description_ could be
+a :class:`PreLine`, with multiple individually wrapped paragraphs.
+The epilog_ could be :class:`Pre` with examples, while the help_ text
+could be left unmarked (or of :class:`Normal`)::
+
+
+>>> parser = argparse.ArgumentParser(
+ ... prog='PROG',
+ ... description=argparse.PreLine('''\
+ ... This is a description composed of several paragraphs that are wrapped individually.
+ ...
+ ... %(prog)s arguments are as follows.
+ ... ''').dedent(),
+ ... epilog=argparse.Pre('''\
+ ... %(prog)s example:
+ ... %(prog)s --other 1
+ ... ''').dedent())
+>>> parser.add_argument('--text', help='a normal help line')
+>>> parser.add_argument('--other', default='test',
+ ... help=argparse.Pre("help line with hanging\n\t(default:%(default)r)"))
+>>> parser.print_help()
+ usage: PROG [-h] [--text TEXT] [--other OTHER]
+
+ This is a description composed of several paragraphs that are wrapped
+ individually.
+
+ PROG arguments are as follows.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --text TEXT a normal help line
+ --other OTHER help line with hanging
+ (default:'test')
+
+ PROG example:
+ PROG --other 1
+
+
+
+
+.. class:: WhitespaceStyle
+ WSList
+
+:class:`WhitespaceStyle` is the parent class for these Style classes,
+which may be used to define custom formatting actions. :class:`WSList` is a subclass of :class:`list`, with strings and Style
+class strings. It may be used to compose a text that uses several types
+of formatting.
+
+For now these Style classes only work with the default :class:`HelpFormatter`.
+
+
 Upgrading optparse code
 -----------------------
 
diff -r 44f455e6163d Lib/argparse.py
--- a/Lib/argparse.py	Thu Jun 27 12:23:29 2013 +0200
+++ b/Lib/argparse.py	Thu Jul 31 18:21:20 2014 -0700
@@ -80,6 +80,14 @@
 'REMAINDER',
 'SUPPRESS',
 'ZERO_OR_MORE',
+ 'WhitespaceStyle',
+ 'Normal',
+ 'Pre',
+ 'NoWrap',
+ 'PreWrap',
+ 'PreLine',
+ 'WSList',
+ 'Py3FormatHelpFormatter',
 ]
 
 
@@ -137,6 +145,194 @@
 return getattr(namespace, name)
 
 
+# =============================
+# CSS white-space like formmating
+# =============================
+
+class WhitespaceStyle(str):
+ """ parent for classes that implement wrapping (or not) in the style
+ of CSS white-space:
+ """
+ def dedent(self):
+ return self.copy_class(_textwrap.dedent(self))
+
+ def copy_class(self, text):
+ """preserve self's class in the returned text (or list of lines)
+ class information like this is readily lost in str operations like join
+ """
+ Fn = type(self)
+ if isinstance(text, str):
+ return Fn(text)
+ else:
+ # this may not be of any value since a list like this normally joined
+ return [Fn(line) for line in text]
+
+ def _str_format(self, adict):
+ # apply % formatting
+ text = self % adict
+ return self.copy_class(text)
+
+ def format(self, *args, **kwargs):
+ # apply Py3 style format()
+ text = super(WhitespaceStyle,self).format(*args, **kwargs)
+ return self.copy_class(text)
+
+ def block(self, keepblank=False):
+ # divide text in paragraphs - block of text lines returned
+ # as one line, defined by blank line
+ # adapted from issue12806 paragraphFormatter
+ # no special handling for indented lines
+ # may keep a blank line (' ') between blocks
+ text = self
+
+ def blocker (text):
+ block = []
+ for line in text.splitlines():
+ isblank = _re.match(r'\s*$', line)
+ if isblank:
+ if block:
+ yield ' '.join(block)
+ block = []
+ if keepblank:
+ yield ' '
+ else:
+ block.append(line)
+ if block:
+ yield (' '.join(block))
+
+ lines = list(blocker(text))
+ lines = '\n'.join(lines)
+ return self.copy_class(lines)
+
+
+class WSList(list):
+ # a list of WhitespaceStyle objects
+ # meant to be called like a WhitespaceStyle object, applying the
+ # method to each of its items
+ # may need to extend to handle str in Normal()
+ # e.g. iterator that converts str to Normal
+
+ def __contains__(self, key):
+ # e.g. for '%' in self
+ return any(l.__contains__(key) for l in self)
+
+ def _split_lines(self, width):
+ lines = []
+ for p in self:
+ lines.extend(p._split_lines(width))
+ return WSList(lines)
+
+ def _fill_text(self, width, indent):
+ lines = []
+ for p in self:
+ lines.append(p._fill_text(width, indent))
+ return '\n'.join(lines)
+
+ def _str_format(self, adict):
+ return WSList([x._str_format(adict) for x in self])
+
+ def format(self, *args, **kwargs):
+ return WSList([x.format(*args, **kwargs) for x in self])
+
+
+class Normal(WhitespaceStyle):
+ """Sequences of whitespace are collapsed. Newline characters in the
+ source are handled as other whitespace. Breaks lines as necessary to fill line boxes.
+ Acts same as the default base str class; convenience class
+ """
+ _whitespace_matcher = _re.compile(r'\s+')
+ def _split_lines(self, width):
+ text = self
+ text = self._whitespace_matcher.sub(' ', text).strip()
+ lines = _textwrap.wrap(text, width)
+ return self.copy_class(lines)
+
+ def _fill_text(self, width, indent):
+ text = self
+ text = self._whitespace_matcher.sub(' ', text).strip()
+ text = _textwrap.fill(text, width, initial_indent=indent,
+ subsequent_indent=indent)
+ return self.copy_class(text)
+
+class Pre(WhitespaceStyle):
+ """Sequences of whitespace are preserved, lines are only broken
+ at newline characters in the source and at 
 elements.
+ Acts same as the Raw...HelpFormatter classes
+ """
+ def _split_lines(self, width):
+ return self.copy_class(self.splitlines())
+
+ def _fill_text(self, width, indent):
+ text = ''.join(indent + line for line in self.splitlines(keepends=True))
+ return self.copy_class(text)
+
+class NoWrap(WhitespaceStyle):
+ """Collapses whitespace as for normal, but suppresses line breaks
+ (text wrapping) within text.
+ """
+ _whitespace_matcher = _re.compile(r'[ \t\r\f\v]+') # whitespace excelude \n
+ def _split_lines(self, width):
+ text = self.strip().splitlines()
+ lines = []
+ for line in text:
+ line = self._whitespace_matcher.sub(' ', line).strip()
+ lines.append(line)
+ return self.copy_class(lines)
+
+ def _fill_text(self, width, indent):
+ text = self.strip().splitlines()
+ lines = []
+ for line in text:
+ line = self._whitespace_matcher.sub(' ', line).strip()
+ lines.append(indent + line)
+ return self.copy_class('\n'.join(lines))
+
+class PreWrap(WhitespaceStyle):
+ """Sequences of whitespace are preserved. Lines are broken at newline characters,
+ and as necessary to fill line boxes."""
+ def _split_lines(self, width):
+ text = self.splitlines()
+ lines = []
+ for line in text:
+ lines.extend(_textwrap.wrap(line, width))
+ return self.copy_class(lines)
+
+ def _fill_text(self, width, indent):
+ text = self.splitlines()
+ lines = []
+ for line in text:
+ newline = _textwrap.fill(line, width, initial_indent=indent,
+ subsequent_indent=indent)
+ lines.append(newline)
+ text = "\n".join(lines)
+ return self.copy_class(text)
+
+class PreLine(WhitespaceStyle):
+ """Sequences of whitespace are collapsed. Lines are broken at newline
+ characters, and as necessary to fill line boxes."""
+ _whitespace_matcher = _re.compile(r'[ \t\r\f\v]+') # whitespace excelude \n
+ def _split_lines(self, width):
+ text = self.splitlines()
+ lines = []
+ for line in text:
+ line = self._whitespace_matcher.sub(' ', line).strip()
+ lines.extend(_textwrap.wrap(line, width))
+ return self.copy_class(lines)
+
+ def _fill_text(self, width, indent, subsequent_indent=None):
+ if subsequent_indent is None:
+ subsequent_indent = indent
+ text = self.splitlines()
+ lines = []
+ for line in text:
+ line = self._whitespace_matcher.sub(' ', line).strip()
+ newline = _textwrap.fill(line, width, initial_indent=indent,
+ subsequent_indent=subsequent_indent)
+ lines.append(newline)
+ text = "\n".join(lines)
+ return self.copy_class(text)
+
+
 # ===============
 # Formatting Help
 # ===============
@@ -290,7 +486,7 @@
 
 # if usage is specified, use that
 if usage is not None:
- usage = usage % dict(prog=self._prog)
+ usage = self._str_format(usage, dict(prog=self._prog))
 
 # if no optionals or positionals are available, usage is just prog
 elif usage is None and not actions:
@@ -474,8 +670,10 @@
 return text
 
 def _format_text(self, text):
- if '%(prog)' in text:
- text = text % dict(prog=self._prog)
+ #if '%(prog)' in text:
+ # text = self._str_format(text, dict(prog=self._prog))
+ # doesn't need to be conditional, does it?
+ text = self._str_format(text, dict(prog=self._prog))
 text_width = self._width - self._current_indent
 indent = ' ' * self._current_indent
 return self._fill_text(text, text_width, indent) + '\n\n'
@@ -597,7 +795,7 @@
 if params.get('choices') is not None:
 choices_str = ', '.join([str(c) for c in params['choices']])
 params['choices'] = choices_str
- return self._get_help_string(action) % params
+ return self._str_format(self._get_help_string(action), params)
 
 def _iter_indented_subactions(self, action):
 try:
@@ -610,13 +808,30 @@
 self._dedent()
 
 def _split_lines(self, text, width):
- text = self._whitespace_matcher.sub(' ', text).strip()
- return _textwrap.wrap(text, width)
+ try:
+ return text._split_lines(width)
+ except AttributeError:
+ return Normal(text)._split_lines(width)
 
 def _fill_text(self, text, width, indent):
- text = self._whitespace_matcher.sub(' ', text).strip()
- return _textwrap.fill(text, width, initial_indent=indent,
- subsequent_indent=indent)
+ try:
+ return text._fill_text(width, indent)
+ except AttributeError:
+ return Normal(text)._fill_text(width, indent)
+
+ def _str_format(self, text, adict):
+ # apply % formatting
+ if isinstance(text, [WhitespaceStyle, WSList]):
+ return text._str_format(adict)
+ else:
+ return text % adict
+
+ def _str_format(self, text, adict):
+ # apply % formatting; alt logic
+ try:
+ return text._str_format(adict)
+ except AttributeError:
+ return Normal(text)._str_format(adict)
 
 def _get_help_string(self, action):
 return action.help
@@ -683,6 +898,26 @@
 
 
 
+class Py3FormatHelpFormatter(HelpFormatter):
+ """Help message formatter which accepts the Py3 string format function.
+
+ Only the name of this class is considered a public API. All the methods
+ provided by the class are considered an implementation detail.
+ """
+
+ def _str_format(self, text, adict):
+ # handle both % and format styles
+ if '%(' in text:
+ return super(Py3FormatHelpFormatter, self)._str_format(text, adict)
+ else:
+ try:
+ # protect against % style text that may have a string
+ # that looks like a new style (e.g. {test})
+ return text.format(**adict)
+ except KeyError:
+ pass
+ return text
+
 # =====================
 # Options and Arguments
 # =====================
diff -r 44f455e6163d Lib/test/test_argparse.py
--- a/Lib/test/test_argparse.py	Thu Jun 27 12:23:29 2013 +0200
+++ b/Lib/test/test_argparse.py	Thu Jul 31 18:21:20 2014 -0700
@@ -3957,6 +3957,102 @@
 version = ''
 
 
+Pre = argparse.Pre
+class TestHelpPreFormattedText(HelpTestCase):
+ """Test the Pre alternative to RawTextHelpFormatter"""
+
+ parser_signature = Sig(
+ prog='PROG',
+ description=Pre('Keep the formatting\n'
+ ' exactly as it is written\n'
+ '\n'
+ 'here\n'))
+
+ argument_signatures = [
+ Sig('--foo', help=Pre(' foo help should also\n'
+ 'appear as given here')),
+ Sig('spam', help='spam help'),
+ ]
+ argument_group_signatures = [
+ (Sig('title', description=Pre(' This text\n'
+ ' should be indented\n'
+ ' exactly like it is here\n')),
+ [Sig('--bar', help='bar help')]),
+ ]
+ usage = '''\
+ usage: PROG [-h] [--foo FOO] [--bar BAR] spam
+ '''
+ help = usage + '''\
+
+ Keep the formatting
+ exactly as it is written
+
+ here
+
+ positional arguments:
+ spam spam help
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo help should also
+ appear as given here
+
+ title:
+ This text
+ should be indented
+ exactly like it is here
+
+ --bar BAR bar help
+ '''
+ version = ''
+
+class TestHelpPreFormattedDescription(HelpTestCase):
+ """Test the Pre alternative to RawTextHelpFormatter"""
+
+ parser_signature = Sig(
+ prog='PROG',
+ description=Pre('Keep the formatting\n'
+ ' exactly as it is written\n'
+ '\n'
+ 'here\n'))
+
+ argument_signatures = [
+ Sig('--foo', help=' foo help should not\n'
+ ' retain this odd formatting'),
+ Sig('spam', help='spam help'),
+ ]
+ argument_group_signatures = [
+ (Sig('title', description=Pre(' This text\n'
+ ' should be indented\n'
+ ' exactly like it is here\n')),
+ [Sig('--bar', help='bar help')]),
+ ]
+ usage = '''\
+ usage: PROG [-h] [--foo FOO] [--bar BAR] spam
+ '''
+ help = usage + '''\
+
+ Keep the formatting
+ exactly as it is written
+
+ here
+
+ positional arguments:
+ spam spam help
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --foo FOO foo help should not retain this odd formatting
+
+ title:
+ This text
+ should be indented
+ exactly like it is here
+
+ --bar BAR bar help
+ '''
+ version = ''
+
 class TestHelpArgumentDefaults(HelpTestCase):
 """Test the ArgumentDefaultsHelpFormatter"""
 





AltStyle によって変換されたページ (->オリジナル)
/