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