jcs.org
qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
1# This is a local copy of the standard library argparse module taken from PyPI.
2# It is licensed under the Python Software Foundation License. This is a
3# fallback for Python 2.6 which does not include this module. Python 2.7+ and
4# 3+ will never load this module because built-in modules are loaded before
5# anything in sys.path.
6#
7# If your script is not located in the same directory as this file, import it
8# like this:
9#
10# import os
11# import sys
12# sys.path.append(os.path.join(os.path.dirname(__file__), ..., 'scripts'))
13# import argparse
14
15# Author: Steven J. Bethard <steven.bethard@gmail.com>.
16# Maintainer: Thomas Waldmann <tw@waldmann-edv.de>
17
18"""Command-line parsing library
19
20This module is an optparse-inspired command-line parsing library that:
21
22 - handles both optional and positional arguments
23 - produces highly informative usage messages
24 - supports parsers that dispatch to sub-parsers
25
26The following is a simple usage example that sums integers from the
27command-line and writes the result to a file::
28
29 parser = argparse.ArgumentParser(
30 description='sum the integers at the command line')
31 parser.add_argument(
32 'integers', metavar='int', nargs='+', type=int,
33 help='an integer to be summed')
34 parser.add_argument(
35 '--log', default=sys.stdout, type=argparse.FileType('w'),
36 help='the file where the sum should be written')
37 args = parser.parse_args()
38 args.log.write('%s' % sum(args.integers))
39 args.log.close()
40
41The module contains the following public classes:
42
43 - ArgumentParser -- The main entry point for command-line parsing. As the
44 example above shows, the add_argument() method is used to populate
45 the parser with actions for optional and positional arguments. Then
46 the parse_args() method is invoked to convert the args at the
47 command-line into an object with attributes.
48
49 - ArgumentError -- The exception raised by ArgumentParser objects when
50 there are errors with the parser's actions. Errors raised while
51 parsing the command-line are caught by ArgumentParser and emitted
52 as command-line messages.
53
54 - FileType -- A factory for defining types of files to be created. As the
55 example above shows, instances of FileType are typically passed as
56 the type= argument of add_argument() calls.
57
58 - Action -- The base class for parser actions. Typically actions are
59 selected by passing strings like 'store_true' or 'append_const' to
60 the action= argument of add_argument(). However, for greater
61 customization of ArgumentParser actions, subclasses of Action may
62 be defined and passed as the action= argument.
63
64 - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter,
65 ArgumentDefaultsHelpFormatter -- Formatter classes which
66 may be passed as the formatter_class= argument to the
67 ArgumentParser constructor. HelpFormatter is the default,
68 RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser
69 not to change the formatting for help text, and
70 ArgumentDefaultsHelpFormatter adds information about argument defaults
71 to the help.
72
73All other classes in this module are considered implementation details.
74(Also note that HelpFormatter and RawDescriptionHelpFormatter are only
75considered public as object names -- the API of the formatter objects is
76still considered an implementation detail.)
77"""
78
79__version__ = '1.4.0' # we use our own version number independent of the
80 # one in stdlib and we release this on pypi.
81
82__external_lib__ = True # to make sure the tests really test THIS lib,
83 # not the builtin one in Python stdlib
84
85__all__ = [
86 'ArgumentParser',
87 'ArgumentError',
88 'ArgumentTypeError',
89 'FileType',
90 'HelpFormatter',
91 'ArgumentDefaultsHelpFormatter',
92 'RawDescriptionHelpFormatter',
93 'RawTextHelpFormatter',
94 'Namespace',
95 'Action',
96 'ONE_OR_MORE',
97 'OPTIONAL',
98 'PARSER',
99 'REMAINDER',
100 'SUPPRESS',
101 'ZERO_OR_MORE',
102]
103
104
105import copy as _copy
106import os as _os
107import re as _re
108import sys as _sys
109import textwrap as _textwrap
110
111from gettext import gettext as _
112
113try:
114 set
115except NameError:
116 # for python < 2.4 compatibility (sets module is there since 2.3):
117 from sets import Set as set
118
119try:
120 basestring
121except NameError:
122 basestring = str
123
124try:
125 sorted
126except NameError:
127 # for python < 2.4 compatibility:
128 def sorted(iterable, reverse=False):
129 result = list(iterable)
130 result.sort()
131 if reverse:
132 result.reverse()
133 return result
134
135
136def _callable(obj):
137 return hasattr(obj, '__call__') or hasattr(obj, '__bases__')
138
139
140SUPPRESS = '==SUPPRESS=='
141
142OPTIONAL = '?'
143ZERO_OR_MORE = '*'
144ONE_OR_MORE = '+'
145PARSER = 'A...'
146REMAINDER = '...'
147_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args'
148
149# =============================
150# Utility functions and classes
151# =============================
152
153class _AttributeHolder(object):
154 """Abstract base class that provides __repr__.
155
156 The __repr__ method returns a string in the format::
157 ClassName(attr=name, attr=name, ...)
158 The attributes are determined either by a class-level attribute,
159 '_kwarg_names', or by inspecting the instance __dict__.
160 """
161
162 def __repr__(self):
163 type_name = type(self).__name__
164 arg_strings = []
165 for arg in self._get_args():
166 arg_strings.append(repr(arg))
167 for name, value in self._get_kwargs():
168 arg_strings.append('%s=%r' % (name, value))
169 return '%s(%s)' % (type_name, ', '.join(arg_strings))
170
171 def _get_kwargs(self):
172 return sorted(self.__dict__.items())
173
174 def _get_args(self):
175 return []
176
177
178def _ensure_value(namespace, name, value):
179 if getattr(namespace, name, None) is None:
180 setattr(namespace, name, value)
181 return getattr(namespace, name)
182
183
184# ===============
185# Formatting Help
186# ===============
187
188class HelpFormatter(object):
189 """Formatter for generating usage messages and argument help strings.
190
191 Only the name of this class is considered a public API. All the methods
192 provided by the class are considered an implementation detail.
193 """
194
195 def __init__(self,
196 prog,
197 indent_increment=2,
198 max_help_position=24,
199 width=None):
200
201 # default setting for width
202 if width is None:
203 try:
204 width = int(_os.environ['COLUMNS'])
205 except (KeyError, ValueError):
206 width = 80
207 width -= 2
208
209 self._prog = prog
210 self._indent_increment = indent_increment
211 self._max_help_position = max_help_position
212 self._width = width
213
214 self._current_indent = 0
215 self._level = 0
216 self._action_max_length = 0
217
218 self._root_section = self._Section(self, None)
219 self._current_section = self._root_section
220
221 self._whitespace_matcher = _re.compile(r'\s+')
222 self._long_break_matcher = _re.compile(r'\n\n\n+')
223
224 # ===============================
225 # Section and indentation methods
226 # ===============================
227 def _indent(self):
228 self._current_indent += self._indent_increment
229 self._level += 1
230
231 def _dedent(self):
232 self._current_indent -= self._indent_increment
233 assert self._current_indent >= 0, 'Indent decreased below 0.'
234 self._level -= 1
235
236 class _Section(object):
237
238 def __init__(self, formatter, parent, heading=None):
239 self.formatter = formatter
240 self.parent = parent
241 self.heading = heading
242 self.items = []
243
244 def format_help(self):
245 # format the indented section
246 if self.parent is not None:
247 self.formatter._indent()
248 join = self.formatter._join_parts
249 for func, args in self.items:
250 func(*args)
251 item_help = join([func(*args) for func, args in self.items])
252 if self.parent is not None:
253 self.formatter._dedent()
254
255 # return nothing if the section was empty
256 if not item_help:
257 return ''
258
259 # add the heading if the section was non-empty
260 if self.heading is not SUPPRESS and self.heading is not None:
261 current_indent = self.formatter._current_indent
262 heading = '%*s%s:\n' % (current_indent, '', self.heading)
263 else:
264 heading = ''
265
266 # join the section-initial newline, the heading and the help
267 return join(['\n', heading, item_help, '\n'])
268
269 def _add_item(self, func, args):
270 self._current_section.items.append((func, args))
271
272 # ========================
273 # Message building methods
274 # ========================
275 def start_section(self, heading):
276 self._indent()
277 section = self._Section(self, self._current_section, heading)
278 self._add_item(section.format_help, [])
279 self._current_section = section
280
281 def end_section(self):
282 self._current_section = self._current_section.parent
283 self._dedent()
284
285 def add_text(self, text):
286 if text is not SUPPRESS and text is not None:
287 self._add_item(self._format_text, [text])
288
289 def add_usage(self, usage, actions, groups, prefix=None):
290 if usage is not SUPPRESS:
291 args = usage, actions, groups, prefix
292 self._add_item(self._format_usage, args)
293
294 def add_argument(self, action):
295 if action.help is not SUPPRESS:
296
297 # find all invocations
298 get_invocation = self._format_action_invocation
299 invocations = [get_invocation(action)]
300 for subaction in self._iter_indented_subactions(action):
301 invocations.append(get_invocation(subaction))
302
303 # update the maximum item length
304 invocation_length = max([len(s) for s in invocations])
305 action_length = invocation_length + self._current_indent
306 self._action_max_length = max(self._action_max_length,
307 action_length)
308
309 # add the item to the list
310 self._add_item(self._format_action, [action])
311
312 def add_arguments(self, actions):
313 for action in actions:
314 self.add_argument(action)
315
316 # =======================
317 # Help-formatting methods
318 # =======================
319 def format_help(self):
320 help = self._root_section.format_help()
321 if help:
322 help = self._long_break_matcher.sub('\n\n', help)
323 help = help.strip('\n') + '\n'
324 return help
325
326 def _join_parts(self, part_strings):
327 return ''.join([part
328 for part in part_strings
329 if part and part is not SUPPRESS])
330
331 def _format_usage(self, usage, actions, groups, prefix):
332 if prefix is None:
333 prefix = _('usage: ')
334
335 # if usage is specified, use that
336 if usage is not None:
337 usage = usage % dict(prog=self._prog)
338
339 # if no optionals or positionals are available, usage is just prog
340 elif usage is None and not actions:
341 usage = '%(prog)s' % dict(prog=self._prog)
342
343 # if optionals and positionals are available, calculate usage
344 elif usage is None:
345 prog = '%(prog)s' % dict(prog=self._prog)
346
347 # split optionals from positionals
348 optionals = []
349 positionals = []
350 for action in actions:
351 if action.option_strings:
352 optionals.append(action)
353 else:
354 positionals.append(action)
355
356 # build full usage string
357 format = self._format_actions_usage
358 action_usage = format(optionals + positionals, groups)
359 usage = ' '.join([s for s in [prog, action_usage] if s])
360
361 # wrap the usage parts if it's too long
362 text_width = self._width - self._current_indent
363 if len(prefix) + len(usage) > text_width:
364
365 # break usage into wrappable parts
366 part_regexp = r'\(.*?\)+|\[.*?\]+|\S+'
367 opt_usage = format(optionals, groups)
368 pos_usage = format(positionals, groups)
369 opt_parts = _re.findall(part_regexp, opt_usage)
370 pos_parts = _re.findall(part_regexp, pos_usage)
371 assert ' '.join(opt_parts) == opt_usage
372 assert ' '.join(pos_parts) == pos_usage
373
374 # helper for wrapping lines
375 def get_lines(parts, indent, prefix=None):
376 lines = []
377 line = []
378 if prefix is not None:
379 line_len = len(prefix) - 1
380 else:
381 line_len = len(indent) - 1
382 for part in parts:
383 if line_len + 1 + len(part) > text_width:
384 lines.append(indent + ' '.join(line))
385 line = []
386 line_len = len(indent) - 1
387 line.append(part)
388 line_len += len(part) + 1
389 if line:
390 lines.append(indent + ' '.join(line))
391 if prefix is not None:
392 lines[0] = lines[0][len(indent):]
393 return lines
394
395 # if prog is short, follow it with optionals or positionals
396 if len(prefix) + len(prog) <= 0.75 * text_width:
397 indent = ' ' * (len(prefix) + len(prog) + 1)
398 if opt_parts:
399 lines = get_lines([prog] + opt_parts, indent, prefix)
400 lines.extend(get_lines(pos_parts, indent))
401 elif pos_parts:
402 lines = get_lines([prog] + pos_parts, indent, prefix)
403 else:
404 lines = [prog]
405
406 # if prog is long, put it on its own line
407 else:
408 indent = ' ' * len(prefix)
409 parts = opt_parts + pos_parts
410 lines = get_lines(parts, indent)
411 if len(lines) > 1:
412 lines = []
413 lines.extend(get_lines(opt_parts, indent))
414 lines.extend(get_lines(pos_parts, indent))
415 lines = [prog] + lines
416
417 # join lines into usage
418 usage = '\n'.join(lines)
419
420 # prefix with 'usage:'
421 return '%s%s\n\n' % (prefix, usage)
422
423 def _format_actions_usage(self, actions, groups):
424 # find group indices and identify actions in groups
425 group_actions = set()
426 inserts = {}
427 for group in groups:
428 try:
429 start = actions.index(group._group_actions[0])
430 except ValueError:
431 continue
432 else:
433 end = start + len(group._group_actions)
434 if actions[start:end] == group._group_actions:
435 for action in group._group_actions:
436 group_actions.add(action)
437 if not group.required:
438 if start in inserts:
439 inserts[start] += ' ['
440 else:
441 inserts[start] = '['
442 inserts[end] = ']'
443 else:
444 if start in inserts:
445 inserts[start] += ' ('
446 else:
447 inserts[start] = '('
448 inserts[end] = ')'
449 for i in range(start + 1, end):
450 inserts[i] = '|'
451
452 # collect all actions format strings
453 parts = []
454 for i, action in enumerate(actions):
455
456 # suppressed arguments are marked with None
457 # remove | separators for suppressed arguments
458 if action.help is SUPPRESS:
459 parts.append(None)
460 if inserts.get(i) == '|':
461 inserts.pop(i)
462 elif inserts.get(i + 1) == '|':
463 inserts.pop(i + 1)
464
465 # produce all arg strings
466 elif not action.option_strings:
467 part = self._format_args(action, action.dest)
468
469 # if it's in a group, strip the outer []
470 if action in group_actions:
471 if part[0] == '[' and part[-1] == ']':
472 part = part[1:-1]
473
474 # add the action string to the list
475 parts.append(part)
476
477 # produce the first way to invoke the option in brackets
478 else:
479 option_string = action.option_strings[0]
480
481 # if the Optional doesn't take a value, format is:
482 # -s or --long
483 if action.nargs == 0:
484 part = '%s' % option_string
485
486 # if the Optional takes a value, format is:
487 # -s ARGS or --long ARGS
488 else:
489 default = action.dest.upper()
490 args_string = self._format_args(action, default)
491 part = '%s %s' % (option_string, args_string)
492
493 # make it look optional if it's not required or in a group
494 if not action.required and action not in group_actions:
495 part = '[%s]' % part
496
497 # add the action string to the list
498 parts.append(part)
499
500 # insert things at the necessary indices
501 for i in sorted(inserts, reverse=True):
502 parts[i:i] = [inserts[i]]
503
504 # join all the action items with spaces
505 text = ' '.join([item for item in parts if item is not None])
506
507 # clean up separators for mutually exclusive groups
508 open = r'[\[(]'
509 close = r'[\])]'
510 text = _re.sub(r'(%s) ' % open, r'\1', text)
511 text = _re.sub(r' (%s)' % close, r'\1', text)
512 text = _re.sub(r'%s *%s' % (open, close), r'', text)
513 text = _re.sub(r'\(([^|]*)\)', r'\1', text)
514 text = text.strip()
515
516 # return the text
517 return text
518
519 def _format_text(self, text):
520 if '%(prog)' in text:
521 text = text % dict(prog=self._prog)
522 text_width = self._width - self._current_indent
523 indent = ' ' * self._current_indent
524 return self._fill_text(text, text_width, indent) + '\n\n'
525
526 def _format_action(self, action):
527 # determine the required width and the entry label
528 help_position = min(self._action_max_length + 2,
529 self._max_help_position)
530 help_width = self._width - help_position
531 action_width = help_position - self._current_indent - 2
532 action_header = self._format_action_invocation(action)
533
534 # ho nelp; start on same line and add a final newline
535 if not action.help:
536 tup = self._current_indent, '', action_header
537 action_header = '%*s%s\n' % tup
538
539 # short action name; start on the same line and pad two spaces
540 elif len(action_header) <= action_width:
541 tup = self._current_indent, '', action_width, action_header
542 action_header = '%*s%-*s ' % tup
543 indent_first = 0
544
545 # long action name; start on the next line
546 else:
547 tup = self._current_indent, '', action_header
548 action_header = '%*s%s\n' % tup
549 indent_first = help_position
550
551 # collect the pieces of the action help
552 parts = [action_header]
553
554 # if there was help for the action, add lines of help text
555 if action.help:
556 help_text = self._expand_help(action)
557 help_lines = self._split_lines(help_text, help_width)
558 parts.append('%*s%s\n' % (indent_first, '', help_lines[0]))
559 for line in help_lines[1:]:
560 parts.append('%*s%s\n' % (help_position, '', line))
561
562 # or add a newline if the description doesn't end with one
563 elif not action_header.endswith('\n'):
564 parts.append('\n')
565
566 # if there are any sub-actions, add their help as well
567 for subaction in self._iter_indented_subactions(action):
568 parts.append(self._format_action(subaction))
569
570 # return a single string
571 return self._join_parts(parts)
572
573 def _format_action_invocation(self, action):
574 if not action.option_strings:
575 metavar, = self._metavar_formatter(action, action.dest)(1)
576 return metavar
577
578 else:
579 parts = []
580
581 # if the Optional doesn't take a value, format is:
582 # -s, --long
583 if action.nargs == 0:
584 parts.extend(action.option_strings)
585
586 # if the Optional takes a value, format is:
587 # -s ARGS, --long ARGS
588 else:
589 default = action.dest.upper()
590 args_string = self._format_args(action, default)
591 for option_string in action.option_strings:
592 parts.append('%s %s' % (option_string, args_string))
593
594 return ', '.join(parts)
595
596 def _metavar_formatter(self, action, default_metavar):
597 if action.metavar is not None:
598 result = action.metavar
599 elif action.choices is not None:
600 choice_strs = [str(choice) for choice in action.choices]
601 result = '{%s}' % ','.join(choice_strs)
602 else:
603 result = default_metavar
604
605 def format(tuple_size):
606 if isinstance(result, tuple):
607 return result
608 else:
609 return (result, ) * tuple_size
610 return format
611
612 def _format_args(self, action, default_metavar):
613 get_metavar = self._metavar_formatter(action, default_metavar)
614 if action.nargs is None:
615 result = '%s' % get_metavar(1)
616 elif action.nargs == OPTIONAL:
617 result = '[%s]' % get_metavar(1)
618 elif action.nargs == ZERO_OR_MORE:
619 result = '[%s [%s ...]]' % get_metavar(2)
620 elif action.nargs == ONE_OR_MORE:
621 result = '%s [%s ...]' % get_metavar(2)
622 elif action.nargs == REMAINDER:
623 result = '...'
624 elif action.nargs == PARSER:
625 result = '%s ...' % get_metavar(1)
626 else:
627 formats = ['%s' for _ in range(action.nargs)]
628 result = ' '.join(formats) % get_metavar(action.nargs)
629 return result
630
631 def _expand_help(self, action):
632 params = dict(vars(action), prog=self._prog)
633 for name in list(params):
634 if params[name] is SUPPRESS:
635 del params[name]
636 for name in list(params):
637 if hasattr(params[name], '__name__'):
638 params[name] = params[name].__name__
639 if params.get('choices') is not None:
640 choices_str = ', '.join([str(c) for c in params['choices']])
641 params['choices'] = choices_str
642 return self._get_help_string(action) % params
643
644 def _iter_indented_subactions(self, action):
645 try:
646 get_subactions = action._get_subactions
647 except AttributeError:
648 pass
649 else:
650 self._indent()
651 for subaction in get_subactions():
652 yield subaction
653 self._dedent()
654
655 def _split_lines(self, text, width):
656 text = self._whitespace_matcher.sub(' ', text).strip()
657 return _textwrap.wrap(text, width)
658
659 def _fill_text(self, text, width, indent):
660 text = self._whitespace_matcher.sub(' ', text).strip()
661 return _textwrap.fill(text, width, initial_indent=indent,
662 subsequent_indent=indent)
663
664 def _get_help_string(self, action):
665 return action.help
666
667
668class RawDescriptionHelpFormatter(HelpFormatter):
669 """Help message formatter which retains any formatting in descriptions.
670
671 Only the name of this class is considered a public API. All the methods
672 provided by the class are considered an implementation detail.
673 """
674
675 def _fill_text(self, text, width, indent):
676 return ''.join([indent + line for line in text.splitlines(True)])
677
678
679class RawTextHelpFormatter(RawDescriptionHelpFormatter):
680 """Help message formatter which retains formatting of all help text.
681
682 Only the name of this class is considered a public API. All the methods
683 provided by the class are considered an implementation detail.
684 """
685
686 def _split_lines(self, text, width):
687 return text.splitlines()
688
689
690class ArgumentDefaultsHelpFormatter(HelpFormatter):
691 """Help message formatter which adds default values to argument help.
692
693 Only the name of this class is considered a public API. All the methods
694 provided by the class are considered an implementation detail.
695 """
696
697 def _get_help_string(self, action):
698 help = action.help
699 if '%(default)' not in action.help:
700 if action.default is not SUPPRESS:
701 defaulting_nargs = [OPTIONAL, ZERO_OR_MORE]
702 if action.option_strings or action.nargs in defaulting_nargs:
703 help += ' (default: %(default)s)'
704 return help
705
706
707# =====================
708# Options and Arguments
709# =====================
710
711def _get_action_name(argument):
712 if argument is None:
713 return None
714 elif argument.option_strings:
715 return '/'.join(argument.option_strings)
716 elif argument.metavar not in (None, SUPPRESS):
717 return argument.metavar
718 elif argument.dest not in (None, SUPPRESS):
719 return argument.dest
720 else:
721 return None
722
723
724class ArgumentError(Exception):
725 """An error from creating or using an argument (optional or positional).
726
727 The string value of this exception is the message, augmented with
728 information about the argument that caused it.
729 """
730
731 def __init__(self, argument, message):
732 self.argument_name = _get_action_name(argument)
733 self.message = message
734
735 def __str__(self):
736 if self.argument_name is None:
737 format = '%(message)s'
738 else:
739 format = 'argument %(argument_name)s: %(message)s'
740 return format % dict(message=self.message,
741 argument_name=self.argument_name)
742
743
744class ArgumentTypeError(Exception):
745 """An error from trying to convert a command line string to a type."""
746 pass
747
748
749# ==============
750# Action classes
751# ==============
752
753class Action(_AttributeHolder):
754 """Information about how to convert command line strings to Python objects.
755
756 Action objects are used by an ArgumentParser to represent the information
757 needed to parse a single argument from one or more strings from the
758 command line. The keyword arguments to the Action constructor are also
759 all attributes of Action instances.
760
761 Keyword Arguments:
762
763 - option_strings -- A list of command-line option strings which
764 should be associated with this action.
765
766 - dest -- The name of the attribute to hold the created object(s)
767
768 - nargs -- The number of command-line arguments that should be
769 consumed. By default, one argument will be consumed and a single
770 value will be produced. Other values include:
771 - N (an integer) consumes N arguments (and produces a list)
772 - '?' consumes zero or one arguments
773 - '*' consumes zero or more arguments (and produces a list)
774 - '+' consumes one or more arguments (and produces a list)
775 Note that the difference between the default and nargs=1 is that
776 with the default, a single value will be produced, while with
777 nargs=1, a list containing a single value will be produced.
778
779 - const -- The value to be produced if the option is specified and the
780 option uses an action that takes no values.
781
782 - default -- The value to be produced if the option is not specified.
783
784 - type -- The type which the command-line arguments should be converted
785 to, should be one of 'string', 'int', 'float', 'complex' or a
786 callable object that accepts a single string argument. If None,
787 'string' is assumed.
788
789 - choices -- A container of values that should be allowed. If not None,
790 after a command-line argument has been converted to the appropriate
791 type, an exception will be raised if it is not a member of this
792 collection.
793
794 - required -- True if the action must always be specified at the
795 command line. This is only meaningful for optional command-line
796 arguments.
797
798 - help -- The help string describing the argument.
799
800 - metavar -- The name to be used for the option's argument with the
801 help string. If None, the 'dest' value will be used as the name.
802 """
803
804 def __init__(self,
805 option_strings,
806 dest,
807 nargs=None,
808 const=None,
809 default=None,
810 type=None,
811 choices=None,
812 required=False,
813 help=None,
814 metavar=None):
815 self.option_strings = option_strings
816 self.dest = dest
817 self.nargs = nargs
818 self.const = const
819 self.default = default
820 self.type = type
821 self.choices = choices
822 self.required = required
823 self.help = help
824 self.metavar = metavar
825
826 def _get_kwargs(self):
827 names = [
828 'option_strings',
829 'dest',
830 'nargs',
831 'const',
832 'default',
833 'type',
834 'choices',
835 'help',
836 'metavar',
837 ]
838 return [(name, getattr(self, name)) for name in names]
839
840 def __call__(self, parser, namespace, values, option_string=None):
841 raise NotImplementedError(_('.__call__() not defined'))
842
843
844class _StoreAction(Action):
845
846 def __init__(self,
847 option_strings,
848 dest,
849 nargs=None,
850 const=None,
851 default=None,
852 type=None,
853 choices=None,
854 required=False,
855 help=None,
856 metavar=None):
857 if nargs == 0:
858 raise ValueError('nargs for store actions must be > 0; if you '
859 'have nothing to store, actions such as store '
860 'true or store const may be more appropriate')
861 if const is not None and nargs != OPTIONAL:
862 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
863 super(_StoreAction, self).__init__(
864 option_strings=option_strings,
865 dest=dest,
866 nargs=nargs,
867 const=const,
868 default=default,
869 type=type,
870 choices=choices,
871 required=required,
872 help=help,
873 metavar=metavar)
874
875 def __call__(self, parser, namespace, values, option_string=None):
876 setattr(namespace, self.dest, values)
877
878
879class _StoreConstAction(Action):
880
881 def __init__(self,
882 option_strings,
883 dest,
884 const,
885 default=None,
886 required=False,
887 help=None,
888 metavar=None):
889 super(_StoreConstAction, self).__init__(
890 option_strings=option_strings,
891 dest=dest,
892 nargs=0,
893 const=const,
894 default=default,
895 required=required,
896 help=help)
897
898 def __call__(self, parser, namespace, values, option_string=None):
899 setattr(namespace, self.dest, self.const)
900
901
902class _StoreTrueAction(_StoreConstAction):
903
904 def __init__(self,
905 option_strings,
906 dest,
907 default=False,
908 required=False,
909 help=None):
910 super(_StoreTrueAction, self).__init__(
911 option_strings=option_strings,
912 dest=dest,
913 const=True,
914 default=default,
915 required=required,
916 help=help)
917
918
919class _StoreFalseAction(_StoreConstAction):
920
921 def __init__(self,
922 option_strings,
923 dest,
924 default=True,
925 required=False,
926 help=None):
927 super(_StoreFalseAction, self).__init__(
928 option_strings=option_strings,
929 dest=dest,
930 const=False,
931 default=default,
932 required=required,
933 help=help)
934
935
936class _AppendAction(Action):
937
938 def __init__(self,
939 option_strings,
940 dest,
941 nargs=None,
942 const=None,
943 default=None,
944 type=None,
945 choices=None,
946 required=False,
947 help=None,
948 metavar=None):
949 if nargs == 0:
950 raise ValueError('nargs for append actions must be > 0; if arg '
951 'strings are not supplying the value to append, '
952 'the append const action may be more appropriate')
953 if const is not None and nargs != OPTIONAL:
954 raise ValueError('nargs must be %r to supply const' % OPTIONAL)
955 super(_AppendAction, self).__init__(
956 option_strings=option_strings,
957 dest=dest,
958 nargs=nargs,
959 const=const,
960 default=default,
961 type=type,
962 choices=choices,
963 required=required,
964 help=help,
965 metavar=metavar)
966
967 def __call__(self, parser, namespace, values, option_string=None):
968 items = _copy.copy(_ensure_value(namespace, self.dest, []))
969 items.append(values)
970 setattr(namespace, self.dest, items)
971
972
973class _AppendConstAction(Action):
974
975 def __init__(self,
976 option_strings,
977 dest,
978 const,
979 default=None,
980 required=False,
981 help=None,
982 metavar=None):
983 super(_AppendConstAction, self).__init__(
984 option_strings=option_strings,
985 dest=dest,
986 nargs=0,
987 const=const,
988 default=default,
989 required=required,
990 help=help,
991 metavar=metavar)
992
993 def __call__(self, parser, namespace, values, option_string=None):
994 items = _copy.copy(_ensure_value(namespace, self.dest, []))
995 items.append(self.const)
996 setattr(namespace, self.dest, items)
997
998
999class _CountAction(Action):
1000
1001 def __init__(self,
1002 option_strings,
1003 dest,
1004 default=None,
1005 required=False,
1006 help=None):
1007 super(_CountAction, self).__init__(
1008 option_strings=option_strings,
1009 dest=dest,
1010 nargs=0,
1011 default=default,
1012 required=required,
1013 help=help)
1014
1015 def __call__(self, parser, namespace, values, option_string=None):
1016 new_count = _ensure_value(namespace, self.dest, 0) + 1
1017 setattr(namespace, self.dest, new_count)
1018
1019
1020class _HelpAction(Action):
1021
1022 def __init__(self,
1023 option_strings,
1024 dest=SUPPRESS,
1025 default=SUPPRESS,
1026 help=None):
1027 super(_HelpAction, self).__init__(
1028 option_strings=option_strings,
1029 dest=dest,
1030 default=default,
1031 nargs=0,
1032 help=help)
1033
1034 def __call__(self, parser, namespace, values, option_string=None):
1035 parser.print_help()
1036 parser.exit()
1037
1038
1039class _VersionAction(Action):
1040
1041 def __init__(self,
1042 option_strings,
1043 version=None,
1044 dest=SUPPRESS,
1045 default=SUPPRESS,
1046 help="show program's version number and exit"):
1047 super(_VersionAction, self).__init__(
1048 option_strings=option_strings,
1049 dest=dest,
1050 default=default,
1051 nargs=0,
1052 help=help)
1053 self.version = version
1054
1055 def __call__(self, parser, namespace, values, option_string=None):
1056 version = self.version
1057 if version is None:
1058 version = parser.version
1059 formatter = parser._get_formatter()
1060 formatter.add_text(version)
1061 parser.exit(message=formatter.format_help())
1062
1063
1064class _SubParsersAction(Action):
1065
1066 class _ChoicesPseudoAction(Action):
1067
1068 def __init__(self, name, aliases, help):
1069 metavar = dest = name
1070 if aliases:
1071 metavar += ' (%s)' % ', '.join(aliases)
1072 sup = super(_SubParsersAction._ChoicesPseudoAction, self)
1073 sup.__init__(option_strings=[], dest=dest, help=help,
1074 metavar=metavar)
1075
1076 def __init__(self,
1077 option_strings,
1078 prog,
1079 parser_class,
1080 dest=SUPPRESS,
1081 help=None,
1082 metavar=None):
1083
1084 self._prog_prefix = prog
1085 self._parser_class = parser_class
1086 self._name_parser_map = {}
1087 self._choices_actions = []
1088
1089 super(_SubParsersAction, self).__init__(
1090 option_strings=option_strings,
1091 dest=dest,
1092 nargs=PARSER,
1093 choices=self._name_parser_map,
1094 help=help,
1095 metavar=metavar)
1096
1097 def add_parser(self, name, **kwargs):
1098 # set prog from the existing prefix
1099 if kwargs.get('prog') is None:
1100 kwargs['prog'] = '%s %s' % (self._prog_prefix, name)
1101
1102 aliases = kwargs.pop('aliases', ())
1103
1104 # create a pseudo-action to hold the choice help
1105 if 'help' in kwargs:
1106 help = kwargs.pop('help')
1107 choice_action = self._ChoicesPseudoAction(name, aliases, help)
1108 self._choices_actions.append(choice_action)
1109
1110 # create the parser and add it to the map
1111 parser = self._parser_class(**kwargs)
1112 self._name_parser_map[name] = parser
1113
1114 # make parser available under aliases also
1115 for alias in aliases:
1116 self._name_parser_map[alias] = parser
1117
1118 return parser
1119
1120 def _get_subactions(self):
1121 return self._choices_actions
1122
1123 def __call__(self, parser, namespace, values, option_string=None):
1124 parser_name = values[0]
1125 arg_strings = values[1:]
1126
1127 # set the parser name if requested
1128 if self.dest is not SUPPRESS:
1129 setattr(namespace, self.dest, parser_name)
1130
1131 # select the parser
1132 try:
1133 parser = self._name_parser_map[parser_name]
1134 except KeyError:
1135 tup = parser_name, ', '.join(self._name_parser_map)
1136 msg = _('unknown parser %r (choices: %s)' % tup)
1137 raise ArgumentError(self, msg)
1138
1139 # parse all the remaining options into the namespace
1140 # store any unrecognized options on the object, so that the top
1141 # level parser can decide what to do with them
1142 namespace, arg_strings = parser.parse_known_args(arg_strings, namespace)
1143 if arg_strings:
1144 vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, [])
1145 getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings)
1146
1147
1148# ==============
1149# Type classes
1150# ==============
1151
1152class FileType(object):
1153 """Factory for creating file object types
1154
1155 Instances of FileType are typically passed as type= arguments to the
1156 ArgumentParser add_argument() method.
1157
1158 Keyword Arguments:
1159 - mode -- A string indicating how the file is to be opened. Accepts the
1160 same values as the builtin open() function.
1161 - bufsize -- The file's desired buffer size. Accepts the same values as
1162 the builtin open() function.
1163 """
1164
1165 def __init__(self, mode='r', bufsize=None):
1166 self._mode = mode
1167 self._bufsize = bufsize
1168
1169 def __call__(self, string):
1170 # the special argument "-" means sys.std{in,out}
1171 if string == '-':
1172 if 'r' in self._mode:
1173 return _sys.stdin
1174 elif 'w' in self._mode:
1175 return _sys.stdout
1176 else:
1177 msg = _('argument "-" with mode %r' % self._mode)
1178 raise ValueError(msg)
1179
1180 try:
1181 # all other arguments are used as file names
1182 if self._bufsize:
1183 return open(string, self._mode, self._bufsize)
1184 else:
1185 return open(string, self._mode)
1186 except IOError:
1187 err = _sys.exc_info()[1]
1188 message = _("can't open '%s': %s")
1189 raise ArgumentTypeError(message % (string, err))
1190
1191 def __repr__(self):
1192 args = [self._mode, self._bufsize]
1193 args_str = ', '.join([repr(arg) for arg in args if arg is not None])
1194 return '%s(%s)' % (type(self).__name__, args_str)
1195
1196# ===========================
1197# Optional and Positional Parsing
1198# ===========================
1199
1200class Namespace(_AttributeHolder):
1201 """Simple object for storing attributes.
1202
1203 Implements equality by attribute names and values, and provides a simple
1204 string representation.
1205 """
1206
1207 def __init__(self, **kwargs):
1208 for name in kwargs:
1209 setattr(self, name, kwargs[name])
1210
1211 __hash__ = None
1212
1213 def __eq__(self, other):
1214 return vars(self) == vars(other)
1215
1216 def __ne__(self, other):
1217 return not (self == other)
1218
1219 def __contains__(self, key):
1220 return key in self.__dict__
1221
1222
1223class _ActionsContainer(object):
1224
1225 def __init__(self,
1226 description,
1227 prefix_chars,
1228 argument_default,
1229 conflict_handler):
1230 super(_ActionsContainer, self).__init__()
1231
1232 self.description = description
1233 self.argument_default = argument_default
1234 self.prefix_chars = prefix_chars
1235 self.conflict_handler = conflict_handler
1236
1237 # set up registries
1238 self._registries = {}
1239
1240 # register actions
1241 self.register('action', None, _StoreAction)
1242 self.register('action', 'store', _StoreAction)
1243 self.register('action', 'store_const', _StoreConstAction)
1244 self.register('action', 'store_true', _StoreTrueAction)
1245 self.register('action', 'store_false', _StoreFalseAction)
1246 self.register('action', 'append', _AppendAction)
1247 self.register('action', 'append_const', _AppendConstAction)
1248 self.register('action', 'count', _CountAction)
1249 self.register('action', 'help', _HelpAction)
1250 self.register('action', 'version', _VersionAction)
1251 self.register('action', 'parsers', _SubParsersAction)
1252
1253 # raise an exception if the conflict handler is invalid
1254 self._get_handler()
1255
1256 # action storage
1257 self._actions = []
1258 self._option_string_actions = {}
1259
1260 # groups
1261 self._action_groups = []
1262 self._mutually_exclusive_groups = []
1263
1264 # defaults storage
1265 self._defaults = {}
1266
1267 # determines whether an "option" looks like a negative number
1268 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$')
1269
1270 # whether or not there are any optionals that look like negative
1271 # numbers -- uses a list so it can be shared and edited
1272 self._has_negative_number_optionals = []
1273
1274 # ====================
1275 # Registration methods
1276 # ====================
1277 def register(self, registry_name, value, object):
1278 registry = self._registries.setdefault(registry_name, {})
1279 registry[value] = object
1280
1281 def _registry_get(self, registry_name, value, default=None):
1282 return self._registries[registry_name].get(value, default)
1283
1284 # ==================================
1285 # Namespace default accessor methods
1286 # ==================================
1287 def set_defaults(self, **kwargs):
1288 self._defaults.update(kwargs)
1289
1290 # if these defaults match any existing arguments, replace
1291 # the previous default on the object with the new one
1292 for action in self._actions:
1293 if action.dest in kwargs:
1294 action.default = kwargs[action.dest]
1295
1296 def get_default(self, dest):
1297 for action in self._actions:
1298 if action.dest == dest and action.default is not None:
1299 return action.default
1300 return self._defaults.get(dest, None)
1301
1302
1303 # =======================
1304 # Adding argument actions
1305 # =======================
1306 def add_argument(self, *args, **kwargs):
1307 """
1308 add_argument(dest, ..., name=value, ...)
1309 add_argument(option_string, option_string, ..., name=value, ...)
1310 """
1311
1312 # if no positional args are supplied or only one is supplied and
1313 # it doesn't look like an option string, parse a positional
1314 # argument
1315 chars = self.prefix_chars
1316 if not args or len(args) == 1 and args[0][0] not in chars:
1317 if args and 'dest' in kwargs:
1318 raise ValueError('dest supplied twice for positional argument')
1319 kwargs = self._get_positional_kwargs(*args, **kwargs)
1320
1321 # otherwise, we're adding an optional argument
1322 else:
1323 kwargs = self._get_optional_kwargs(*args, **kwargs)
1324
1325 # if no default was supplied, use the parser-level default
1326 if 'default' not in kwargs:
1327 dest = kwargs['dest']
1328 if dest in self._defaults:
1329 kwargs['default'] = self._defaults[dest]
1330 elif self.argument_default is not None:
1331 kwargs['default'] = self.argument_default
1332
1333 # create the action object, and add it to the parser
1334 action_class = self._pop_action_class(kwargs)
1335 if not _callable(action_class):
1336 raise ValueError('unknown action "%s"' % action_class)
1337 action = action_class(**kwargs)
1338
1339 # raise an error if the action type is not callable
1340 type_func = self._registry_get('type', action.type, action.type)
1341 if not _callable(type_func):
1342 raise ValueError('%r is not callable' % type_func)
1343
1344 return self._add_action(action)
1345
1346 def add_argument_group(self, *args, **kwargs):
1347 group = _ArgumentGroup(self, *args, **kwargs)
1348 self._action_groups.append(group)
1349 return group
1350
1351 def add_mutually_exclusive_group(self, **kwargs):
1352 group = _MutuallyExclusiveGroup(self, **kwargs)
1353 self._mutually_exclusive_groups.append(group)
1354 return group
1355
1356 def _add_action(self, action):
1357 # resolve any conflicts
1358 self._check_conflict(action)
1359
1360 # add to actions list
1361 self._actions.append(action)
1362 action.container = self
1363
1364 # index the action by any option strings it has
1365 for option_string in action.option_strings:
1366 self._option_string_actions[option_string] = action
1367
1368 # set the flag if any option strings look like negative numbers
1369 for option_string in action.option_strings:
1370 if self._negative_number_matcher.match(option_string):
1371 if not self._has_negative_number_optionals:
1372 self._has_negative_number_optionals.append(True)
1373
1374 # return the created action
1375 return action
1376
1377 def _remove_action(self, action):
1378 self._actions.remove(action)
1379
1380 def _add_container_actions(self, container):
1381 # collect groups by titles
1382 title_group_map = {}
1383 for group in self._action_groups:
1384 if group.title in title_group_map:
1385 msg = _('cannot merge actions - two groups are named %r')
1386 raise ValueError(msg % (group.title))
1387 title_group_map[group.title] = group
1388
1389 # map each action to its group
1390 group_map = {}
1391 for group in container._action_groups:
1392
1393 # if a group with the title exists, use that, otherwise
1394 # create a new group matching the container's group
1395 if group.title not in title_group_map:
1396 title_group_map[group.title] = self.add_argument_group(
1397 title=group.title,
1398 description=group.description,
1399 conflict_handler=group.conflict_handler)
1400
1401 # map the actions to their new group
1402 for action in group._group_actions:
1403 group_map[action] = title_group_map[group.title]
1404
1405 # add container's mutually exclusive groups
1406 # NOTE: if add_mutually_exclusive_group ever gains title= and
1407 # description= then this code will need to be expanded as above
1408 for group in container._mutually_exclusive_groups:
1409 mutex_group = self.add_mutually_exclusive_group(
1410 required=group.required)
1411
1412 # map the actions to their new mutex group
1413 for action in group._group_actions:
1414 group_map[action] = mutex_group
1415
1416 # add all actions to this container or their group
1417 for action in container._actions:
1418 group_map.get(action, self)._add_action(action)
1419
1420 def _get_positional_kwargs(self, dest, **kwargs):
1421 # make sure required is not specified
1422 if 'required' in kwargs:
1423 msg = _("'required' is an invalid argument for positionals")
1424 raise TypeError(msg)
1425
1426 # mark positional arguments as required if at least one is
1427 # always required
1428 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]:
1429 kwargs['required'] = True
1430 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs:
1431 kwargs['required'] = True
1432
1433 # return the keyword arguments with no option strings
1434 return dict(kwargs, dest=dest, option_strings=[])
1435
1436 def _get_optional_kwargs(self, *args, **kwargs):
1437 # determine short and long option strings
1438 option_strings = []
1439 long_option_strings = []
1440 for option_string in args:
1441 # error on strings that don't start with an appropriate prefix
1442 if not option_string[0] in self.prefix_chars:
1443 msg = _('invalid option string %r: '
1444 'must start with a character %r')
1445 tup = option_string, self.prefix_chars
1446 raise ValueError(msg % tup)
1447
1448 # strings starting with two prefix characters are long options
1449 option_strings.append(option_string)
1450 if option_string[0] in self.prefix_chars:
1451 if len(option_string) > 1:
1452 if option_string[1] in self.prefix_chars:
1453 long_option_strings.append(option_string)
1454
1455 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
1456 dest = kwargs.pop('dest', None)
1457 if dest is None:
1458 if long_option_strings:
1459 dest_option_string = long_option_strings[0]
1460 else:
1461 dest_option_string = option_strings[0]
1462 dest = dest_option_string.lstrip(self.prefix_chars)
1463 if not dest:
1464 msg = _('dest= is required for options like %r')
1465 raise ValueError(msg % option_string)
1466 dest = dest.replace('-', '_')
1467
1468 # return the updated keyword arguments
1469 return dict(kwargs, dest=dest, option_strings=option_strings)
1470
1471 def _pop_action_class(self, kwargs, default=None):
1472 action = kwargs.pop('action', default)
1473 return self._registry_get('action', action, action)
1474
1475 def _get_handler(self):
1476 # determine function from conflict handler string
1477 handler_func_name = '_handle_conflict_%s' % self.conflict_handler
1478 try:
1479 return getattr(self, handler_func_name)
1480 except AttributeError:
1481 msg = _('invalid conflict_resolution value: %r')
1482 raise ValueError(msg % self.conflict_handler)
1483
1484 def _check_conflict(self, action):
1485
1486 # find all options that conflict with this option
1487 confl_optionals = []
1488 for option_string in action.option_strings:
1489 if option_string in self._option_string_actions:
1490 confl_optional = self._option_string_actions[option_string]
1491 confl_optionals.append((option_string, confl_optional))
1492
1493 # resolve any conflicts
1494 if confl_optionals:
1495 conflict_handler = self._get_handler()
1496 conflict_handler(action, confl_optionals)
1497
1498 def _handle_conflict_error(self, action, conflicting_actions):
1499 message = _('conflicting option string(s): %s')
1500 conflict_string = ', '.join([option_string
1501 for option_string, action
1502 in conflicting_actions])
1503 raise ArgumentError(action, message % conflict_string)
1504
1505 def _handle_conflict_resolve(self, action, conflicting_actions):
1506
1507 # remove all conflicting options
1508 for option_string, action in conflicting_actions:
1509
1510 # remove the conflicting option
1511 action.option_strings.remove(option_string)
1512 self._option_string_actions.pop(option_string, None)
1513
1514 # if the option now has no option string, remove it from the
1515 # container holding it
1516 if not action.option_strings:
1517 action.container._remove_action(action)
1518
1519
1520class _ArgumentGroup(_ActionsContainer):
1521
1522 def __init__(self, container, title=None, description=None, **kwargs):
1523 # add any missing keyword arguments by checking the container
1524 update = kwargs.setdefault
1525 update('conflict_handler', container.conflict_handler)
1526 update('prefix_chars', container.prefix_chars)
1527 update('argument_default', container.argument_default)
1528 super_init = super(_ArgumentGroup, self).__init__
1529 super_init(description=description, **kwargs)
1530
1531 # group attributes
1532 self.title = title
1533 self._group_actions = []
1534
1535 # share most attributes with the container
1536 self._registries = container._registries
1537 self._actions = container._actions
1538 self._option_string_actions = container._option_string_actions
1539 self._defaults = container._defaults
1540 self._has_negative_number_optionals = \
1541 container._has_negative_number_optionals
1542
1543 def _add_action(self, action):
1544 action = super(_ArgumentGroup, self)._add_action(action)
1545 self._group_actions.append(action)
1546 return action
1547
1548 def _remove_action(self, action):
1549 super(_ArgumentGroup, self)._remove_action(action)
1550 self._group_actions.remove(action)
1551
1552
1553class _MutuallyExclusiveGroup(_ArgumentGroup):
1554
1555 def __init__(self, container, required=False):
1556 super(_MutuallyExclusiveGroup, self).__init__(container)
1557 self.required = required
1558 self._container = container
1559
1560 def _add_action(self, action):
1561 if action.required:
1562 msg = _('mutually exclusive arguments must be optional')
1563 raise ValueError(msg)
1564 action = self._container._add_action(action)
1565 self._group_actions.append(action)
1566 return action
1567
1568 def _remove_action(self, action):
1569 self._container._remove_action(action)
1570 self._group_actions.remove(action)
1571
1572
1573class ArgumentParser(_AttributeHolder, _ActionsContainer):
1574 """Object for parsing command line strings into Python objects.
1575
1576 Keyword Arguments:
1577 - prog -- The name of the program (default: sys.argv[0])
1578 - usage -- A usage message (default: auto-generated from arguments)
1579 - description -- A description of what the program does
1580 - epilog -- Text following the argument descriptions
1581 - parents -- Parsers whose arguments should be copied into this one
1582 - formatter_class -- HelpFormatter class for printing help messages
1583 - prefix_chars -- Characters that prefix optional arguments
1584 - fromfile_prefix_chars -- Characters that prefix files containing
1585 additional arguments
1586 - argument_default -- The default value for all arguments
1587 - conflict_handler -- String indicating how to handle conflicts
1588 - add_help -- Add a -h/-help option
1589 """
1590
1591 def __init__(self,
1592 prog=None,
1593 usage=None,
1594 description=None,
1595 epilog=None,
1596 version=None,
1597 parents=[],
1598 formatter_class=HelpFormatter,
1599 prefix_chars='-',
1600 fromfile_prefix_chars=None,
1601 argument_default=None,
1602 conflict_handler='error',
1603 add_help=True):
1604
1605 if version is not None:
1606 import warnings
1607 warnings.warn(
1608 """The "version" argument to ArgumentParser is deprecated. """
1609 """Please use """
1610 """"add_argument(..., action='version', version="N", ...)" """
1611 """instead""", DeprecationWarning)
1612
1613 superinit = super(ArgumentParser, self).__init__
1614 superinit(description=description,
1615 prefix_chars=prefix_chars,
1616 argument_default=argument_default,
1617 conflict_handler=conflict_handler)
1618
1619 # default setting for prog
1620 if prog is None:
1621 prog = _os.path.basename(_sys.argv[0])
1622
1623 self.prog = prog
1624 self.usage = usage
1625 self.epilog = epilog
1626 self.version = version
1627 self.formatter_class = formatter_class
1628 self.fromfile_prefix_chars = fromfile_prefix_chars
1629 self.add_help = add_help
1630
1631 add_group = self.add_argument_group
1632 self._positionals = add_group(_('positional arguments'))
1633 self._optionals = add_group(_('optional arguments'))
1634 self._subparsers = None
1635
1636 # register types
1637 def identity(string):
1638 return string
1639 self.register('type', None, identity)
1640
1641 # add help and version arguments if necessary
1642 # (using explicit default to override global argument_default)
1643 if '-' in prefix_chars:
1644 default_prefix = '-'
1645 else:
1646 default_prefix = prefix_chars[0]
1647 if self.add_help:
1648 self.add_argument(
1649 default_prefix+'h', default_prefix*2+'help',
1650 action='help', default=SUPPRESS,
1651 help=_('show this help message and exit'))
1652 if self.version:
1653 self.add_argument(
1654 default_prefix+'v', default_prefix*2+'version',
1655 action='version', default=SUPPRESS,
1656 version=self.version,
1657 help=_("show program's version number and exit"))
1658
1659 # add parent arguments and defaults
1660 for parent in parents:
1661 self._add_container_actions(parent)
1662 try:
1663 defaults = parent._defaults
1664 except AttributeError:
1665 pass
1666 else:
1667 self._defaults.update(defaults)
1668
1669 # =======================
1670 # Pretty __repr__ methods
1671 # =======================
1672 def _get_kwargs(self):
1673 names = [
1674 'prog',
1675 'usage',
1676 'description',
1677 'version',
1678 'formatter_class',
1679 'conflict_handler',
1680 'add_help',
1681 ]
1682 return [(name, getattr(self, name)) for name in names]
1683
1684 # ==================================
1685 # Optional/Positional adding methods
1686 # ==================================
1687 def add_subparsers(self, **kwargs):
1688 if self._subparsers is not None:
1689 self.error(_('cannot have multiple subparser arguments'))
1690
1691 # add the parser class to the arguments if it's not present
1692 kwargs.setdefault('parser_class', type(self))
1693
1694 if 'title' in kwargs or 'description' in kwargs:
1695 title = _(kwargs.pop('title', 'subcommands'))
1696 description = _(kwargs.pop('description', None))
1697 self._subparsers = self.add_argument_group(title, description)
1698 else:
1699 self._subparsers = self._positionals
1700
1701 # prog defaults to the usage message of this parser, skipping
1702 # optional arguments and with no "usage:" prefix
1703 if kwargs.get('prog') is None:
1704 formatter = self._get_formatter()
1705 positionals = self._get_positional_actions()
1706 groups = self._mutually_exclusive_groups
1707 formatter.add_usage(self.usage, positionals, groups, '')
1708 kwargs['prog'] = formatter.format_help().strip()
1709
1710 # create the parsers action and add it to the positionals list
1711 parsers_class = self._pop_action_class(kwargs, 'parsers')
1712 action = parsers_class(option_strings=[], **kwargs)
1713 self._subparsers._add_action(action)
1714
1715 # return the created parsers action
1716 return action
1717
1718 def _add_action(self, action):
1719 if action.option_strings:
1720 self._optionals._add_action(action)
1721 else:
1722 self._positionals._add_action(action)
1723 return action
1724
1725 def _get_optional_actions(self):
1726 return [action
1727 for action in self._actions
1728 if action.option_strings]
1729
1730 def _get_positional_actions(self):
1731 return [action
1732 for action in self._actions
1733 if not action.option_strings]
1734
1735 # =====================================
1736 # Command line argument parsing methods
1737 # =====================================
1738 def parse_args(self, args=None, namespace=None):
1739 args, argv = self.parse_known_args(args, namespace)
1740 if argv:
1741 msg = _('unrecognized arguments: %s')
1742 self.error(msg % ' '.join(argv))
1743 return args
1744
1745 def parse_known_args(self, args=None, namespace=None):
1746 # args default to the system args
1747 if args is None:
1748 args = _sys.argv[1:]
1749
1750 # default Namespace built from parser defaults
1751 if namespace is None:
1752 namespace = Namespace()
1753
1754 # add any action defaults that aren't present
1755 for action in self._actions:
1756 if action.dest is not SUPPRESS:
1757 if not hasattr(namespace, action.dest):
1758 if action.default is not SUPPRESS:
1759 setattr(namespace, action.dest, action.default)
1760
1761 # add any parser defaults that aren't present
1762 for dest in self._defaults:
1763 if not hasattr(namespace, dest):
1764 setattr(namespace, dest, self._defaults[dest])
1765
1766 # parse the arguments and exit if there are any errors
1767 try:
1768 namespace, args = self._parse_known_args(args, namespace)
1769 if hasattr(namespace, _UNRECOGNIZED_ARGS_ATTR):
1770 args.extend(getattr(namespace, _UNRECOGNIZED_ARGS_ATTR))
1771 delattr(namespace, _UNRECOGNIZED_ARGS_ATTR)
1772 return namespace, args
1773 except ArgumentError:
1774 err = _sys.exc_info()[1]
1775 self.error(str(err))
1776
1777 def _parse_known_args(self, arg_strings, namespace):
1778 # replace arg strings that are file references
1779 if self.fromfile_prefix_chars is not None:
1780 arg_strings = self._read_args_from_files(arg_strings)
1781
1782 # map all mutually exclusive arguments to the other arguments
1783 # they can't occur with
1784 action_conflicts = {}
1785 for mutex_group in self._mutually_exclusive_groups:
1786 group_actions = mutex_group._group_actions
1787 for i, mutex_action in enumerate(mutex_group._group_actions):
1788 conflicts = action_conflicts.setdefault(mutex_action, [])
1789 conflicts.extend(group_actions[:i])
1790 conflicts.extend(group_actions[i + 1:])
1791
1792 # find all option indices, and determine the arg_string_pattern
1793 # which has an 'O' if there is an option at an index,
1794 # an 'A' if there is an argument, or a '-' if there is a '--'
1795 option_string_indices = {}
1796 arg_string_pattern_parts = []
1797 arg_strings_iter = iter(arg_strings)
1798 for i, arg_string in enumerate(arg_strings_iter):
1799
1800 # all args after -- are non-options
1801 if arg_string == '--':
1802 arg_string_pattern_parts.append('-')
1803 for arg_string in arg_strings_iter:
1804 arg_string_pattern_parts.append('A')
1805
1806 # otherwise, add the arg to the arg strings
1807 # and note the index if it was an option
1808 else:
1809 option_tuple = self._parse_optional(arg_string)
1810 if option_tuple is None:
1811 pattern = 'A'
1812 else:
1813 option_string_indices[i] = option_tuple
1814 pattern = 'O'
1815 arg_string_pattern_parts.append(pattern)
1816
1817 # join the pieces together to form the pattern
1818 arg_strings_pattern = ''.join(arg_string_pattern_parts)
1819
1820 # converts arg strings to the appropriate and then takes the action
1821 seen_actions = set()
1822 seen_non_default_actions = set()
1823
1824 def take_action(action, argument_strings, option_string=None):
1825 seen_actions.add(action)
1826 argument_values = self._get_values(action, argument_strings)
1827
1828 # error if this argument is not allowed with other previously
1829 # seen arguments, assuming that actions that use the default
1830 # value don't really count as "present"
1831 if argument_values is not action.default:
1832 seen_non_default_actions.add(action)
1833 for conflict_action in action_conflicts.get(action, []):
1834 if conflict_action in seen_non_default_actions:
1835 msg = _('not allowed with argument %s')
1836 action_name = _get_action_name(conflict_action)
1837 raise ArgumentError(action, msg % action_name)
1838
1839 # take the action if we didn't receive a SUPPRESS value
1840 # (e.g. from a default)
1841 if argument_values is not SUPPRESS:
1842 action(self, namespace, argument_values, option_string)
1843
1844 # function to convert arg_strings into an optional action
1845 def consume_optional(start_index):
1846
1847 # get the optional identified at this index
1848 option_tuple = option_string_indices[start_index]
1849 action, option_string, explicit_arg = option_tuple
1850
1851 # identify additional optionals in the same arg string
1852 # (e.g. -xyz is the same as -x -y -z if no args are required)
1853 match_argument = self._match_argument
1854 action_tuples = []
1855 while True:
1856
1857 # if we found no optional action, skip it
1858 if action is None:
1859 extras.append(arg_strings[start_index])
1860 return start_index + 1
1861
1862 # if there is an explicit argument, try to match the
1863 # optional's string arguments to only this
1864 if explicit_arg is not None:
1865 arg_count = match_argument(action, 'A')
1866
1867 # if the action is a single-dash option and takes no
1868 # arguments, try to parse more single-dash options out
1869 # of the tail of the option string
1870 chars = self.prefix_chars
1871 if arg_count == 0 and option_string[1] not in chars:
1872 action_tuples.append((action, [], option_string))
1873 char = option_string[0]
1874 option_string = char + explicit_arg[0]
1875 new_explicit_arg = explicit_arg[1:] or None
1876 optionals_map = self._option_string_actions
1877 if option_string in optionals_map:
1878 action = optionals_map[option_string]
1879 explicit_arg = new_explicit_arg
1880 else:
1881 msg = _('ignored explicit argument %r')
1882 raise ArgumentError(action, msg % explicit_arg)
1883
1884 # if the action expect exactly one argument, we've
1885 # successfully matched the option; exit the loop
1886 elif arg_count == 1:
1887 stop = start_index + 1
1888 args = [explicit_arg]
1889 action_tuples.append((action, args, option_string))
1890 break
1891
1892 # error if a double-dash option did not use the
1893 # explicit argument
1894 else:
1895 msg = _('ignored explicit argument %r')
1896 raise ArgumentError(action, msg % explicit_arg)
1897
1898 # if there is no explicit argument, try to match the
1899 # optional's string arguments with the following strings
1900 # if successful, exit the loop
1901 else:
1902 start = start_index + 1
1903 selected_patterns = arg_strings_pattern[start:]
1904 arg_count = match_argument(action, selected_patterns)
1905 stop = start + arg_count
1906 args = arg_strings[start:stop]
1907 action_tuples.append((action, args, option_string))
1908 break
1909
1910 # add the Optional to the list and return the index at which
1911 # the Optional's string args stopped
1912 assert action_tuples
1913 for action, args, option_string in action_tuples:
1914 take_action(action, args, option_string)
1915 return stop
1916
1917 # the list of Positionals left to be parsed; this is modified
1918 # by consume_positionals()
1919 positionals = self._get_positional_actions()
1920
1921 # function to convert arg_strings into positional actions
1922 def consume_positionals(start_index):
1923 # match as many Positionals as possible
1924 match_partial = self._match_arguments_partial
1925 selected_pattern = arg_strings_pattern[start_index:]
1926 arg_counts = match_partial(positionals, selected_pattern)
1927
1928 # slice off the appropriate arg strings for each Positional
1929 # and add the Positional and its args to the list
1930 for action, arg_count in zip(positionals, arg_counts):
1931 args = arg_strings[start_index: start_index + arg_count]
1932 start_index += arg_count
1933 take_action(action, args)
1934
1935 # slice off the Positionals that we just parsed and return the
1936 # index at which the Positionals' string args stopped
1937 positionals[:] = positionals[len(arg_counts):]
1938 return start_index
1939
1940 # consume Positionals and Optionals alternately, until we have
1941 # passed the last option string
1942 extras = []
1943 start_index = 0
1944 if option_string_indices:
1945 max_option_string_index = max(option_string_indices)
1946 else:
1947 max_option_string_index = -1
1948 while start_index <= max_option_string_index:
1949
1950 # consume any Positionals preceding the next option
1951 next_option_string_index = min([
1952 index
1953 for index in option_string_indices
1954 if index >= start_index])
1955 if start_index != next_option_string_index:
1956 positionals_end_index = consume_positionals(start_index)
1957
1958 # only try to parse the next optional if we didn't consume
1959 # the option string during the positionals parsing
1960 if positionals_end_index > start_index:
1961 start_index = positionals_end_index
1962 continue
1963 else:
1964 start_index = positionals_end_index
1965
1966 # if we consumed all the positionals we could and we're not
1967 # at the index of an option string, there were extra arguments
1968 if start_index not in option_string_indices:
1969 strings = arg_strings[start_index:next_option_string_index]
1970 extras.extend(strings)
1971 start_index = next_option_string_index
1972
1973 # consume the next optional and any arguments for it
1974 start_index = consume_optional(start_index)
1975
1976 # consume any positionals following the last Optional
1977 stop_index = consume_positionals(start_index)
1978
1979 # if we didn't consume all the argument strings, there were extras
1980 extras.extend(arg_strings[stop_index:])
1981
1982 # if we didn't use all the Positional objects, there were too few
1983 # arg strings supplied.
1984 if positionals:
1985 self.error(_('too few arguments'))
1986
1987 # make sure all required actions were present, and convert defaults.
1988 for action in self._actions:
1989 if action not in seen_actions:
1990 if action.required:
1991 name = _get_action_name(action)
1992 self.error(_('argument %s is required') % name)
1993 else:
1994 # Convert action default now instead of doing it before
1995 # parsing arguments to avoid calling convert functions
1996 # twice (which may fail) if the argument was given, but
1997 # only if it was defined already in the namespace
1998 if (action.default is not None and
1999 isinstance(action.default, basestring) and
2000 hasattr(namespace, action.dest) and
2001 action.default is getattr(namespace, action.dest)):
2002 setattr(namespace, action.dest,
2003 self._get_value(action, action.default))
2004
2005 # make sure all required groups had one option present
2006 for group in self._mutually_exclusive_groups:
2007 if group.required:
2008 for action in group._group_actions:
2009 if action in seen_non_default_actions:
2010 break
2011
2012 # if no actions were used, report the error
2013 else:
2014 names = [_get_action_name(action)
2015 for action in group._group_actions
2016 if action.help is not SUPPRESS]
2017 msg = _('one of the arguments %s is required')
2018 self.error(msg % ' '.join(names))
2019
2020 # return the updated namespace and the extra arguments
2021 return namespace, extras
2022
2023 def _read_args_from_files(self, arg_strings):
2024 # expand arguments referencing files
2025 new_arg_strings = []
2026 for arg_string in arg_strings:
2027
2028 # for regular arguments, just add them back into the list
2029 if arg_string[0] not in self.fromfile_prefix_chars:
2030 new_arg_strings.append(arg_string)
2031
2032 # replace arguments referencing files with the file content
2033 else:
2034 try:
2035 args_file = open(arg_string[1:])
2036 try:
2037 arg_strings = []
2038 for arg_line in args_file.read().splitlines():
2039 for arg in self.convert_arg_line_to_args(arg_line):
2040 arg_strings.append(arg)
2041 arg_strings = self._read_args_from_files(arg_strings)
2042 new_arg_strings.extend(arg_strings)
2043 finally:
2044 args_file.close()
2045 except IOError:
2046 err = _sys.exc_info()[1]
2047 self.error(str(err))
2048
2049 # return the modified argument list
2050 return new_arg_strings
2051
2052 def convert_arg_line_to_args(self, arg_line):
2053 return [arg_line]
2054
2055 def _match_argument(self, action, arg_strings_pattern):
2056 # match the pattern for this action to the arg strings
2057 nargs_pattern = self._get_nargs_pattern(action)
2058 match = _re.match(nargs_pattern, arg_strings_pattern)
2059
2060 # raise an exception if we weren't able to find a match
2061 if match is None:
2062 nargs_errors = {
2063 None: _('expected one argument'),
2064 OPTIONAL: _('expected at most one argument'),
2065 ONE_OR_MORE: _('expected at least one argument'),
2066 }
2067 default = _('expected %s argument(s)') % action.nargs
2068 msg = nargs_errors.get(action.nargs, default)
2069 raise ArgumentError(action, msg)
2070
2071 # return the number of arguments matched
2072 return len(match.group(1))
2073
2074 def _match_arguments_partial(self, actions, arg_strings_pattern):
2075 # progressively shorten the actions list by slicing off the
2076 # final actions until we find a match
2077 result = []
2078 for i in range(len(actions), 0, -1):
2079 actions_slice = actions[:i]
2080 pattern = ''.join([self._get_nargs_pattern(action)
2081 for action in actions_slice])
2082 match = _re.match(pattern, arg_strings_pattern)
2083 if match is not None:
2084 result.extend([len(string) for string in match.groups()])
2085 break
2086
2087 # return the list of arg string counts
2088 return result
2089
2090 def _parse_optional(self, arg_string):
2091 # if it's an empty string, it was meant to be a positional
2092 if not arg_string:
2093 return None
2094
2095 # if it doesn't start with a prefix, it was meant to be positional
2096 if not arg_string[0] in self.prefix_chars:
2097 return None
2098
2099 # if the option string is present in the parser, return the action
2100 if arg_string in self._option_string_actions:
2101 action = self._option_string_actions[arg_string]
2102 return action, arg_string, None
2103
2104 # if it's just a single character, it was meant to be positional
2105 if len(arg_string) == 1:
2106 return None
2107
2108 # if the option string before the "=" is present, return the action
2109 if '=' in arg_string:
2110 option_string, explicit_arg = arg_string.split('=', 1)
2111 if option_string in self._option_string_actions:
2112 action = self._option_string_actions[option_string]
2113 return action, option_string, explicit_arg
2114
2115 # search through all possible prefixes of the option string
2116 # and all actions in the parser for possible interpretations
2117 option_tuples = self._get_option_tuples(arg_string)
2118
2119 # if multiple actions match, the option string was ambiguous
2120 if len(option_tuples) > 1:
2121 options = ', '.join([option_string
2122 for action, option_string, explicit_arg in option_tuples])
2123 tup = arg_string, options
2124 self.error(_('ambiguous option: %s could match %s') % tup)
2125
2126 # if exactly one action matched, this segmentation is good,
2127 # so return the parsed action
2128 elif len(option_tuples) == 1:
2129 option_tuple, = option_tuples
2130 return option_tuple
2131
2132 # if it was not found as an option, but it looks like a negative
2133 # number, it was meant to be positional
2134 # unless there are negative-number-like options
2135 if self._negative_number_matcher.match(arg_string):
2136 if not self._has_negative_number_optionals:
2137 return None
2138
2139 # if it contains a space, it was meant to be a positional
2140 if ' ' in arg_string:
2141 return None
2142
2143 # it was meant to be an optional but there is no such option
2144 # in this parser (though it might be a valid option in a subparser)
2145 return None, arg_string, None
2146
2147 def _get_option_tuples(self, option_string):
2148 result = []
2149
2150 # option strings starting with two prefix characters are only
2151 # split at the '='
2152 chars = self.prefix_chars
2153 if option_string[0] in chars and option_string[1] in chars:
2154 if '=' in option_string:
2155 option_prefix, explicit_arg = option_string.split('=', 1)
2156 else:
2157 option_prefix = option_string
2158 explicit_arg = None
2159 for option_string in self._option_string_actions:
2160 if option_string.startswith(option_prefix):
2161 action = self._option_string_actions[option_string]
2162 tup = action, option_string, explicit_arg
2163 result.append(tup)
2164
2165 # single character options can be concatenated with their arguments
2166 # but multiple character options always have to have their argument
2167 # separate
2168 elif option_string[0] in chars and option_string[1] not in chars:
2169 option_prefix = option_string
2170 explicit_arg = None
2171 short_option_prefix = option_string[:2]
2172 short_explicit_arg = option_string[2:]
2173
2174 for option_string in self._option_string_actions:
2175 if option_string == short_option_prefix:
2176 action = self._option_string_actions[option_string]
2177 tup = action, option_string, short_explicit_arg
2178 result.append(tup)
2179 elif option_string.startswith(option_prefix):
2180 action = self._option_string_actions[option_string]
2181 tup = action, option_string, explicit_arg
2182 result.append(tup)
2183
2184 # shouldn't ever get here
2185 else:
2186 self.error(_('unexpected option string: %s') % option_string)
2187
2188 # return the collected option tuples
2189 return result
2190
2191 def _get_nargs_pattern(self, action):
2192 # in all examples below, we have to allow for '--' args
2193 # which are represented as '-' in the pattern
2194 nargs = action.nargs
2195
2196 # the default (None) is assumed to be a single argument
2197 if nargs is None:
2198 nargs_pattern = '(-*A-*)'
2199
2200 # allow zero or one arguments
2201 elif nargs == OPTIONAL:
2202 nargs_pattern = '(-*A?-*)'
2203
2204 # allow zero or more arguments
2205 elif nargs == ZERO_OR_MORE:
2206 nargs_pattern = '(-*[A-]*)'
2207
2208 # allow one or more arguments
2209 elif nargs == ONE_OR_MORE:
2210 nargs_pattern = '(-*A[A-]*)'
2211
2212 # allow any number of options or arguments
2213 elif nargs == REMAINDER:
2214 nargs_pattern = '([-AO]*)'
2215
2216 # allow one argument followed by any number of options or arguments
2217 elif nargs == PARSER:
2218 nargs_pattern = '(-*A[-AO]*)'
2219
2220 # all others should be integers
2221 else:
2222 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs)
2223
2224 # if this is an optional action, -- is not allowed
2225 if action.option_strings:
2226 nargs_pattern = nargs_pattern.replace('-*', '')
2227 nargs_pattern = nargs_pattern.replace('-', '')
2228
2229 # return the pattern
2230 return nargs_pattern
2231
2232 # ========================
2233 # Value conversion methods
2234 # ========================
2235 def _get_values(self, action, arg_strings):
2236 # for everything but PARSER args, strip out '--'
2237 if action.nargs not in [PARSER, REMAINDER]:
2238 arg_strings = [s for s in arg_strings if s != '--']
2239
2240 # optional argument produces a default when not present
2241 if not arg_strings and action.nargs == OPTIONAL:
2242 if action.option_strings:
2243 value = action.const
2244 else:
2245 value = action.default
2246 if isinstance(value, basestring):
2247 value = self._get_value(action, value)
2248 self._check_value(action, value)
2249
2250 # when nargs='*' on a positional, if there were no command-line
2251 # args, use the default if it is anything other than None
2252 elif (not arg_strings and action.nargs == ZERO_OR_MORE and
2253 not action.option_strings):
2254 if action.default is not None:
2255 value = action.default
2256 else:
2257 value = arg_strings
2258 self._check_value(action, value)
2259
2260 # single argument or optional argument produces a single value
2261 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]:
2262 arg_string, = arg_strings
2263 value = self._get_value(action, arg_string)
2264 self._check_value(action, value)
2265
2266 # REMAINDER arguments convert all values, checking none
2267 elif action.nargs == REMAINDER:
2268 value = [self._get_value(action, v) for v in arg_strings]
2269
2270 # PARSER arguments convert all values, but check only the first
2271 elif action.nargs == PARSER:
2272 value = [self._get_value(action, v) for v in arg_strings]
2273 self._check_value(action, value[0])
2274
2275 # all other types of nargs produce a list
2276 else:
2277 value = [self._get_value(action, v) for v in arg_strings]
2278 for v in value:
2279 self._check_value(action, v)
2280
2281 # return the converted value
2282 return value
2283
2284 def _get_value(self, action, arg_string):
2285 type_func = self._registry_get('type', action.type, action.type)
2286 if not _callable(type_func):
2287 msg = _('%r is not callable')
2288 raise ArgumentError(action, msg % type_func)
2289
2290 # convert the value to the appropriate type
2291 try:
2292 result = type_func(arg_string)
2293
2294 # ArgumentTypeErrors indicate errors
2295 except ArgumentTypeError:
2296 name = getattr(action.type, '__name__', repr(action.type))
2297 msg = str(_sys.exc_info()[1])
2298 raise ArgumentError(action, msg)
2299
2300 # TypeErrors or ValueErrors also indicate errors
2301 except (TypeError, ValueError):
2302 name = getattr(action.type, '__name__', repr(action.type))
2303 msg = _('invalid %s value: %r')
2304 raise ArgumentError(action, msg % (name, arg_string))
2305
2306 # return the converted value
2307 return result
2308
2309 def _check_value(self, action, value):
2310 # converted value must be one of the choices (if specified)
2311 if action.choices is not None and value not in action.choices:
2312 tup = value, ', '.join(map(repr, action.choices))
2313 msg = _('invalid choice: %r (choose from %s)') % tup
2314 raise ArgumentError(action, msg)
2315
2316 # =======================
2317 # Help-formatting methods
2318 # =======================
2319 def format_usage(self):
2320 formatter = self._get_formatter()
2321 formatter.add_usage(self.usage, self._actions,
2322 self._mutually_exclusive_groups)
2323 return formatter.format_help()
2324
2325 def format_help(self):
2326 formatter = self._get_formatter()
2327
2328 # usage
2329 formatter.add_usage(self.usage, self._actions,
2330 self._mutually_exclusive_groups)
2331
2332 # description
2333 formatter.add_text(self.description)
2334
2335 # positionals, optionals and user-defined groups
2336 for action_group in self._action_groups:
2337 formatter.start_section(action_group.title)
2338 formatter.add_text(action_group.description)
2339 formatter.add_arguments(action_group._group_actions)
2340 formatter.end_section()
2341
2342 # epilog
2343 formatter.add_text(self.epilog)
2344
2345 # determine help from format above
2346 return formatter.format_help()
2347
2348 def format_version(self):
2349 import warnings
2350 warnings.warn(
2351 'The format_version method is deprecated -- the "version" '
2352 'argument to ArgumentParser is no longer supported.',
2353 DeprecationWarning)
2354 formatter = self._get_formatter()
2355 formatter.add_text(self.version)
2356 return formatter.format_help()
2357
2358 def _get_formatter(self):
2359 return self.formatter_class(prog=self.prog)
2360
2361 # =====================
2362 # Help-printing methods
2363 # =====================
2364 def print_usage(self, file=None):
2365 if file is None:
2366 file = _sys.stdout
2367 self._print_message(self.format_usage(), file)
2368
2369 def print_help(self, file=None):
2370 if file is None:
2371 file = _sys.stdout
2372 self._print_message(self.format_help(), file)
2373
2374 def print_version(self, file=None):
2375 import warnings
2376 warnings.warn(
2377 'The print_version method is deprecated -- the "version" '
2378 'argument to ArgumentParser is no longer supported.',
2379 DeprecationWarning)
2380 self._print_message(self.format_version(), file)
2381
2382 def _print_message(self, message, file=None):
2383 if message:
2384 if file is None:
2385 file = _sys.stderr
2386 file.write(message)
2387
2388 # ===============
2389 # Exiting methods
2390 # ===============
2391 def exit(self, status=0, message=None):
2392 if message:
2393 self._print_message(message, _sys.stderr)
2394 _sys.exit(status)
2395
2396 def error(self, message):
2397 """error(message: string)
2398
2399 Prints a usage message incorporating the message to stderr and
2400 exits.
2401
2402 If you override this in a subclass, it should not return -- it
2403 should either exit or raise an exception.
2404 """
2405 self.print_usage(_sys.stderr)
2406 self.exit(2, _('%s: error: %s\n') % (self.prog, message))