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