CMS 3D CMS Logo

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