Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/face/helpers.py: 37%
173 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 06:23 +0000
2import os
3import sys
4import array
5import textwrap
7from boltons.iterutils import unique, split
9from face.utils import format_flag_label, format_flag_post_doc, format_posargs_label, echo
10from face.parser import Flag
12DEFAULT_HELP_FLAG = Flag('--help', parse_as=True, char='-h', doc='show this help message and exit')
13DEFAULT_MAX_WIDTH = 120
16def _get_termios_winsize():
17 # TLPI, 62.9 (p. 1319)
18 import fcntl
19 import termios
21 winsize = array.array('H', [0, 0, 0, 0])
23 assert not fcntl.ioctl(sys.stdout, termios.TIOCGWINSZ, winsize)
25 ws_row, ws_col, _, _ = winsize
27 return ws_row, ws_col
30def _get_environ_winsize():
31 # the argparse approach. not sure which systems this works or
32 # worked on, if any. ROWS/COLUMNS are special shell variables.
33 try:
34 rows, columns = int(os.environ['ROWS']), int(os.environ['COLUMNS'])
35 except (KeyError, ValueError):
36 rows, columns = None, None
37 return rows, columns
40def get_winsize():
41 rows, cols = None, None
42 try:
43 rows, cols = _get_termios_winsize()
44 except Exception:
45 try:
46 rows, cols = _get_environ_winsize()
47 except Exception:
48 pass
49 return rows, cols
52def get_wrap_width(max_width=DEFAULT_MAX_WIDTH):
53 _, width = get_winsize()
54 if width is None:
55 width = 80
56 width = min(width, max_width)
57 width -= 2
58 return width
61def _wrap_stout_pair(indent, label, sep, doc, doc_start, max_doc_width):
62 # TODO: consider making the fill character configurable (ljust
63 # uses space by default, the just() methods can only take
64 # characters, might be a useful bolton to take a repeating
65 # sequence)
66 ret = []
67 append = ret.append
68 lhs = indent + label
70 if not doc:
71 append(lhs)
72 return ret
74 len_sep = len(sep)
75 wrapped_doc = textwrap.wrap(doc, max_doc_width)
76 if len(lhs) <= doc_start:
77 lhs_f = lhs.ljust(doc_start - len(sep)) + sep
78 append(lhs_f + wrapped_doc[0])
79 else:
80 append(lhs)
81 append((' ' * (doc_start - len_sep)) + sep + wrapped_doc[0])
83 for line in wrapped_doc[1:]:
84 append(' ' * doc_start + line)
86 return ret
89def _wrap_stout_cmd_doc(indent, doc, max_width):
90 """Function for wrapping command description."""
91 parts = []
92 paras = ['\n'.join(para) for para in
93 split(doc.splitlines(), lambda l: not l.lstrip())
94 if para]
95 for para in paras:
96 part = textwrap.fill(text=para,
97 width=(max_width - len(indent)),
98 initial_indent=indent,
99 subsequent_indent=indent)
100 parts.append(part)
101 return '\n\n'.join(parts)
104def get_stout_layout(labels, indent, sep, width=None, max_width=DEFAULT_MAX_WIDTH,
105 min_doc_width=40):
106 width = width or get_wrap_width(max_width=max_width)
108 len_sep = len(sep)
109 len_indent = len(indent)
111 max_label_width = 0
112 max_doc_width = min_doc_width
113 doc_start = width - min_doc_width
114 for label in labels:
115 cur_len = len(label)
116 if cur_len < max_label_width:
117 continue
118 max_label_width = cur_len
119 if (len_indent + cur_len + len_sep + min_doc_width) < width:
120 max_doc_width = width - max_label_width - len_sep - len_indent
121 doc_start = len_indent + cur_len + len_sep
123 return {'width': width,
124 'label_width': max_label_width,
125 'doc_width': max_doc_width,
126 'doc_start': doc_start}
129DEFAULT_CONTEXT = {
130 'usage_label': 'Usage:',
131 'subcmd_section_heading': 'Subcommands: ',
132 'flags_section_heading': 'Flags: ',
133 'posargs_section_heading': 'Positional arguments:',
134 'section_break': '\n',
135 'group_break': '',
136 'subcmd_example': 'subcommand',
137 'width': None,
138 'max_width': 120,
139 'min_doc_width': 50,
140 'format_posargs_label': format_posargs_label,
141 'format_flag_label': format_flag_label,
142 'format_flag_post_doc': format_flag_post_doc,
143 'doc_separator': ' ', # ' + ' is pretty classy as bullet points, too
144 'section_indent': ' ',
145 'pre_doc': '', # TODO: these should go on CommandDisplay
146 'post_doc': '\n',
147}
150class StoutHelpFormatter(object):
151 """This formatter takes :class:`Parser` and :class:`Command` instances
152 and generates help text. The output style is inspired by, but not
153 the same as, argparse's automatic help formatting.
155 Probably what most Pythonists expect, this help text is slightly
156 stouter (conservative with vertical space) than other conventional
157 help messages.
159 The default output looks like::
161 Usage: example.py subcommand [FLAGS]
163 Does a bit of busy work
166 Subcommands:
168 sum Just a lil fun in the sum
169 subtract
170 print
173 Flags:
175 --help / -h show this help message and exit
176 --verbose / -V
179 Due to customizability, the constructor takes a large number of
180 keyword arguments, the most important of which are highlighted
181 here.
183 Args:
184 width (int): The width of the help output in
185 columns/characters. Defaults to the width of the terminal,
186 with a max of *max_width*.
187 max_width (int): The widest the help output will get. Too wide
188 and it can be hard to visually scan. Defaults to 120 columns.
189 min_doc_width (int): The text documentation's minimum width in
190 columns/characters. Puts flags and subcommands on their own
191 lines when they're long or the terminal is narrow. Defaults to
192 50.
193 doc_separator (str): The string to put between a
194 flag/subcommand and its documentation. Defaults to `' '`. (Try
195 `' + '` for a classy bulleted doc style.
197 An instance of StoutHelpFormatter can be passed to
198 :class:`HelpHandler`, which can in turn be passed to
199 :class:`Command` for maximum command customizability.
201 Alternatively, when using :class:`Parser` object directly, you can
202 instantiate this type and pass a :class:`Parser` object to
203 :meth:`get_help_text()` or :meth:`get_usage_line()` to get
204 identically formatted text without sacrificing flow control.
206 HelpFormatters are stateless, in that they can be used more than
207 once, with different Parsers and Commands without needing to be
208 recreated or otherwise reset.
210 """
211 default_context = dict(DEFAULT_CONTEXT)
213 def __init__(self, **kwargs):
214 self.ctx = {}
215 for key, val in self.default_context.items():
216 self.ctx[key] = kwargs.pop(key, val)
217 if kwargs:
218 raise TypeError('unexpected formatter arguments: %r' % list(kwargs.keys()))
220 def _get_layout(self, labels):
221 ctx = self.ctx
222 return get_stout_layout(labels=labels,
223 indent=ctx['section_indent'],
224 sep=ctx['doc_separator'],
225 width=ctx['width'],
226 max_width=ctx['max_width'],
227 min_doc_width=ctx['min_doc_width'])
229 def get_help_text(self, parser, subcmds=(), program_name=None):
230 """Turn a :class:`Parser` or :class:`Command` into a multiline
231 formatted help string, suitable for printing. Includes the
232 usage line and trailing newline by default.
234 Args:
235 parser (Parser): A :class:`Parser` or :class:`Command`
236 object to generate help text for.
237 subcmds (tuple): A sequence of subcommand strings
238 specifying the subcommand to generate help text for.
239 Defaults to ``()``.
240 program_name (str): The program name, if it differs from
241 the default ``sys.argv[0]``. (For example,
242 ``example.py``, when running the command ``python
243 example.py --flag val arg``.)
245 """
246 # TODO: incorporate "Arguments" section if posargs has a doc set
247 ctx = self.ctx
249 ret = [self.get_usage_line(parser, subcmds=subcmds, program_name=program_name)]
250 append = ret.append
251 append(ctx['group_break'])
253 shown_flags = parser.get_flags(path=subcmds, with_hidden=False)
254 if subcmds:
255 parser = parser.subprs_map[subcmds]
257 if parser.doc:
258 append(_wrap_stout_cmd_doc(indent=ctx['section_indent'],
259 doc=parser.doc,
260 max_width=ctx['width'] or get_wrap_width(
261 max_width=ctx['max_width'])))
262 append(ctx['section_break'])
264 if parser.subprs_map:
265 subcmd_names = unique([sp[0] for sp in parser.subprs_map if sp])
266 subcmd_layout = self._get_layout(labels=subcmd_names)
268 append(ctx['subcmd_section_heading'])
269 append(ctx['group_break'])
270 for sub_name in unique([sp[0] for sp in parser.subprs_map if sp]):
271 subprs = parser.subprs_map[(sub_name,)]
272 subcmd_lines = _wrap_stout_pair(indent=ctx['section_indent'],
273 label=sub_name.replace('_', '-'),
274 sep=ctx['doc_separator'],
275 doc=subprs.doc,
276 doc_start=subcmd_layout['doc_start'],
277 max_doc_width=subcmd_layout['doc_width'])
278 ret.extend(subcmd_lines)
280 append(ctx['section_break'])
282 if not shown_flags:
283 return '\n'.join(ret)
285 fmt_flag_label = ctx['format_flag_label']
286 flag_labels = [fmt_flag_label(flag) for flag in shown_flags]
287 flag_layout = self._get_layout(labels=flag_labels)
289 fmt_flag_post_doc = ctx['format_flag_post_doc']
290 append(ctx['flags_section_heading'])
291 append(ctx['group_break'])
292 for flag in shown_flags:
293 disp = flag.display
294 if disp.full_doc is not None:
295 doc = disp.full_doc
296 else:
297 _parts = [disp.doc] if disp.doc else []
298 post_doc = disp.post_doc if disp.post_doc else fmt_flag_post_doc(flag)
299 if post_doc:
300 _parts.append(post_doc)
301 doc = ' '.join(_parts)
303 flag_lines = _wrap_stout_pair(indent=ctx['section_indent'],
304 label=fmt_flag_label(flag),
305 sep=ctx['doc_separator'],
306 doc=doc,
307 doc_start=flag_layout['doc_start'],
308 max_doc_width=flag_layout['doc_width'])
310 ret.extend(flag_lines)
312 return ctx['pre_doc'] + '\n'.join(ret) + ctx['post_doc']
314 def get_usage_line(self, parser, subcmds=(), program_name=None):
315 """Get just the top line of automated text output. Arguments are the
316 same as :meth:`get_help_text()`. Basic info about running the
317 command, such as:
319 Usage: example.py subcommand [FLAGS] [args ...]
321 """
322 ctx = self.ctx
323 subcmds = tuple(subcmds or ())
324 parts = [ctx['usage_label']] if ctx['usage_label'] else []
325 append = parts.append
327 program_name = program_name or parser.name
329 append(' '.join((program_name,) + subcmds))
331 # TODO: put () in subprs_map to handle some of this sorta thing
332 if not subcmds and parser.subprs_map:
333 append('subcommand')
334 elif subcmds and parser.subprs_map[subcmds].subprs_map:
335 append('subcommand')
337 # with subcommands out of the way, look up the parser for flags and args
338 if subcmds:
339 parser = parser.subprs_map[subcmds]
341 flags = parser.get_flags(with_hidden=False)
343 if flags:
344 append('[FLAGS]')
346 if not parser.posargs.display.hidden:
347 fmt_posargs_label = ctx['format_posargs_label']
348 append(fmt_posargs_label(parser.posargs))
350 return ' '.join(parts)
354'''
355class AiryHelpFormatter(object):
356 """No wrapping a doc onto the same line as the label. Just left
357 aligned labels + newline, then right align doc. No complicated
358 width calculations either. See https://github.com/kbknapp/clap-rs
359 """
360 pass # TBI
361'''
364class HelpHandler(object):
365 """The HelpHandler is a one-stop object for that all-important CLI
366 feature: automatic help generation. It ties together the actual
367 help handler with the optional flag and subcommand such that it
368 can be added to any :class:`Command` instance.
370 The :class:`Command` creates a HelpHandler instance by default,
371 and its constructor also accepts an instance of this type to
372 customize a variety of helpful features.
374 Args:
375 flag (face.Flag): The Flag instance to use for triggering a
376 help output in a Command setting. Defaults to the standard
377 ``--help / -h`` flag. Pass ``False`` to disable.
378 subcmd (str): A subcommand name to be added to any
379 :class:`Command` using this HelpHandler. Defaults to
380 ``None``.
381 formatter: A help formatter instance or type. Type will be
382 instantiated with keyword arguments passed to this
383 constructor. Defaults to :class:`StoutHelpFormatter`.
384 func (callable): The actual handler function called on flag
385 presence or subcommand invocation. Defaults to
386 :meth:`HelpHandler.default_help_func()`.
388 All other remaining keyword arguments are used to construct the
389 HelpFormatter, if *formatter* is a type (as is the default). For
390 an example of a formatter, see :class:`StoutHelpFormatter`, the
391 default help formatter.
392 """
393 # Other hooks (besides the help function itself):
394 # * Callbacks for unhandled exceptions
395 # * Callbacks for formatting errors (add a "see --help for more options")
397 def __init__(self, flag=DEFAULT_HELP_FLAG, subcmd=None,
398 formatter=StoutHelpFormatter, func=None, **formatter_kwargs):
399 # subcmd expects a string
400 self.flag = flag
401 self.subcmd = subcmd
402 self.func = func if func is not None else self.default_help_func
403 if not callable(self.func):
404 raise TypeError('expected help handler func to be callable, not %r' % func)
406 self.formatter = formatter
407 if not formatter:
408 raise TypeError('expected Formatter type or instance, not: %r' % formatter)
409 if isinstance(formatter, type):
410 self.formatter = formatter(**formatter_kwargs)
411 elif formatter_kwargs:
412 raise TypeError('only accepts extra formatter kwargs (%r) if'
413 ' formatter argument is a Formatter type, not: %r'
414 % (sorted(formatter_kwargs.keys()), formatter))
415 _has_get_help_text = callable(getattr(self.formatter, 'get_help_text', None))
416 if not _has_get_help_text:
417 raise TypeError('expected valid formatter, or other object with a'
418 ' get_help_text() method, not %r' % (self.formatter,))
419 return
421 def default_help_func(self, cmd_, subcmds_, args_, command_):
422 """The default help handler function. Called when either the help flag
423 or subcommand is passed.
425 Prints the output of the help formatter instance attached to
426 this HelpHandler and exits with exit code 0.
428 """
429 echo(self.formatter.get_help_text(command_, subcmds=subcmds_, program_name=cmd_))
432"""Usage: cmd_name sub_cmd [..as many subcommands as the max] --flags args ...
434Possible commands:
436(One of the possible styles below)
438Flags:
439 Group name (if grouped):
440 -F, --flag VALUE Help text goes here. (integer, defaults to 3)
442Flag help notes:
444* don't display parenthetical if it's string/None
445* Also need to indicate required and mutual exclusion ("not with")
446* Maybe experimental / deprecated support
447* General flag listing should also include flags up the chain
449Subcommand listing styles:
451* Grouped, one-deep, flag overview on each
452* One-deep, grouped or alphabetical, help string next to each
453* Grouped by tree (new group whenever a subtree of more than one
454 member finishes), with help next to each.
456What about extra lines in the help (like zfs) (maybe each individual
457line can be a template string?)
459TODO: does face need built-in support for version subcommand/flag,
460basically identical to help?
462Group names can be ints or strings. When, group names are strings,
463flags are indented under a heading consisting of the string followed
464by a colon. All ungrouped flags go under a 'General Flags' group
465name. When group names are ints, groups are not indented, but a
466newline is still emitted by each group.
468Alphabetize should be an option, otherwise everything stays in
469insertion order.
471Subcommands without handlers should not be displayed in help. Also,
472their implicit handler prints the help.
474Subcommand groups could be Commands with name='', and they can only be
475added to other commands, where they would embed as siblings instead of
476as subcommands. Similar to how clastic subapplications can be mounted
477without necessarily adding to the path.
479Is it better to delegate representations out or keep them all within
480the help builder?
482---
484Help needs: a flag (and a way to disable it), as well as a renderer.
486Usage:
488Doc
490Subcommands:
492... ...
494Flags:
496...
498Postdoc
501{usage_label} {cmd_name} {subcmd_path} {subcmd_blank} {flags_blank} {posargs_label}
503{cmd.doc}
505{subcmd_heading}
507 {subcmd.name} {subcmd.doc} {subcmd.post_doc}
509{flags_heading}
511 {group_name}:
513 {flag_label} {flag.doc} {flag.post_doc}
515{cmd.post_doc}
518--------
520# Grouping
522Effectively sorted on: (group_name, group_index, sort_order, label)
524But group names should be based on insertion order, with the
525default-grouped/ungrouped items showing up in the last group.
527# Wrapping / Alignment
529Docs start at the position after the longest "left-hand side"
530(LHS/"key") item that would not cause the first line of the docs to be
531narrower than the minimum doc width.
533LHSes which do extend beyond this point will be on their own line,
534with the doc starting on the line below.
536# Window width considerations
538With better termios-based logic in place to get window size, there are
539going to be a lot of wider-than-80-char help messages.
541The goal of help message alignment is to help eyes track across from a
542flag or subcommand to its corresponding doc. Rather than maximizing
543width usage or topping out at a max width limit, we should be
544balancing or at least limiting the amount of whitespace between the
545shortest flag and its doc. (TODO)
547A width limit might still make sense because reading all the way
548across the screen can be tiresome, too.
550TODO: padding_top and padding_bottom attributes on various displays
551(esp FlagDisplay) to enable finer grained whitespace control without
552complicated group setups.
554"""