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