source: python/trunk/Lib/argparse.py@ 611

Last change on this file since 611 was 391, checked in by dmik, 11 years ago

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