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