Coverage for Lib/argparse.py: 97%

1302 statements  

« prev     ^ index     » next       coverage.py v7.2.1, created at 2023-04-15 13:10 +0300

1# Author: Steven J. Bethard <steven.bethard@gmail.com>. 

2# New maintainer as of 29 August 2019: Raymond Hettinger <raymond.hettinger@gmail.com> 

3 

4"""Command-line parsing library 

5 

6This module is an optparse-inspired command-line parsing library that: 

7 

8 - handles both optional and positional arguments 

9 - produces highly informative usage messages 

10 - supports parsers that dispatch to sub-parsers 

11 

12The following is a simple usage example that sums integers from the 

13command-line and writes the result to a file:: 

14 

15 parser = argparse.ArgumentParser( 

16 description='sum the integers at the command line') 

17 parser.add_argument( 

18 'integers', metavar='int', nargs='+', type=int, 

19 help='an integer to be summed') 

20 parser.add_argument( 

21 '--log', default=sys.stdout, type=argparse.FileType('w'), 

22 help='the file where the sum should be written') 

23 args = parser.parse_args() 

24 args.log.write('%s' % sum(args.integers)) 

25 args.log.close() 

26 

27The module contains the following public classes: 

28 

29 - ArgumentParser -- The main entry point for command-line parsing. As the 

30 example above shows, the add_argument() method is used to populate 

31 the parser with actions for optional and positional arguments. Then 

32 the parse_args() method is invoked to convert the args at the 

33 command-line into an object with attributes. 

34 

35 - ArgumentError -- The exception raised by ArgumentParser objects when 

36 there are errors with the parser's actions. Errors raised while 

37 parsing the command-line are caught by ArgumentParser and emitted 

38 as command-line messages. 

39 

40 - FileType -- A factory for defining types of files to be created. As the 

41 example above shows, instances of FileType are typically passed as 

42 the type= argument of add_argument() calls. 

43 

44 - Action -- The base class for parser actions. Typically actions are 

45 selected by passing strings like 'store_true' or 'append_const' to 

46 the action= argument of add_argument(). However, for greater 

47 customization of ArgumentParser actions, subclasses of Action may 

48 be defined and passed as the action= argument. 

49 

50 - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter, 

51 ArgumentDefaultsHelpFormatter -- Formatter classes which 

52 may be passed as the formatter_class= argument to the 

53 ArgumentParser constructor. HelpFormatter is the default, 

54 RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser 

55 not to change the formatting for help text, and 

56 ArgumentDefaultsHelpFormatter adds information about argument defaults 

57 to the help. 

58 

59All other classes in this module are considered implementation details. 

60(Also note that HelpFormatter and RawDescriptionHelpFormatter are only 

61considered public as object names -- the API of the formatter objects is 

62still considered an implementation detail.) 

63""" 

64 

65__version__ = '1.1' 

66__all__ = [ 

67 'ArgumentParser', 

68 'ArgumentError', 

69 'ArgumentTypeError', 

70 'BooleanOptionalAction', 

71 'FileType', 

72 'HelpFormatter', 

73 'ArgumentDefaultsHelpFormatter', 

74 'RawDescriptionHelpFormatter', 

75 'RawTextHelpFormatter', 

76 'MetavarTypeHelpFormatter', 

77 'Namespace', 

78 'Action', 

79 'ONE_OR_MORE', 

80 'OPTIONAL', 

81 'PARSER', 

82 'REMAINDER', 

83 'SUPPRESS', 

84 'ZERO_OR_MORE', 

85] 

86 

87 

88import os as _os 

89import re as _re 

90import sys as _sys 

91 

92import warnings 

93 

94from gettext import gettext as _, ngettext 

95 

96SUPPRESS = '==SUPPRESS==' 

97 

98OPTIONAL = '?' 

99ZERO_OR_MORE = '*' 

100ONE_OR_MORE = '+' 

101PARSER = 'A...' 

102REMAINDER = '...' 

103_UNRECOGNIZED_ARGS_ATTR = '_unrecognized_args' 

104 

105# ============================= 

106# Utility functions and classes 

107# ============================= 

108 

109class _AttributeHolder(object): 

110 """Abstract base class that provides __repr__. 

111 

112 The __repr__ method returns a string in the format:: 

113 ClassName(attr=name, attr=name, ...) 

114 The attributes are determined either by a class-level attribute, 

115 '_kwarg_names', or by inspecting the instance __dict__. 

116 """ 

117 

118 def __repr__(self): 

119 type_name = type(self).__name__ 

120 arg_strings = [] 

121 star_args = {} 

122 for arg in self._get_args(): 122 ↛ 123line 122 didn't jump to line 123, because the loop on line 122 never started

123 arg_strings.append(repr(arg)) 

124 for name, value in self._get_kwargs(): 

125 if name.isidentifier(): 

126 arg_strings.append('%s=%r' % (name, value)) 

127 else: 

128 star_args[name] = value 

129 if star_args: 

130 arg_strings.append('**%s' % repr(star_args)) 

131 return '%s(%s)' % (type_name, ', '.join(arg_strings)) 

132 

133 def _get_kwargs(self): 

134 return list(self.__dict__.items()) 

135 

136 def _get_args(self): 

137 return [] 

138 

139 

140def _copy_items(items): 

141 if items is None: 

142 return [] 

143 # The copy module is used only in the 'append' and 'append_const' 

144 # actions, and it is needed only when the default value isn't a list. 

145 # Delay its import for speeding up the common case. 

146 if type(items) is list: 146 ↛ 148line 146 didn't jump to line 148, because the condition on line 146 was never false

147 return items[:] 

148 import copy 

149 return copy.copy(items) 

150 

151 

152# =============== 

153# Formatting Help 

154# =============== 

155 

156 

157class HelpFormatter(object): 

158 """Formatter for generating usage messages and argument help strings. 

159 

160 Only the name of this class is considered a public API. All the methods 

161 provided by the class are considered an implementation detail. 

162 """ 

163 

164 def __init__(self, 

165 prog, 

166 indent_increment=2, 

167 max_help_position=24, 

168 width=None): 

169 

170 # default setting for width 

171 if width is None: 171 ↛ 176line 171 didn't jump to line 176, because the condition on line 171 was never false

172 import shutil 

173 width = shutil.get_terminal_size().columns 

174 width -= 2 

175 

176 self._prog = prog 

177 self._indent_increment = indent_increment 

178 self._max_help_position = min(max_help_position, 

179 max(width - 20, indent_increment * 2)) 

180 self._width = width 

181 

182 self._current_indent = 0 

183 self._level = 0 

184 self._action_max_length = 0 

185 

186 self._root_section = self._Section(self, None) 

187 self._current_section = self._root_section 

188 

189 self._whitespace_matcher = _re.compile(r'\s+', _re.ASCII) 

190 self._long_break_matcher = _re.compile(r'\n\n\n+') 

191 

192 # =============================== 

193 # Section and indentation methods 

194 # =============================== 

195 def _indent(self): 

196 self._current_indent += self._indent_increment 

197 self._level += 1 

198 

199 def _dedent(self): 

200 self._current_indent -= self._indent_increment 

201 assert self._current_indent >= 0, 'Indent decreased below 0.' 

202 self._level -= 1 

203 

204 class _Section(object): 

205 

206 def __init__(self, formatter, parent, heading=None): 

207 self.formatter = formatter 

208 self.parent = parent 

209 self.heading = heading 

210 self.items = [] 

211 

212 def format_help(self): 

213 # format the indented section 

214 if self.parent is not None: 

215 self.formatter._indent() 

216 join = self.formatter._join_parts 

217 item_help = join([func(*args) for func, args in self.items]) 

218 if self.parent is not None: 

219 self.formatter._dedent() 

220 

221 # return nothing if the section was empty 

222 if not item_help: 

223 return '' 

224 

225 # add the heading if the section was non-empty 

226 if self.heading is not SUPPRESS and self.heading is not None: 

227 current_indent = self.formatter._current_indent 

228 heading = '%*s%s:\n' % (current_indent, '', self.heading) 

229 else: 

230 heading = '' 

231 

232 # join the section-initial newline, the heading and the help 

233 return join(['\n', heading, item_help, '\n']) 

234 

235 def _add_item(self, func, args): 

236 self._current_section.items.append((func, args)) 

237 

238 # ======================== 

239 # Message building methods 

240 # ======================== 

241 def start_section(self, heading): 

242 self._indent() 

243 section = self._Section(self, self._current_section, heading) 

244 self._add_item(section.format_help, []) 

245 self._current_section = section 

246 

247 def end_section(self): 

248 self._current_section = self._current_section.parent 

249 self._dedent() 

250 

251 def add_text(self, text): 

252 if text is not SUPPRESS and text is not None: 

253 self._add_item(self._format_text, [text]) 

254 

255 def add_usage(self, usage, actions, groups, prefix=None): 

256 if usage is not SUPPRESS: 

257 args = usage, actions, groups, prefix 

258 self._add_item(self._format_usage, args) 

259 

260 def add_argument(self, action): 

261 if action.help is not SUPPRESS: 

262 

263 # find all invocations 

264 get_invocation = self._format_action_invocation 

265 invocations = [get_invocation(action)] 

266 for subaction in self._iter_indented_subactions(action): 

267 invocations.append(get_invocation(subaction)) 

268 

269 # update the maximum item length 

270 invocation_length = max(map(len, invocations)) 

271 action_length = invocation_length + self._current_indent 

272 self._action_max_length = max(self._action_max_length, 

273 action_length) 

274 

275 # add the item to the list 

276 self._add_item(self._format_action, [action]) 

277 

278 def add_arguments(self, actions): 

279 for action in actions: 

280 self.add_argument(action) 

281 

282 # ======================= 

283 # Help-formatting methods 

284 # ======================= 

285 def format_help(self): 

286 help = self._root_section.format_help() 

287 if help: 

288 help = self._long_break_matcher.sub('\n\n', help) 

289 help = help.strip('\n') + '\n' 

290 return help 

291 

292 def _join_parts(self, part_strings): 

293 return ''.join([part 

294 for part in part_strings 

295 if part and part is not SUPPRESS]) 

296 

297 def _format_usage(self, usage, actions, groups, prefix): 

298 if prefix is None: 

299 prefix = _('usage: ') 

300 

301 # if usage is specified, use that 

302 if usage is not None: 

303 usage = usage % dict(prog=self._prog) 

304 

305 # if no optionals or positionals are available, usage is just prog 

306 elif usage is None and not actions: 

307 usage = '%(prog)s' % dict(prog=self._prog) 

308 

309 # if optionals and positionals are available, calculate usage 

310 elif usage is None: 310 ↛ 391line 310 didn't jump to line 391, because the condition on line 310 was never false

311 prog = '%(prog)s' % dict(prog=self._prog) 

312 

313 # split optionals from positionals 

314 optionals = [] 

315 positionals = [] 

316 for action in actions: 

317 if action.option_strings: 

318 optionals.append(action) 

319 else: 

320 positionals.append(action) 

321 

322 # build full usage string 

323 format = self._format_actions_usage 

324 action_usage = format(optionals + positionals, groups) 

325 usage = ' '.join([s for s in [prog, action_usage] if s]) 

326 

327 # wrap the usage parts if it's too long 

328 text_width = self._width - self._current_indent 

329 if len(prefix) + len(usage) > text_width: 

330 

331 # break usage into wrappable parts 

332 part_regexp = ( 

333 r'\(.*?\)+(?=\s|$)|' 

334 r'\[.*?\]+(?=\s|$)|' 

335 r'\S+' 

336 ) 

337 opt_usage = format(optionals, groups) 

338 pos_usage = format(positionals, groups) 

339 opt_parts = _re.findall(part_regexp, opt_usage) 

340 pos_parts = _re.findall(part_regexp, pos_usage) 

341 assert ' '.join(opt_parts) == opt_usage 

342 assert ' '.join(pos_parts) == pos_usage 

343 

344 # helper for wrapping lines 

345 def get_lines(parts, indent, prefix=None): 

346 lines = [] 

347 line = [] 

348 if prefix is not None: 

349 line_len = len(prefix) - 1 

350 else: 

351 line_len = len(indent) - 1 

352 for part in parts: 

353 if line_len + 1 + len(part) > text_width and line: 

354 lines.append(indent + ' '.join(line)) 

355 line = [] 

356 line_len = len(indent) - 1 

357 line.append(part) 

358 line_len += len(part) + 1 

359 if line: 

360 lines.append(indent + ' '.join(line)) 

361 if prefix is not None: 

362 lines[0] = lines[0][len(indent):] 

363 return lines 

364 

365 # if prog is short, follow it with optionals or positionals 

366 if len(prefix) + len(prog) <= 0.75 * text_width: 

367 indent = ' ' * (len(prefix) + len(prog) + 1) 

368 if opt_parts: 

369 lines = get_lines([prog] + opt_parts, indent, prefix) 

370 lines.extend(get_lines(pos_parts, indent)) 

371 elif pos_parts: 371 ↛ 374line 371 didn't jump to line 374, because the condition on line 371 was never false

372 lines = get_lines([prog] + pos_parts, indent, prefix) 

373 else: 

374 lines = [prog] 

375 

376 # if prog is long, put it on its own line 

377 else: 

378 indent = ' ' * len(prefix) 

379 parts = opt_parts + pos_parts 

380 lines = get_lines(parts, indent) 

381 if len(lines) > 1: 

382 lines = [] 

383 lines.extend(get_lines(opt_parts, indent)) 

384 lines.extend(get_lines(pos_parts, indent)) 

385 lines = [prog] + lines 

386 

387 # join lines into usage 

388 usage = '\n'.join(lines) 

389 

390 # prefix with 'usage:' 

391 return '%s%s\n\n' % (prefix, usage) 

392 

393 def _format_actions_usage(self, actions, groups): 

394 # find group indices and identify actions in groups 

395 group_actions = set() 

396 inserts = {} 

397 for group in groups: 

398 if not group._group_actions: 

399 raise ValueError(f'empty group {group}') 

400 

401 try: 

402 start = actions.index(group._group_actions[0]) 

403 except ValueError: 

404 continue 

405 else: 

406 group_action_count = len(group._group_actions) 

407 end = start + group_action_count 

408 if actions[start:end] == group._group_actions: 

409 

410 suppressed_actions_count = 0 

411 for action in group._group_actions: 

412 group_actions.add(action) 

413 if action.help is SUPPRESS: 

414 suppressed_actions_count += 1 

415 

416 exposed_actions_count = group_action_count - suppressed_actions_count 

417 

418 if not group.required: 

419 if start in inserts: 

420 inserts[start] += ' [' 

421 else: 

422 inserts[start] = '[' 

423 if end in inserts: 

424 inserts[end] += ']' 

425 else: 

426 inserts[end] = ']' 

427 elif exposed_actions_count > 1: 

428 if start in inserts: 

429 inserts[start] += ' (' 

430 else: 

431 inserts[start] = '(' 

432 if end in inserts: 

433 inserts[end] += ')' 

434 else: 

435 inserts[end] = ')' 

436 for i in range(start + 1, end): 

437 inserts[i] = '|' 

438 

439 # collect all actions format strings 

440 parts = [] 

441 for i, action in enumerate(actions): 

442 

443 # suppressed arguments are marked with None 

444 # remove | separators for suppressed arguments 

445 if action.help is SUPPRESS: 

446 parts.append(None) 

447 if inserts.get(i) == '|': 447 ↛ 448line 447 didn't jump to line 448, because the condition on line 447 was never true

448 inserts.pop(i) 

449 elif inserts.get(i + 1) == '|': 

450 inserts.pop(i + 1) 

451 

452 # produce all arg strings 

453 elif not action.option_strings: 

454 default = self._get_default_metavar_for_positional(action) 

455 part = self._format_args(action, default) 

456 

457 # if it's in a group, strip the outer [] 

458 if action in group_actions: 

459 if part[0] == '[' and part[-1] == ']': 459 ↛ 463line 459 didn't jump to line 463, because the condition on line 459 was never false

460 part = part[1:-1] 

461 

462 # add the action string to the list 

463 parts.append(part) 

464 

465 # produce the first way to invoke the option in brackets 

466 else: 

467 option_string = action.option_strings[0] 

468 

469 # if the Optional doesn't take a value, format is: 

470 # -s or --long 

471 if action.nargs == 0: 

472 part = action.format_usage() 

473 

474 # if the Optional takes a value, format is: 

475 # -s ARGS or --long ARGS 

476 else: 

477 default = self._get_default_metavar_for_optional(action) 

478 args_string = self._format_args(action, default) 

479 part = '%s %s' % (option_string, args_string) 

480 

481 # make it look optional if it's not required or in a group 

482 if not action.required and action not in group_actions: 

483 part = '[%s]' % part 

484 

485 # add the action string to the list 

486 parts.append(part) 

487 

488 # insert things at the necessary indices 

489 for i in sorted(inserts, reverse=True): 

490 parts[i:i] = [inserts[i]] 

491 

492 # join all the action items with spaces 

493 text = ' '.join([item for item in parts if item is not None]) 

494 

495 # clean up separators for mutually exclusive groups 

496 open = r'[\[(]' 

497 close = r'[\])]' 

498 text = _re.sub(r'(%s) ' % open, r'\1', text) 

499 text = _re.sub(r' (%s)' % close, r'\1', text) 

500 text = _re.sub(r'%s *%s' % (open, close), r'', text) 

501 text = text.strip() 

502 

503 # return the text 

504 return text 

505 

506 def _format_text(self, text): 

507 if '%(prog)' in text: 

508 text = text % dict(prog=self._prog) 

509 text_width = max(self._width - self._current_indent, 11) 

510 indent = ' ' * self._current_indent 

511 return self._fill_text(text, text_width, indent) + '\n\n' 

512 

513 def _format_action(self, action): 

514 # determine the required width and the entry label 

515 help_position = min(self._action_max_length + 2, 

516 self._max_help_position) 

517 help_width = max(self._width - help_position, 11) 

518 action_width = help_position - self._current_indent - 2 

519 action_header = self._format_action_invocation(action) 

520 

521 # no help; start on same line and add a final newline 

522 if not action.help: 

523 tup = self._current_indent, '', action_header 

524 action_header = '%*s%s\n' % tup 

525 

526 # short action name; start on the same line and pad two spaces 

527 elif len(action_header) <= action_width: 

528 tup = self._current_indent, '', action_width, action_header 

529 action_header = '%*s%-*s ' % tup 

530 indent_first = 0 

531 

532 # long action name; start on the next line 

533 else: 

534 tup = self._current_indent, '', action_header 

535 action_header = '%*s%s\n' % tup 

536 indent_first = help_position 

537 

538 # collect the pieces of the action help 

539 parts = [action_header] 

540 

541 # if there was help for the action, add lines of help text 

542 if action.help and action.help.strip(): 

543 help_text = self._expand_help(action) 

544 if help_text: 

545 help_lines = self._split_lines(help_text, help_width) 

546 parts.append('%*s%s\n' % (indent_first, '', help_lines[0])) 

547 for line in help_lines[1:]: 

548 parts.append('%*s%s\n' % (help_position, '', line)) 

549 

550 # or add a newline if the description doesn't end with one 

551 elif not action_header.endswith('\n'): 

552 parts.append('\n') 

553 

554 # if there are any sub-actions, add their help as well 

555 for subaction in self._iter_indented_subactions(action): 

556 parts.append(self._format_action(subaction)) 

557 

558 # return a single string 

559 return self._join_parts(parts) 

560 

561 def _format_action_invocation(self, action): 

562 if not action.option_strings: 

563 default = self._get_default_metavar_for_positional(action) 

564 metavar, = self._metavar_formatter(action, default)(1) 

565 return metavar 

566 

567 else: 

568 parts = [] 

569 

570 # if the Optional doesn't take a value, format is: 

571 # -s, --long 

572 if action.nargs == 0: 

573 parts.extend(action.option_strings) 

574 

575 # if the Optional takes a value, format is: 

576 # -s ARGS, --long ARGS 

577 else: 

578 default = self._get_default_metavar_for_optional(action) 

579 args_string = self._format_args(action, default) 

580 for option_string in action.option_strings: 

581 parts.append('%s %s' % (option_string, args_string)) 

582 

583 return ', '.join(parts) 

584 

585 def _metavar_formatter(self, action, default_metavar): 

586 if action.metavar is not None: 

587 result = action.metavar 

588 elif action.choices is not None: 

589 choice_strs = [str(choice) for choice in action.choices] 

590 result = '{%s}' % ','.join(choice_strs) 

591 else: 

592 result = default_metavar 

593 

594 def format(tuple_size): 

595 if isinstance(result, tuple): 

596 return result 

597 else: 

598 return (result, ) * tuple_size 

599 return format 

600 

601 def _format_args(self, action, default_metavar): 

602 get_metavar = self._metavar_formatter(action, default_metavar) 

603 if action.nargs is None: 

604 result = '%s' % get_metavar(1) 

605 elif action.nargs == OPTIONAL: 

606 result = '[%s]' % get_metavar(1) 

607 elif action.nargs == ZERO_OR_MORE: 

608 metavar = get_metavar(1) 

609 if len(metavar) == 2: 

610 result = '[%s [%s ...]]' % metavar 

611 else: 

612 result = '[%s ...]' % metavar 

613 elif action.nargs == ONE_OR_MORE: 

614 result = '%s [%s ...]' % get_metavar(2) 

615 elif action.nargs == REMAINDER: 

616 result = '...' 

617 elif action.nargs == PARSER: 

618 result = '%s ...' % get_metavar(1) 

619 elif action.nargs == SUPPRESS: 619 ↛ 620line 619 didn't jump to line 620, because the condition on line 619 was never true

620 result = '' 

621 else: 

622 try: 

623 formats = ['%s' for _ in range(action.nargs)] 

624 except TypeError: 

625 raise ValueError("invalid nargs value") from None 

626 result = ' '.join(formats) % get_metavar(action.nargs) 

627 return result 

628 

629 def _expand_help(self, action): 

630 params = dict(vars(action), prog=self._prog) 

631 for name in list(params): 

632 if params[name] is SUPPRESS: 

633 del params[name] 

634 for name in list(params): 

635 if hasattr(params[name], '__name__'): 

636 params[name] = params[name].__name__ 

637 if params.get('choices') is not None: 

638 choices_str = ', '.join([str(c) for c in params['choices']]) 

639 params['choices'] = choices_str 

640 return self._get_help_string(action) % params 

641 

642 def _iter_indented_subactions(self, action): 

643 try: 

644 get_subactions = action._get_subactions 

645 except AttributeError: 

646 pass 

647 else: 

648 self._indent() 

649 yield from get_subactions() 

650 self._dedent() 

651 

652 def _split_lines(self, text, width): 

653 text = self._whitespace_matcher.sub(' ', text).strip() 

654 # The textwrap module is used only for formatting help. 

655 # Delay its import for speeding up the common usage of argparse. 

656 import textwrap 

657 return textwrap.wrap(text, width) 

658 

659 def _fill_text(self, text, width, indent): 

660 text = self._whitespace_matcher.sub(' ', text).strip() 

661 import textwrap 

662 return textwrap.fill(text, width, 

663 initial_indent=indent, 

664 subsequent_indent=indent) 

665 

666 def _get_help_string(self, action): 

667 return action.help 

668 

669 def _get_default_metavar_for_optional(self, action): 

670 return action.dest.upper() 

671 

672 def _get_default_metavar_for_positional(self, action): 

673 return action.dest 

674 

675 

676class RawDescriptionHelpFormatter(HelpFormatter): 

677 """Help message formatter which retains any formatting in descriptions. 

678 

679 Only the name of this class is considered a public API. All the methods 

680 provided by the class are considered an implementation detail. 

681 """ 

682 

683 def _fill_text(self, text, width, indent): 

684 return ''.join(indent + line for line in text.splitlines(keepends=True)) 

685 

686 

687class RawTextHelpFormatter(RawDescriptionHelpFormatter): 

688 """Help message formatter which retains formatting of all help text. 

689 

690 Only the name of this class is considered a public API. All the methods 

691 provided by the class are considered an implementation detail. 

692 """ 

693 

694 def _split_lines(self, text, width): 

695 return text.splitlines() 

696 

697 

698class ArgumentDefaultsHelpFormatter(HelpFormatter): 

699 """Help message formatter which adds default values to argument help. 

700 

701 Only the name of this class is considered a public API. All the methods 

702 provided by the class are considered an implementation detail. 

703 """ 

704 

705 def _get_help_string(self, action): 

706 """ 

707 Add the default value to the option help message. 

708 

709 ArgumentDefaultsHelpFormatter and BooleanOptionalAction when it isn't 

710 already present. This code will do that, detecting cornercases to 

711 prevent duplicates or cases where it wouldn't make sense to the end 

712 user. 

713 """ 

714 help = action.help 

715 if help is None: 715 ↛ 716line 715 didn't jump to line 716, because the condition on line 715 was never true

716 help = '' 

717 

718 if '%(default)' not in help: 

719 if action.default is not SUPPRESS: 

720 defaulting_nargs = [OPTIONAL, ZERO_OR_MORE] 

721 if action.option_strings or action.nargs in defaulting_nargs: 

722 help += ' (default: %(default)s)' 

723 return help 

724 

725 

726 

727class MetavarTypeHelpFormatter(HelpFormatter): 

728 """Help message formatter which uses the argument 'type' as the default 

729 metavar value (instead of the argument 'dest') 

730 

731 Only the name of this class is considered a public API. All the methods 

732 provided by the class are considered an implementation detail. 

733 """ 

734 

735 def _get_default_metavar_for_optional(self, action): 

736 return action.type.__name__ 

737 

738 def _get_default_metavar_for_positional(self, action): 

739 return action.type.__name__ 

740 

741 

742# ===================== 

743# Options and Arguments 

744# ===================== 

745 

746def _get_action_name(argument): 

747 if argument is None: 

748 return None 

749 elif argument.option_strings: 

750 return '/'.join(argument.option_strings) 

751 elif argument.metavar not in (None, SUPPRESS): 

752 return argument.metavar 

753 elif argument.dest not in (None, SUPPRESS): 

754 return argument.dest 

755 elif argument.choices: 755 ↛ 758line 755 didn't jump to line 758, because the condition on line 755 was never false

756 return '{' + ','.join(argument.choices) + '}' 

757 else: 

758 return None 

759 

760 

761class ArgumentError(Exception): 

762 """An error from creating or using an argument (optional or positional). 

763 

764 The string value of this exception is the message, augmented with 

765 information about the argument that caused it. 

766 """ 

767 

768 def __init__(self, argument, message): 

769 self.argument_name = _get_action_name(argument) 

770 self.message = message 

771 

772 def __str__(self): 

773 if self.argument_name is None: 

774 format = '%(message)s' 

775 else: 

776 format = _('argument %(argument_name)s: %(message)s') 

777 return format % dict(message=self.message, 

778 argument_name=self.argument_name) 

779 

780 

781class ArgumentTypeError(Exception): 

782 """An error from trying to convert a command line string to a type.""" 

783 pass 

784 

785 

786# ============== 

787# Action classes 

788# ============== 

789 

790class Action(_AttributeHolder): 

791 """Information about how to convert command line strings to Python objects. 

792 

793 Action objects are used by an ArgumentParser to represent the information 

794 needed to parse a single argument from one or more strings from the 

795 command line. The keyword arguments to the Action constructor are also 

796 all attributes of Action instances. 

797 

798 Keyword Arguments: 

799 

800 - option_strings -- A list of command-line option strings which 

801 should be associated with this action. 

802 

803 - dest -- The name of the attribute to hold the created object(s) 

804 

805 - nargs -- The number of command-line arguments that should be 

806 consumed. By default, one argument will be consumed and a single 

807 value will be produced. Other values include: 

808 - N (an integer) consumes N arguments (and produces a list) 

809 - '?' consumes zero or one arguments 

810 - '*' consumes zero or more arguments (and produces a list) 

811 - '+' consumes one or more arguments (and produces a list) 

812 Note that the difference between the default and nargs=1 is that 

813 with the default, a single value will be produced, while with 

814 nargs=1, a list containing a single value will be produced. 

815 

816 - const -- The value to be produced if the option is specified and the 

817 option uses an action that takes no values. 

818 

819 - default -- The value to be produced if the option is not specified. 

820 

821 - type -- A callable that accepts a single string argument, and 

822 returns the converted value. The standard Python types str, int, 

823 float, and complex are useful examples of such callables. If None, 

824 str is used. 

825 

826 - choices -- A container of values that should be allowed. If not None, 

827 after a command-line argument has been converted to the appropriate 

828 type, an exception will be raised if it is not a member of this 

829 collection. 

830 

831 - required -- True if the action must always be specified at the 

832 command line. This is only meaningful for optional command-line 

833 arguments. 

834 

835 - help -- The help string describing the argument. 

836 

837 - metavar -- The name to be used for the option's argument with the 

838 help string. If None, the 'dest' value will be used as the name. 

839 """ 

840 

841 def __init__(self, 

842 option_strings, 

843 dest, 

844 nargs=None, 

845 const=None, 

846 default=None, 

847 type=None, 

848 choices=None, 

849 required=False, 

850 help=None, 

851 metavar=None): 

852 self.option_strings = option_strings 

853 self.dest = dest 

854 self.nargs = nargs 

855 self.const = const 

856 self.default = default 

857 self.type = type 

858 self.choices = choices 

859 self.required = required 

860 self.help = help 

861 self.metavar = metavar 

862 

863 def _get_kwargs(self): 

864 names = [ 

865 'option_strings', 

866 'dest', 

867 'nargs', 

868 'const', 

869 'default', 

870 'type', 

871 'choices', 

872 'required', 

873 'help', 

874 'metavar', 

875 ] 

876 return [(name, getattr(self, name)) for name in names] 

877 

878 def format_usage(self): 

879 return self.option_strings[0] 

880 

881 def __call__(self, parser, namespace, values, option_string=None): 

882 raise NotImplementedError(_('.__call__() not defined')) 

883 

884 

885class BooleanOptionalAction(Action): 

886 def __init__(self, 

887 option_strings, 

888 dest, 

889 default=None, 

890 type=None, 

891 choices=None, 

892 required=False, 

893 help=None, 

894 metavar=None): 

895 

896 _option_strings = [] 

897 for option_string in option_strings: 

898 _option_strings.append(option_string) 

899 

900 if option_string.startswith('--'): 

901 option_string = '--no-' + option_string[2:] 

902 _option_strings.append(option_string) 

903 

904 super().__init__( 

905 option_strings=_option_strings, 

906 dest=dest, 

907 nargs=0, 

908 default=default, 

909 type=type, 

910 choices=choices, 

911 required=required, 

912 help=help, 

913 metavar=metavar) 

914 

915 

916 def __call__(self, parser, namespace, values, option_string=None): 

917 if option_string in self.option_strings: 917 ↛ exitline 917 didn't return from function '__call__', because the condition on line 917 was never false

918 setattr(namespace, self.dest, not option_string.startswith('--no-')) 

919 

920 def format_usage(self): 

921 return ' | '.join(self.option_strings) 

922 

923 

924class _StoreAction(Action): 

925 

926 def __init__(self, 

927 option_strings, 

928 dest, 

929 nargs=None, 

930 const=None, 

931 default=None, 

932 type=None, 

933 choices=None, 

934 required=False, 

935 help=None, 

936 metavar=None): 

937 if nargs == 0: 

938 raise ValueError('nargs for store actions must be != 0; if you ' 

939 'have nothing to store, actions such as store ' 

940 'true or store const may be more appropriate') 

941 if const is not None and nargs != OPTIONAL: 

942 raise ValueError('nargs must be %r to supply const' % OPTIONAL) 

943 super(_StoreAction, self).__init__( 

944 option_strings=option_strings, 

945 dest=dest, 

946 nargs=nargs, 

947 const=const, 

948 default=default, 

949 type=type, 

950 choices=choices, 

951 required=required, 

952 help=help, 

953 metavar=metavar) 

954 

955 def __call__(self, parser, namespace, values, option_string=None): 

956 setattr(namespace, self.dest, values) 

957 

958 

959class _StoreConstAction(Action): 

960 

961 def __init__(self, 

962 option_strings, 

963 dest, 

964 const=None, 

965 default=None, 

966 required=False, 

967 help=None, 

968 metavar=None): 

969 super(_StoreConstAction, self).__init__( 

970 option_strings=option_strings, 

971 dest=dest, 

972 nargs=0, 

973 const=const, 

974 default=default, 

975 required=required, 

976 help=help) 

977 

978 def __call__(self, parser, namespace, values, option_string=None): 

979 setattr(namespace, self.dest, self.const) 

980 

981 

982class _StoreTrueAction(_StoreConstAction): 

983 

984 def __init__(self, 

985 option_strings, 

986 dest, 

987 default=False, 

988 required=False, 

989 help=None): 

990 super(_StoreTrueAction, self).__init__( 

991 option_strings=option_strings, 

992 dest=dest, 

993 const=True, 

994 default=default, 

995 required=required, 

996 help=help) 

997 

998 

999class _StoreFalseAction(_StoreConstAction): 

1000 

1001 def __init__(self, 

1002 option_strings, 

1003 dest, 

1004 default=True, 

1005 required=False, 

1006 help=None): 

1007 super(_StoreFalseAction, self).__init__( 

1008 option_strings=option_strings, 

1009 dest=dest, 

1010 const=False, 

1011 default=default, 

1012 required=required, 

1013 help=help) 

1014 

1015 

1016class _AppendAction(Action): 

1017 

1018 def __init__(self, 

1019 option_strings, 

1020 dest, 

1021 nargs=None, 

1022 const=None, 

1023 default=None, 

1024 type=None, 

1025 choices=None, 

1026 required=False, 

1027 help=None, 

1028 metavar=None): 

1029 if nargs == 0: 

1030 raise ValueError('nargs for append actions must be != 0; if arg ' 

1031 'strings are not supplying the value to append, ' 

1032 'the append const action may be more appropriate') 

1033 if const is not None and nargs != OPTIONAL: 

1034 raise ValueError('nargs must be %r to supply const' % OPTIONAL) 

1035 super(_AppendAction, self).__init__( 

1036 option_strings=option_strings, 

1037 dest=dest, 

1038 nargs=nargs, 

1039 const=const, 

1040 default=default, 

1041 type=type, 

1042 choices=choices, 

1043 required=required, 

1044 help=help, 

1045 metavar=metavar) 

1046 

1047 def __call__(self, parser, namespace, values, option_string=None): 

1048 items = getattr(namespace, self.dest, None) 

1049 items = _copy_items(items) 

1050 items.append(values) 

1051 setattr(namespace, self.dest, items) 

1052 

1053 

1054class _AppendConstAction(Action): 

1055 

1056 def __init__(self, 

1057 option_strings, 

1058 dest, 

1059 const=None, 

1060 default=None, 

1061 required=False, 

1062 help=None, 

1063 metavar=None): 

1064 super(_AppendConstAction, self).__init__( 

1065 option_strings=option_strings, 

1066 dest=dest, 

1067 nargs=0, 

1068 const=const, 

1069 default=default, 

1070 required=required, 

1071 help=help, 

1072 metavar=metavar) 

1073 

1074 def __call__(self, parser, namespace, values, option_string=None): 

1075 items = getattr(namespace, self.dest, None) 

1076 items = _copy_items(items) 

1077 items.append(self.const) 

1078 setattr(namespace, self.dest, items) 

1079 

1080 

1081class _CountAction(Action): 

1082 

1083 def __init__(self, 

1084 option_strings, 

1085 dest, 

1086 default=None, 

1087 required=False, 

1088 help=None): 

1089 super(_CountAction, self).__init__( 

1090 option_strings=option_strings, 

1091 dest=dest, 

1092 nargs=0, 

1093 default=default, 

1094 required=required, 

1095 help=help) 

1096 

1097 def __call__(self, parser, namespace, values, option_string=None): 

1098 count = getattr(namespace, self.dest, None) 

1099 if count is None: 

1100 count = 0 

1101 setattr(namespace, self.dest, count + 1) 

1102 

1103 

1104class _HelpAction(Action): 

1105 

1106 def __init__(self, 

1107 option_strings, 

1108 dest=SUPPRESS, 

1109 default=SUPPRESS, 

1110 help=None): 

1111 super(_HelpAction, self).__init__( 

1112 option_strings=option_strings, 

1113 dest=dest, 

1114 default=default, 

1115 nargs=0, 

1116 help=help) 

1117 

1118 def __call__(self, parser, namespace, values, option_string=None): 

1119 parser.print_help() 

1120 parser.exit() 

1121 

1122 

1123class _VersionAction(Action): 

1124 

1125 def __init__(self, 

1126 option_strings, 

1127 version=None, 

1128 dest=SUPPRESS, 

1129 default=SUPPRESS, 

1130 help="show program's version number and exit"): 

1131 super(_VersionAction, self).__init__( 

1132 option_strings=option_strings, 

1133 dest=dest, 

1134 default=default, 

1135 nargs=0, 

1136 help=help) 

1137 self.version = version 

1138 

1139 def __call__(self, parser, namespace, values, option_string=None): 

1140 version = self.version 

1141 if version is None: 1141 ↛ 1142line 1141 didn't jump to line 1142, because the condition on line 1141 was never true

1142 version = parser.version 

1143 formatter = parser._get_formatter() 

1144 formatter.add_text(version) 

1145 parser._print_message(formatter.format_help(), _sys.stdout) 

1146 parser.exit() 

1147 

1148 

1149class _SubParsersAction(Action): 

1150 

1151 class _ChoicesPseudoAction(Action): 

1152 

1153 def __init__(self, name, aliases, help): 

1154 metavar = dest = name 

1155 if aliases: 

1156 metavar += ' (%s)' % ', '.join(aliases) 

1157 sup = super(_SubParsersAction._ChoicesPseudoAction, self) 

1158 sup.__init__(option_strings=[], dest=dest, help=help, 

1159 metavar=metavar) 

1160 

1161 def __init__(self, 

1162 option_strings, 

1163 prog, 

1164 parser_class, 

1165 dest=SUPPRESS, 

1166 required=False, 

1167 help=None, 

1168 metavar=None): 

1169 

1170 self._prog_prefix = prog 

1171 self._parser_class = parser_class 

1172 self._name_parser_map = {} 

1173 self._choices_actions = [] 

1174 

1175 super(_SubParsersAction, self).__init__( 

1176 option_strings=option_strings, 

1177 dest=dest, 

1178 nargs=PARSER, 

1179 choices=self._name_parser_map, 

1180 required=required, 

1181 help=help, 

1182 metavar=metavar) 

1183 

1184 def add_parser(self, name, **kwargs): 

1185 # set prog from the existing prefix 

1186 if kwargs.get('prog') is None: 1186 ↛ 1189line 1186 didn't jump to line 1189, because the condition on line 1186 was never false

1187 kwargs['prog'] = '%s %s' % (self._prog_prefix, name) 

1188 

1189 aliases = kwargs.pop('aliases', ()) 

1190 

1191 if name in self._name_parser_map: 

1192 raise ArgumentError(self, _('conflicting subparser: %s') % name) 

1193 for alias in aliases: 

1194 if alias in self._name_parser_map: 

1195 raise ArgumentError( 

1196 self, _('conflicting subparser alias: %s') % alias) 

1197 

1198 # create a pseudo-action to hold the choice help 

1199 if 'help' in kwargs: 

1200 help = kwargs.pop('help') 

1201 choice_action = self._ChoicesPseudoAction(name, aliases, help) 

1202 self._choices_actions.append(choice_action) 

1203 

1204 # create the parser and add it to the map 

1205 parser = self._parser_class(**kwargs) 

1206 self._name_parser_map[name] = parser 

1207 

1208 # make parser available under aliases also 

1209 for alias in aliases: 

1210 self._name_parser_map[alias] = parser 

1211 

1212 return parser 

1213 

1214 def _get_subactions(self): 

1215 return self._choices_actions 

1216 

1217 def __call__(self, parser, namespace, values, option_string=None): 

1218 parser_name = values[0] 

1219 arg_strings = values[1:] 

1220 

1221 # set the parser name if requested 

1222 if self.dest is not SUPPRESS: 

1223 setattr(namespace, self.dest, parser_name) 

1224 

1225 # select the parser 

1226 try: 

1227 parser = self._name_parser_map[parser_name] 

1228 except KeyError: 

1229 args = {'parser_name': parser_name, 

1230 'choices': ', '.join(self._name_parser_map)} 

1231 msg = _('unknown parser %(parser_name)r (choices: %(choices)s)') % args 

1232 raise ArgumentError(self, msg) 

1233 

1234 # parse all the remaining options into the namespace 

1235 # store any unrecognized options on the object, so that the top 

1236 # level parser can decide what to do with them 

1237 

1238 # In case this subparser defines new defaults, we parse them 

1239 # in a new namespace object and then update the original 

1240 # namespace for the relevant parts. 

1241 subnamespace, arg_strings = parser.parse_known_args(arg_strings, None) 

1242 for key, value in vars(subnamespace).items(): 

1243 setattr(namespace, key, value) 

1244 

1245 if arg_strings: 

1246 vars(namespace).setdefault(_UNRECOGNIZED_ARGS_ATTR, []) 

1247 getattr(namespace, _UNRECOGNIZED_ARGS_ATTR).extend(arg_strings) 

1248 

1249class _ExtendAction(_AppendAction): 

1250 def __call__(self, parser, namespace, values, option_string=None): 

1251 items = getattr(namespace, self.dest, None) 

1252 items = _copy_items(items) 

1253 items.extend(values) 

1254 setattr(namespace, self.dest, items) 

1255 

1256# ============== 

1257# Type classes 

1258# ============== 

1259 

1260class FileType(object): 

1261 """Factory for creating file object types 

1262 

1263 Instances of FileType are typically passed as type= arguments to the 

1264 ArgumentParser add_argument() method. 

1265 

1266 Keyword Arguments: 

1267 - mode -- A string indicating how the file is to be opened. Accepts the 

1268 same values as the builtin open() function. 

1269 - bufsize -- The file's desired buffer size. Accepts the same values as 

1270 the builtin open() function. 

1271 - encoding -- The file's encoding. Accepts the same values as the 

1272 builtin open() function. 

1273 - errors -- A string indicating how encoding and decoding errors are to 

1274 be handled. Accepts the same value as the builtin open() function. 

1275 """ 

1276 

1277 def __init__(self, mode='r', bufsize=-1, encoding=None, errors=None): 

1278 self._mode = mode 

1279 self._bufsize = bufsize 

1280 self._encoding = encoding 

1281 self._errors = errors 

1282 

1283 def __call__(self, string): 

1284 # the special argument "-" means sys.std{in,out} 

1285 if string == '-': 

1286 if 'r' in self._mode: 

1287 return _sys.stdin.buffer if 'b' in self._mode else _sys.stdin 

1288 elif any(c in self._mode for c in 'wax'): 1288 ↛ exit,   1288 ↛ 12912 missed branches: 1) line 1288 didn't finish the generator expression on line 1288, 2) line 1288 didn't jump to line 1291, because the condition on line 1288 was never false

1289 return _sys.stdout.buffer if 'b' in self._mode else _sys.stdout 

1290 else: 

1291 msg = _('argument "-" with mode %r') % self._mode 

1292 raise ValueError(msg) 

1293 

1294 # all other arguments are used as file names 

1295 try: 

1296 return open(string, self._mode, self._bufsize, self._encoding, 

1297 self._errors) 

1298 except OSError as e: 

1299 args = {'filename': string, 'error': e} 

1300 message = _("can't open '%(filename)s': %(error)s") 

1301 raise ArgumentTypeError(message % args) 

1302 

1303 def __repr__(self): 

1304 args = self._mode, self._bufsize 

1305 kwargs = [('encoding', self._encoding), ('errors', self._errors)] 

1306 args_str = ', '.join([repr(arg) for arg in args if arg != -1] + 

1307 ['%s=%r' % (kw, arg) for kw, arg in kwargs 

1308 if arg is not None]) 

1309 return '%s(%s)' % (type(self).__name__, args_str) 

1310 

1311# =========================== 

1312# Optional and Positional Parsing 

1313# =========================== 

1314 

1315class Namespace(_AttributeHolder): 

1316 """Simple object for storing attributes. 

1317 

1318 Implements equality by attribute names and values, and provides a simple 

1319 string representation. 

1320 """ 

1321 

1322 def __init__(self, **kwargs): 

1323 for name in kwargs: 

1324 setattr(self, name, kwargs[name]) 

1325 

1326 def __eq__(self, other): 

1327 if not isinstance(other, Namespace): 

1328 return NotImplemented 

1329 return vars(self) == vars(other) 

1330 

1331 def __contains__(self, key): 

1332 return key in self.__dict__ 

1333 

1334 

1335class _ActionsContainer(object): 

1336 

1337 def __init__(self, 

1338 description, 

1339 prefix_chars, 

1340 argument_default, 

1341 conflict_handler): 

1342 super(_ActionsContainer, self).__init__() 

1343 

1344 self.description = description 

1345 self.argument_default = argument_default 

1346 self.prefix_chars = prefix_chars 

1347 self.conflict_handler = conflict_handler 

1348 

1349 # set up registries 

1350 self._registries = {} 

1351 

1352 # register actions 

1353 self.register('action', None, _StoreAction) 

1354 self.register('action', 'store', _StoreAction) 

1355 self.register('action', 'store_const', _StoreConstAction) 

1356 self.register('action', 'store_true', _StoreTrueAction) 

1357 self.register('action', 'store_false', _StoreFalseAction) 

1358 self.register('action', 'append', _AppendAction) 

1359 self.register('action', 'append_const', _AppendConstAction) 

1360 self.register('action', 'count', _CountAction) 

1361 self.register('action', 'help', _HelpAction) 

1362 self.register('action', 'version', _VersionAction) 

1363 self.register('action', 'parsers', _SubParsersAction) 

1364 self.register('action', 'extend', _ExtendAction) 

1365 

1366 # raise an exception if the conflict handler is invalid 

1367 self._get_handler() 

1368 

1369 # action storage 

1370 self._actions = [] 

1371 self._option_string_actions = {} 

1372 

1373 # groups 

1374 self._action_groups = [] 

1375 self._mutually_exclusive_groups = [] 

1376 

1377 # defaults storage 

1378 self._defaults = {} 

1379 

1380 # determines whether an "option" looks like a negative number 

1381 self._negative_number_matcher = _re.compile(r'^-\d+$|^-\d*\.\d+$') 

1382 

1383 # whether or not there are any optionals that look like negative 

1384 # numbers -- uses a list so it can be shared and edited 

1385 self._has_negative_number_optionals = [] 

1386 

1387 # ==================== 

1388 # Registration methods 

1389 # ==================== 

1390 def register(self, registry_name, value, object): 

1391 registry = self._registries.setdefault(registry_name, {}) 

1392 registry[value] = object 

1393 

1394 def _registry_get(self, registry_name, value, default=None): 

1395 return self._registries[registry_name].get(value, default) 

1396 

1397 # ================================== 

1398 # Namespace default accessor methods 

1399 # ================================== 

1400 def set_defaults(self, **kwargs): 

1401 self._defaults.update(kwargs) 

1402 

1403 # if these defaults match any existing arguments, replace 

1404 # the previous default on the object with the new one 

1405 for action in self._actions: 

1406 if action.dest in kwargs: 

1407 action.default = kwargs[action.dest] 

1408 

1409 def get_default(self, dest): 

1410 for action in self._actions: 

1411 if action.dest == dest and action.default is not None: 

1412 return action.default 

1413 return self._defaults.get(dest, None) 

1414 

1415 

1416 # ======================= 

1417 # Adding argument actions 

1418 # ======================= 

1419 def add_argument(self, *args, **kwargs): 

1420 """ 

1421 add_argument(dest, ..., name=value, ...) 

1422 add_argument(option_string, option_string, ..., name=value, ...) 

1423 """ 

1424 

1425 # if no positional args are supplied or only one is supplied and 

1426 # it doesn't look like an option string, parse a positional 

1427 # argument 

1428 chars = self.prefix_chars 

1429 if not args or len(args) == 1 and args[0][0] not in chars: 

1430 if args and 'dest' in kwargs: 

1431 raise ValueError('dest supplied twice for positional argument') 

1432 kwargs = self._get_positional_kwargs(*args, **kwargs) 

1433 

1434 # otherwise, we're adding an optional argument 

1435 else: 

1436 kwargs = self._get_optional_kwargs(*args, **kwargs) 

1437 

1438 # if no default was supplied, use the parser-level default 

1439 if 'default' not in kwargs: 

1440 dest = kwargs['dest'] 

1441 if dest in self._defaults: 

1442 kwargs['default'] = self._defaults[dest] 

1443 elif self.argument_default is not None: 

1444 kwargs['default'] = self.argument_default 

1445 

1446 # create the action object, and add it to the parser 

1447 action_class = self._pop_action_class(kwargs) 

1448 if not callable(action_class): 

1449 raise ValueError('unknown action "%s"' % (action_class,)) 

1450 action = action_class(**kwargs) 

1451 

1452 # raise an error if the action type is not callable 

1453 type_func = self._registry_get('type', action.type, action.type) 

1454 if not callable(type_func): 

1455 raise ValueError('%r is not callable' % (type_func,)) 

1456 

1457 if type_func is FileType: 

1458 raise ValueError('%r is a FileType class object, instance of it' 

1459 ' must be passed' % (type_func,)) 

1460 

1461 # raise an error if the metavar does not match the type 

1462 if hasattr(self, "_get_formatter"): 

1463 try: 

1464 self._get_formatter()._format_args(action, None) 

1465 except TypeError: 

1466 raise ValueError("length of metavar tuple does not match nargs") 

1467 

1468 return self._add_action(action) 

1469 

1470 def add_argument_group(self, *args, **kwargs): 

1471 group = _ArgumentGroup(self, *args, **kwargs) 

1472 self._action_groups.append(group) 

1473 return group 

1474 

1475 def add_mutually_exclusive_group(self, **kwargs): 

1476 group = _MutuallyExclusiveGroup(self, **kwargs) 

1477 self._mutually_exclusive_groups.append(group) 

1478 return group 

1479 

1480 def _add_action(self, action): 

1481 # resolve any conflicts 

1482 self._check_conflict(action) 

1483 

1484 # add to actions list 

1485 self._actions.append(action) 

1486 action.container = self 

1487 

1488 # index the action by any option strings it has 

1489 for option_string in action.option_strings: 

1490 self._option_string_actions[option_string] = action 

1491 

1492 # set the flag if any option strings look like negative numbers 

1493 for option_string in action.option_strings: 

1494 if self._negative_number_matcher.match(option_string): 

1495 if not self._has_negative_number_optionals: 1495 ↛ 1493line 1495 didn't jump to line 1493, because the condition on line 1495 was never false

1496 self._has_negative_number_optionals.append(True) 

1497 

1498 # return the created action 

1499 return action 

1500 

1501 def _remove_action(self, action): 

1502 self._actions.remove(action) 

1503 

1504 def _add_container_actions(self, container): 

1505 # collect groups by titles 

1506 title_group_map = {} 

1507 for group in self._action_groups: 

1508 if group.title in title_group_map: 1508 ↛ 1509line 1508 didn't jump to line 1509, because the condition on line 1508 was never true

1509 msg = _('cannot merge actions - two groups are named %r') 

1510 raise ValueError(msg % (group.title)) 

1511 title_group_map[group.title] = group 

1512 

1513 # map each action to its group 

1514 group_map = {} 

1515 for group in container._action_groups: 

1516 

1517 # if a group with the title exists, use that, otherwise 

1518 # create a new group matching the container's group 

1519 if group.title not in title_group_map: 

1520 title_group_map[group.title] = self.add_argument_group( 

1521 title=group.title, 

1522 description=group.description, 

1523 conflict_handler=group.conflict_handler) 

1524 

1525 # map the actions to their new group 

1526 for action in group._group_actions: 

1527 group_map[action] = title_group_map[group.title] 

1528 

1529 # add container's mutually exclusive groups 

1530 # NOTE: if add_mutually_exclusive_group ever gains title= and 

1531 # description= then this code will need to be expanded as above 

1532 for group in container._mutually_exclusive_groups: 

1533 mutex_group = self.add_mutually_exclusive_group( 

1534 required=group.required) 

1535 

1536 # map the actions to their new mutex group 

1537 for action in group._group_actions: 

1538 group_map[action] = mutex_group 

1539 

1540 # add all actions to this container or their group 

1541 for action in container._actions: 

1542 group_map.get(action, self)._add_action(action) 

1543 

1544 def _get_positional_kwargs(self, dest, **kwargs): 

1545 # make sure required is not specified 

1546 if 'required' in kwargs: 

1547 msg = _("'required' is an invalid argument for positionals") 

1548 raise TypeError(msg) 

1549 

1550 # mark positional arguments as required if at least one is 

1551 # always required 

1552 if kwargs.get('nargs') not in [OPTIONAL, ZERO_OR_MORE]: 

1553 kwargs['required'] = True 

1554 if kwargs.get('nargs') == ZERO_OR_MORE and 'default' not in kwargs: 

1555 kwargs['required'] = True 

1556 

1557 # return the keyword arguments with no option strings 

1558 return dict(kwargs, dest=dest, option_strings=[]) 

1559 

1560 def _get_optional_kwargs(self, *args, **kwargs): 

1561 # determine short and long option strings 

1562 option_strings = [] 

1563 long_option_strings = [] 

1564 for option_string in args: 

1565 # error on strings that don't start with an appropriate prefix 

1566 if not option_string[0] in self.prefix_chars: 1566 ↛ 1567line 1566 didn't jump to line 1567, because the condition on line 1566 was never true

1567 args = {'option': option_string, 

1568 'prefix_chars': self.prefix_chars} 

1569 msg = _('invalid option string %(option)r: ' 

1570 'must start with a character %(prefix_chars)r') 

1571 raise ValueError(msg % args) 

1572 

1573 # strings starting with two prefix characters are long options 

1574 option_strings.append(option_string) 

1575 if len(option_string) > 1 and option_string[1] in self.prefix_chars: 

1576 long_option_strings.append(option_string) 

1577 

1578 # infer destination, '--foo-bar' -> 'foo_bar' and '-x' -> 'x' 

1579 dest = kwargs.pop('dest', None) 

1580 if dest is None: 

1581 if long_option_strings: 

1582 dest_option_string = long_option_strings[0] 

1583 else: 

1584 dest_option_string = option_strings[0] 

1585 dest = dest_option_string.lstrip(self.prefix_chars) 

1586 if not dest: 

1587 msg = _('dest= is required for options like %r') 

1588 raise ValueError(msg % option_string) 

1589 dest = dest.replace('-', '_') 

1590 

1591 # return the updated keyword arguments 

1592 return dict(kwargs, dest=dest, option_strings=option_strings) 

1593 

1594 def _pop_action_class(self, kwargs, default=None): 

1595 action = kwargs.pop('action', default) 

1596 return self._registry_get('action', action, action) 

1597 

1598 def _get_handler(self): 

1599 # determine function from conflict handler string 

1600 handler_func_name = '_handle_conflict_%s' % self.conflict_handler 

1601 try: 

1602 return getattr(self, handler_func_name) 

1603 except AttributeError: 

1604 msg = _('invalid conflict_resolution value: %r') 

1605 raise ValueError(msg % self.conflict_handler) 

1606 

1607 def _check_conflict(self, action): 

1608 

1609 # find all options that conflict with this option 

1610 confl_optionals = [] 

1611 for option_string in action.option_strings: 

1612 if option_string in self._option_string_actions: 

1613 confl_optional = self._option_string_actions[option_string] 

1614 confl_optionals.append((option_string, confl_optional)) 

1615 

1616 # resolve any conflicts 

1617 if confl_optionals: 

1618 conflict_handler = self._get_handler() 

1619 conflict_handler(action, confl_optionals) 

1620 

1621 def _handle_conflict_error(self, action, conflicting_actions): 

1622 message = ngettext('conflicting option string: %s', 

1623 'conflicting option strings: %s', 

1624 len(conflicting_actions)) 

1625 conflict_string = ', '.join([option_string 

1626 for option_string, action 

1627 in conflicting_actions]) 

1628 raise ArgumentError(action, message % conflict_string) 

1629 

1630 def _handle_conflict_resolve(self, action, conflicting_actions): 

1631 

1632 # remove all conflicting options 

1633 for option_string, action in conflicting_actions: 

1634 

1635 # remove the conflicting option 

1636 action.option_strings.remove(option_string) 

1637 self._option_string_actions.pop(option_string, None) 

1638 

1639 # if the option now has no option string, remove it from the 

1640 # container holding it 

1641 if not action.option_strings: 1641 ↛ 1633line 1641 didn't jump to line 1633, because the condition on line 1641 was never false

1642 action.container._remove_action(action) 

1643 

1644 

1645class _ArgumentGroup(_ActionsContainer): 

1646 

1647 def __init__(self, container, title=None, description=None, **kwargs): 

1648 # add any missing keyword arguments by checking the container 

1649 update = kwargs.setdefault 

1650 update('conflict_handler', container.conflict_handler) 

1651 update('prefix_chars', container.prefix_chars) 

1652 update('argument_default', container.argument_default) 

1653 super_init = super(_ArgumentGroup, self).__init__ 

1654 super_init(description=description, **kwargs) 

1655 

1656 # group attributes 

1657 self.title = title 

1658 self._group_actions = [] 

1659 

1660 # share most attributes with the container 

1661 self._registries = container._registries 

1662 self._actions = container._actions 

1663 self._option_string_actions = container._option_string_actions 

1664 self._defaults = container._defaults 

1665 self._has_negative_number_optionals = \ 

1666 container._has_negative_number_optionals 

1667 self._mutually_exclusive_groups = container._mutually_exclusive_groups 

1668 

1669 def _add_action(self, action): 

1670 action = super(_ArgumentGroup, self)._add_action(action) 

1671 self._group_actions.append(action) 

1672 return action 

1673 

1674 def _remove_action(self, action): 

1675 super(_ArgumentGroup, self)._remove_action(action) 

1676 self._group_actions.remove(action) 

1677 

1678 def add_argument_group(self, *args, **kwargs): 

1679 warnings.warn( 

1680 "Nesting argument groups is deprecated.", 

1681 category=DeprecationWarning, 

1682 stacklevel=2 

1683 ) 

1684 return super().add_argument_group(*args, **kwargs) 

1685 

1686 

1687class _MutuallyExclusiveGroup(_ArgumentGroup): 

1688 

1689 def __init__(self, container, required=False): 

1690 super(_MutuallyExclusiveGroup, self).__init__(container) 

1691 self.required = required 

1692 self._container = container 

1693 

1694 def _add_action(self, action): 

1695 if action.required: 

1696 msg = _('mutually exclusive arguments must be optional') 

1697 raise ValueError(msg) 

1698 action = self._container._add_action(action) 

1699 self._group_actions.append(action) 

1700 return action 

1701 

1702 def _remove_action(self, action): 

1703 self._container._remove_action(action) 

1704 self._group_actions.remove(action) 

1705 

1706 def add_mutually_exclusive_group(self, *args, **kwargs): 

1707 warnings.warn( 

1708 "Nesting mutually exclusive groups is deprecated.", 

1709 category=DeprecationWarning, 

1710 stacklevel=2 

1711 ) 

1712 return super().add_mutually_exclusive_group(*args, **kwargs) 

1713 

1714 

1715class ArgumentParser(_AttributeHolder, _ActionsContainer): 

1716 """Object for parsing command line strings into Python objects. 

1717 

1718 Keyword Arguments: 

1719 - prog -- The name of the program (default: 

1720 ``os.path.basename(sys.argv[0])``) 

1721 - usage -- A usage message (default: auto-generated from arguments) 

1722 - description -- A description of what the program does 

1723 - epilog -- Text following the argument descriptions 

1724 - parents -- Parsers whose arguments should be copied into this one 

1725 - formatter_class -- HelpFormatter class for printing help messages 

1726 - prefix_chars -- Characters that prefix optional arguments 

1727 - fromfile_prefix_chars -- Characters that prefix files containing 

1728 additional arguments 

1729 - argument_default -- The default value for all arguments 

1730 - conflict_handler -- String indicating how to handle conflicts 

1731 - add_help -- Add a -h/-help option 

1732 - allow_abbrev -- Allow long options to be abbreviated unambiguously 

1733 - exit_on_error -- Determines whether or not ArgumentParser exits with 

1734 error info when an error occurs 

1735 """ 

1736 

1737 def __init__(self, 

1738 prog=None, 

1739 usage=None, 

1740 description=None, 

1741 epilog=None, 

1742 parents=[], 

1743 formatter_class=HelpFormatter, 

1744 prefix_chars='-', 

1745 fromfile_prefix_chars=None, 

1746 argument_default=None, 

1747 conflict_handler='error', 

1748 add_help=True, 

1749 allow_abbrev=True, 

1750 exit_on_error=True): 

1751 

1752 superinit = super(ArgumentParser, self).__init__ 

1753 superinit(description=description, 

1754 prefix_chars=prefix_chars, 

1755 argument_default=argument_default, 

1756 conflict_handler=conflict_handler) 

1757 

1758 # default setting for prog 

1759 if prog is None: 

1760 prog = _os.path.basename(_sys.argv[0]) 

1761 

1762 self.prog = prog 

1763 self.usage = usage 

1764 self.epilog = epilog 

1765 self.formatter_class = formatter_class 

1766 self.fromfile_prefix_chars = fromfile_prefix_chars 

1767 self.add_help = add_help 

1768 self.allow_abbrev = allow_abbrev 

1769 self.exit_on_error = exit_on_error 

1770 

1771 add_group = self.add_argument_group 

1772 self._positionals = add_group(_('positional arguments')) 

1773 self._optionals = add_group(_('options')) 

1774 self._subparsers = None 

1775 

1776 # register types 

1777 def identity(string): 

1778 return string 

1779 self.register('type', None, identity) 

1780 

1781 # add help argument if necessary 

1782 # (using explicit default to override global argument_default) 

1783 default_prefix = '-' if '-' in prefix_chars else prefix_chars[0] 

1784 if self.add_help: 

1785 self.add_argument( 

1786 default_prefix+'h', default_prefix*2+'help', 

1787 action='help', default=SUPPRESS, 

1788 help=_('show this help message and exit')) 

1789 

1790 # add parent arguments and defaults 

1791 for parent in parents: 

1792 self._add_container_actions(parent) 

1793 try: 

1794 defaults = parent._defaults 

1795 except AttributeError: 

1796 pass 

1797 else: 

1798 self._defaults.update(defaults) 

1799 

1800 # ======================= 

1801 # Pretty __repr__ methods 

1802 # ======================= 

1803 def _get_kwargs(self): 

1804 names = [ 

1805 'prog', 

1806 'usage', 

1807 'description', 

1808 'formatter_class', 

1809 'conflict_handler', 

1810 'add_help', 

1811 ] 

1812 return [(name, getattr(self, name)) for name in names] 

1813 

1814 # ================================== 

1815 # Optional/Positional adding methods 

1816 # ================================== 

1817 def add_subparsers(self, **kwargs): 

1818 if self._subparsers is not None: 

1819 self.error(_('cannot have multiple subparser arguments')) 

1820 

1821 # add the parser class to the arguments if it's not present 

1822 kwargs.setdefault('parser_class', type(self)) 

1823 

1824 if 'title' in kwargs or 'description' in kwargs: 

1825 title = _(kwargs.pop('title', 'subcommands')) 

1826 description = _(kwargs.pop('description', None)) 

1827 self._subparsers = self.add_argument_group(title, description) 

1828 else: 

1829 self._subparsers = self._positionals 

1830 

1831 # prog defaults to the usage message of this parser, skipping 

1832 # optional arguments and with no "usage:" prefix 

1833 if kwargs.get('prog') is None: 1833 ↛ 1841line 1833 didn't jump to line 1841, because the condition on line 1833 was never false

1834 formatter = self._get_formatter() 

1835 positionals = self._get_positional_actions() 

1836 groups = self._mutually_exclusive_groups 

1837 formatter.add_usage(self.usage, positionals, groups, '') 

1838 kwargs['prog'] = formatter.format_help().strip() 

1839 

1840 # create the parsers action and add it to the positionals list 

1841 parsers_class = self._pop_action_class(kwargs, 'parsers') 

1842 action = parsers_class(option_strings=[], **kwargs) 

1843 self._subparsers._add_action(action) 

1844 

1845 # return the created parsers action 

1846 return action 

1847 

1848 def _add_action(self, action): 

1849 if action.option_strings: 

1850 self._optionals._add_action(action) 

1851 else: 

1852 self._positionals._add_action(action) 

1853 return action 

1854 

1855 def _get_optional_actions(self): 

1856 return [action 

1857 for action in self._actions 

1858 if action.option_strings] 

1859 

1860 def _get_positional_actions(self): 

1861 return [action 

1862 for action in self._actions 

1863 if not action.option_strings] 

1864 

1865 # ===================================== 

1866 # Command line argument parsing methods 

1867 # ===================================== 

1868 def parse_args(self, args=None, namespace=None): 

1869 args, argv = self.parse_known_args(args, namespace) 

1870 if argv: 

1871 msg = _('unrecognized arguments: %s') 

1872 self.error(msg % ' '.join(argv)) 

1873 return args 

1874 

1875 def parse_known_args(self, args=None, namespace=None): 

1876 if args is None: 

1877 # args default to the system args 

1878 args = _sys.argv[1:] 

1879 else: 

1880 # make sure that args are mutable 

1881 args = list(args) 

1882 

1883 # default Namespace built from parser defaults 

1884 if namespace is None: 

1885 namespace = Namespace() 

1886 

1887 # add any action defaults that aren't present 

1888 for action in self._actions: 

1889 if action.dest is not SUPPRESS: 

1890 if not hasattr(namespace, action.dest): 

1891 if action.default is not SUPPRESS: 

1892 setattr(namespace, action.dest, action.default) 

1893 

1894 # add any parser defaults that aren't present 

1895 for dest in self._defaults: 

1896 if not hasattr(namespace, dest): 

1897 setattr(namespace, dest, self._defaults[dest]) 

1898 

1899 # parse the arguments and exit if there are any errors 

1900 if self.exit_on_error: 

1901 try: 

1902 namespace, args = self._parse_known_args(args, namespace) 

1903 except ArgumentError as err: 

1904 self.error(str(err)) 

1905 else: 

1906 namespace, args = self._parse_known_args(args, namespace) 

1907 

1908 if hasattr(namespace, _UNRECOGNIZED_ARGS_ATTR): 

1909 args.extend(getattr(namespace, _UNRECOGNIZED_ARGS_ATTR)) 

1910 delattr(namespace, _UNRECOGNIZED_ARGS_ATTR) 

1911 return namespace, args 

1912 

1913 def _parse_known_args(self, arg_strings, namespace): 

1914 # replace arg strings that are file references 

1915 if self.fromfile_prefix_chars is not None: 

1916 arg_strings = self._read_args_from_files(arg_strings) 

1917 

1918 # map all mutually exclusive arguments to the other arguments 

1919 # they can't occur with 

1920 action_conflicts = {} 

1921 for mutex_group in self._mutually_exclusive_groups: 

1922 group_actions = mutex_group._group_actions 

1923 for i, mutex_action in enumerate(mutex_group._group_actions): 

1924 conflicts = action_conflicts.setdefault(mutex_action, []) 

1925 conflicts.extend(group_actions[:i]) 

1926 conflicts.extend(group_actions[i + 1:]) 

1927 

1928 # find all option indices, and determine the arg_string_pattern 

1929 # which has an 'O' if there is an option at an index, 

1930 # an 'A' if there is an argument, or a '-' if there is a '--' 

1931 option_string_indices = {} 

1932 arg_string_pattern_parts = [] 

1933 arg_strings_iter = iter(arg_strings) 

1934 for i, arg_string in enumerate(arg_strings_iter): 

1935 

1936 # all args after -- are non-options 

1937 if arg_string == '--': 

1938 arg_string_pattern_parts.append('-') 

1939 for arg_string in arg_strings_iter: 

1940 arg_string_pattern_parts.append('A') 

1941 

1942 # otherwise, add the arg to the arg strings 

1943 # and note the index if it was an option 

1944 else: 

1945 option_tuple = self._parse_optional(arg_string) 

1946 if option_tuple is None: 

1947 pattern = 'A' 

1948 else: 

1949 option_string_indices[i] = option_tuple 

1950 pattern = 'O' 

1951 arg_string_pattern_parts.append(pattern) 

1952 

1953 # join the pieces together to form the pattern 

1954 arg_strings_pattern = ''.join(arg_string_pattern_parts) 

1955 

1956 # converts arg strings to the appropriate and then takes the action 

1957 seen_actions = set() 

1958 seen_non_default_actions = set() 

1959 

1960 def take_action(action, argument_strings, option_string=None): 

1961 seen_actions.add(action) 

1962 argument_values = self._get_values(action, argument_strings) 

1963 

1964 # error if this argument is not allowed with other previously 

1965 # seen arguments, assuming that actions that use the default 

1966 # value don't really count as "present" 

1967 if argument_values is not action.default: 

1968 seen_non_default_actions.add(action) 

1969 for conflict_action in action_conflicts.get(action, []): 

1970 if conflict_action in seen_non_default_actions: 

1971 msg = _('not allowed with argument %s') 

1972 action_name = _get_action_name(conflict_action) 

1973 raise ArgumentError(action, msg % action_name) 

1974 

1975 # take the action if we didn't receive a SUPPRESS value 

1976 # (e.g. from a default) 

1977 if argument_values is not SUPPRESS: 

1978 action(self, namespace, argument_values, option_string) 

1979 

1980 # function to convert arg_strings into an optional action 

1981 def consume_optional(start_index): 

1982 

1983 # get the optional identified at this index 

1984 option_tuple = option_string_indices[start_index] 

1985 action, option_string, explicit_arg = option_tuple 

1986 

1987 # identify additional optionals in the same arg string 

1988 # (e.g. -xyz is the same as -x -y -z if no args are required) 

1989 match_argument = self._match_argument 

1990 action_tuples = [] 

1991 while True: 

1992 

1993 # if we found no optional action, skip it 

1994 if action is None: 

1995 extras.append(arg_strings[start_index]) 

1996 return start_index + 1 

1997 

1998 # if there is an explicit argument, try to match the 

1999 # optional's string arguments to only this 

2000 if explicit_arg is not None: 

2001 arg_count = match_argument(action, 'A') 

2002 

2003 # if the action is a single-dash option and takes no 

2004 # arguments, try to parse more single-dash options out 

2005 # of the tail of the option string 

2006 chars = self.prefix_chars 

2007 if ( 

2008 arg_count == 0 

2009 and option_string[1] not in chars 

2010 and explicit_arg != '' 

2011 ): 

2012 action_tuples.append((action, [], option_string)) 

2013 char = option_string[0] 

2014 option_string = char + explicit_arg[0] 

2015 new_explicit_arg = explicit_arg[1:] or None 

2016 optionals_map = self._option_string_actions 

2017 if option_string in optionals_map: 

2018 action = optionals_map[option_string] 

2019 explicit_arg = new_explicit_arg 

2020 else: 

2021 msg = _('ignored explicit argument %r') 

2022 raise ArgumentError(action, msg % explicit_arg) 

2023 

2024 # if the action expect exactly one argument, we've 

2025 # successfully matched the option; exit the loop 

2026 elif arg_count == 1: 

2027 stop = start_index + 1 

2028 args = [explicit_arg] 

2029 action_tuples.append((action, args, option_string)) 

2030 break 

2031 

2032 # error if a double-dash option did not use the 

2033 # explicit argument 

2034 else: 

2035 msg = _('ignored explicit argument %r') 

2036 raise ArgumentError(action, msg % explicit_arg) 

2037 

2038 # if there is no explicit argument, try to match the 

2039 # optional's string arguments with the following strings 

2040 # if successful, exit the loop 

2041 else: 

2042 start = start_index + 1 

2043 selected_patterns = arg_strings_pattern[start:] 

2044 arg_count = match_argument(action, selected_patterns) 

2045 stop = start + arg_count 

2046 args = arg_strings[start:stop] 

2047 action_tuples.append((action, args, option_string)) 

2048 break 

2049 

2050 # add the Optional to the list and return the index at which 

2051 # the Optional's string args stopped 

2052 assert action_tuples 

2053 for action, args, option_string in action_tuples: 

2054 take_action(action, args, option_string) 

2055 return stop 

2056 

2057 # the list of Positionals left to be parsed; this is modified 

2058 # by consume_positionals() 

2059 positionals = self._get_positional_actions() 

2060 

2061 # function to convert arg_strings into positional actions 

2062 def consume_positionals(start_index): 

2063 # match as many Positionals as possible 

2064 match_partial = self._match_arguments_partial 

2065 selected_pattern = arg_strings_pattern[start_index:] 

2066 arg_counts = match_partial(positionals, selected_pattern) 

2067 

2068 # slice off the appropriate arg strings for each Positional 

2069 # and add the Positional and its args to the list 

2070 for action, arg_count in zip(positionals, arg_counts): 

2071 args = arg_strings[start_index: start_index + arg_count] 

2072 start_index += arg_count 

2073 take_action(action, args) 

2074 

2075 # slice off the Positionals that we just parsed and return the 

2076 # index at which the Positionals' string args stopped 

2077 positionals[:] = positionals[len(arg_counts):] 

2078 return start_index 

2079 

2080 # consume Positionals and Optionals alternately, until we have 

2081 # passed the last option string 

2082 extras = [] 

2083 start_index = 0 

2084 if option_string_indices: 

2085 max_option_string_index = max(option_string_indices) 

2086 else: 

2087 max_option_string_index = -1 

2088 while start_index <= max_option_string_index: 

2089 

2090 # consume any Positionals preceding the next option 

2091 next_option_string_index = min([ 

2092 index 

2093 for index in option_string_indices 

2094 if index >= start_index]) 

2095 if start_index != next_option_string_index: 

2096 positionals_end_index = consume_positionals(start_index) 

2097 

2098 # only try to parse the next optional if we didn't consume 

2099 # the option string during the positionals parsing 

2100 if positionals_end_index > start_index: 

2101 start_index = positionals_end_index 

2102 continue 

2103 else: 

2104 start_index = positionals_end_index 

2105 

2106 # if we consumed all the positionals we could and we're not 

2107 # at the index of an option string, there were extra arguments 

2108 if start_index not in option_string_indices: 

2109 strings = arg_strings[start_index:next_option_string_index] 

2110 extras.extend(strings) 

2111 start_index = next_option_string_index 

2112 

2113 # consume the next optional and any arguments for it 

2114 start_index = consume_optional(start_index) 

2115 

2116 # consume any positionals following the last Optional 

2117 stop_index = consume_positionals(start_index) 

2118 

2119 # if we didn't consume all the argument strings, there were extras 

2120 extras.extend(arg_strings[stop_index:]) 

2121 

2122 # make sure all required actions were present and also convert 

2123 # action defaults which were not given as arguments 

2124 required_actions = [] 

2125 for action in self._actions: 

2126 if action not in seen_actions: 

2127 if action.required: 

2128 required_actions.append(_get_action_name(action)) 

2129 else: 

2130 # Convert action default now instead of doing it before 

2131 # parsing arguments to avoid calling convert functions 

2132 # twice (which may fail) if the argument was given, but 

2133 # only if it was defined already in the namespace 

2134 if (action.default is not None and 

2135 isinstance(action.default, str) and 

2136 hasattr(namespace, action.dest) and 

2137 action.default is getattr(namespace, action.dest)): 

2138 setattr(namespace, action.dest, 

2139 self._get_value(action, action.default)) 

2140 

2141 if required_actions: 

2142 self.error(_('the following arguments are required: %s') % 

2143 ', '.join(required_actions)) 

2144 

2145 # make sure all required groups had one option present 

2146 for group in self._mutually_exclusive_groups: 

2147 if group.required: 

2148 for action in group._group_actions: 

2149 if action in seen_non_default_actions: 

2150 break 

2151 

2152 # if no actions were used, report the error 

2153 else: 

2154 names = [_get_action_name(action) 

2155 for action in group._group_actions 

2156 if action.help is not SUPPRESS] 

2157 msg = _('one of the arguments %s is required') 

2158 self.error(msg % ' '.join(names)) 

2159 

2160 # return the updated namespace and the extra arguments 

2161 return namespace, extras 

2162 

2163 def _read_args_from_files(self, arg_strings): 

2164 # expand arguments referencing files 

2165 new_arg_strings = [] 

2166 for arg_string in arg_strings: 

2167 

2168 # for regular arguments, just add them back into the list 

2169 if not arg_string or arg_string[0] not in self.fromfile_prefix_chars: 

2170 new_arg_strings.append(arg_string) 

2171 

2172 # replace arguments referencing files with the file content 

2173 else: 

2174 try: 

2175 with open(arg_string[1:], 

2176 encoding=_sys.getfilesystemencoding(), 

2177 errors=_sys.getfilesystemencodeerrors()) as args_file: 

2178 arg_strings = [] 

2179 for arg_line in args_file.read().splitlines(): 

2180 for arg in self.convert_arg_line_to_args(arg_line): 

2181 arg_strings.append(arg) 

2182 arg_strings = self._read_args_from_files(arg_strings) 

2183 new_arg_strings.extend(arg_strings) 

2184 except OSError as err: 

2185 self.error(str(err)) 

2186 

2187 # return the modified argument list 

2188 return new_arg_strings 

2189 

2190 def convert_arg_line_to_args(self, arg_line): 

2191 return [arg_line] 

2192 

2193 def _match_argument(self, action, arg_strings_pattern): 

2194 # match the pattern for this action to the arg strings 

2195 nargs_pattern = self._get_nargs_pattern(action) 

2196 match = _re.match(nargs_pattern, arg_strings_pattern) 

2197 

2198 # raise an exception if we weren't able to find a match 

2199 if match is None: 

2200 nargs_errors = { 

2201 None: _('expected one argument'), 

2202 OPTIONAL: _('expected at most one argument'), 

2203 ONE_OR_MORE: _('expected at least one argument'), 

2204 } 

2205 msg = nargs_errors.get(action.nargs) 

2206 if msg is None: 

2207 msg = ngettext('expected %s argument', 

2208 'expected %s arguments', 

2209 action.nargs) % action.nargs 

2210 raise ArgumentError(action, msg) 

2211 

2212 # return the number of arguments matched 

2213 return len(match.group(1)) 

2214 

2215 def _match_arguments_partial(self, actions, arg_strings_pattern): 

2216 # progressively shorten the actions list by slicing off the 

2217 # final actions until we find a match 

2218 result = [] 

2219 for i in range(len(actions), 0, -1): 

2220 actions_slice = actions[:i] 

2221 pattern = ''.join([self._get_nargs_pattern(action) 

2222 for action in actions_slice]) 

2223 match = _re.match(pattern, arg_strings_pattern) 

2224 if match is not None: 

2225 result.extend([len(string) for string in match.groups()]) 

2226 break 

2227 

2228 # return the list of arg string counts 

2229 return result 

2230 

2231 def _parse_optional(self, arg_string): 

2232 # if it's an empty string, it was meant to be a positional 

2233 if not arg_string: 

2234 return None 

2235 

2236 # if it doesn't start with a prefix, it was meant to be positional 

2237 if not arg_string[0] in self.prefix_chars: 

2238 return None 

2239 

2240 # if the option string is present in the parser, return the action 

2241 if arg_string in self._option_string_actions: 

2242 action = self._option_string_actions[arg_string] 

2243 return action, arg_string, None 

2244 

2245 # if it's just a single character, it was meant to be positional 

2246 if len(arg_string) == 1: 

2247 return None 

2248 

2249 # if the option string before the "=" is present, return the action 

2250 if '=' in arg_string: 

2251 option_string, explicit_arg = arg_string.split('=', 1) 

2252 if option_string in self._option_string_actions: 

2253 action = self._option_string_actions[option_string] 

2254 return action, option_string, explicit_arg 

2255 

2256 # search through all possible prefixes of the option string 

2257 # and all actions in the parser for possible interpretations 

2258 option_tuples = self._get_option_tuples(arg_string) 

2259 

2260 # if multiple actions match, the option string was ambiguous 

2261 if len(option_tuples) > 1: 

2262 options = ', '.join([option_string 

2263 for action, option_string, explicit_arg in option_tuples]) 

2264 args = {'option': arg_string, 'matches': options} 

2265 msg = _('ambiguous option: %(option)s could match %(matches)s') 

2266 self.error(msg % args) 

2267 

2268 # if exactly one action matched, this segmentation is good, 

2269 # so return the parsed action 

2270 elif len(option_tuples) == 1: 

2271 option_tuple, = option_tuples 

2272 return option_tuple 

2273 

2274 # if it was not found as an option, but it looks like a negative 

2275 # number, it was meant to be positional 

2276 # unless there are negative-number-like options 

2277 if self._negative_number_matcher.match(arg_string): 

2278 if not self._has_negative_number_optionals: 

2279 return None 

2280 

2281 # if it contains a space, it was meant to be a positional 

2282 if ' ' in arg_string: 

2283 return None 

2284 

2285 # it was meant to be an optional but there is no such option 

2286 # in this parser (though it might be a valid option in a subparser) 

2287 return None, arg_string, None 

2288 

2289 def _get_option_tuples(self, option_string): 

2290 result = [] 

2291 

2292 # option strings starting with two prefix characters are only 

2293 # split at the '=' 

2294 chars = self.prefix_chars 

2295 if option_string[0] in chars and option_string[1] in chars: 

2296 if self.allow_abbrev: 

2297 if '=' in option_string: 

2298 option_prefix, explicit_arg = option_string.split('=', 1) 

2299 else: 

2300 option_prefix = option_string 

2301 explicit_arg = None 

2302 for option_string in self._option_string_actions: 

2303 if option_string.startswith(option_prefix): 

2304 action = self._option_string_actions[option_string] 

2305 tup = action, option_string, explicit_arg 

2306 result.append(tup) 

2307 

2308 # single character options can be concatenated with their arguments 

2309 # but multiple character options always have to have their argument 

2310 # separate 

2311 elif option_string[0] in chars and option_string[1] not in chars: 2311 ↛ 2329line 2311 didn't jump to line 2329, because the condition on line 2311 was never false

2312 option_prefix = option_string 

2313 explicit_arg = None 

2314 short_option_prefix = option_string[:2] 

2315 short_explicit_arg = option_string[2:] 

2316 

2317 for option_string in self._option_string_actions: 

2318 if option_string == short_option_prefix: 

2319 action = self._option_string_actions[option_string] 

2320 tup = action, option_string, short_explicit_arg 

2321 result.append(tup) 

2322 elif option_string.startswith(option_prefix): 

2323 action = self._option_string_actions[option_string] 

2324 tup = action, option_string, explicit_arg 

2325 result.append(tup) 

2326 

2327 # shouldn't ever get here 

2328 else: 

2329 self.error(_('unexpected option string: %s') % option_string) 

2330 

2331 # return the collected option tuples 

2332 return result 

2333 

2334 def _get_nargs_pattern(self, action): 

2335 # in all examples below, we have to allow for '--' args 

2336 # which are represented as '-' in the pattern 

2337 nargs = action.nargs 

2338 

2339 # the default (None) is assumed to be a single argument 

2340 if nargs is None: 

2341 nargs_pattern = '(-*A-*)' 

2342 

2343 # allow zero or one arguments 

2344 elif nargs == OPTIONAL: 

2345 nargs_pattern = '(-*A?-*)' 

2346 

2347 # allow zero or more arguments 

2348 elif nargs == ZERO_OR_MORE: 

2349 nargs_pattern = '(-*[A-]*)' 

2350 

2351 # allow one or more arguments 

2352 elif nargs == ONE_OR_MORE: 

2353 nargs_pattern = '(-*A[A-]*)' 

2354 

2355 # allow any number of options or arguments 

2356 elif nargs == REMAINDER: 

2357 nargs_pattern = '([-AO]*)' 

2358 

2359 # allow one argument followed by any number of options or arguments 

2360 elif nargs == PARSER: 

2361 nargs_pattern = '(-*A[-AO]*)' 

2362 

2363 # suppress action, like nargs=0 

2364 elif nargs == SUPPRESS: 

2365 nargs_pattern = '(-*-*)' 

2366 

2367 # all others should be integers 

2368 else: 

2369 nargs_pattern = '(-*%s-*)' % '-*'.join('A' * nargs) 

2370 

2371 # if this is an optional action, -- is not allowed 

2372 if action.option_strings: 

2373 nargs_pattern = nargs_pattern.replace('-*', '') 

2374 nargs_pattern = nargs_pattern.replace('-', '') 

2375 

2376 # return the pattern 

2377 return nargs_pattern 

2378 

2379 # ======================== 

2380 # Alt command line argument parsing, allowing free intermix 

2381 # ======================== 

2382 

2383 def parse_intermixed_args(self, args=None, namespace=None): 

2384 args, argv = self.parse_known_intermixed_args(args, namespace) 

2385 if argv: 2385 ↛ 2386line 2385 didn't jump to line 2386, because the condition on line 2385 was never true

2386 msg = _('unrecognized arguments: %s') 

2387 self.error(msg % ' '.join(argv)) 

2388 return args 

2389 

2390 def parse_known_intermixed_args(self, args=None, namespace=None): 

2391 # returns a namespace and list of extras 

2392 # 

2393 # positional can be freely intermixed with optionals. optionals are 

2394 # first parsed with all positional arguments deactivated. The 'extras' 

2395 # are then parsed. If the parser definition is incompatible with the 

2396 # intermixed assumptions (e.g. use of REMAINDER, subparsers) a 

2397 # TypeError is raised. 

2398 # 

2399 # positionals are 'deactivated' by setting nargs and default to 

2400 # SUPPRESS. This blocks the addition of that positional to the 

2401 # namespace 

2402 

2403 positionals = self._get_positional_actions() 

2404 a = [action for action in positionals 

2405 if action.nargs in [PARSER, REMAINDER]] 

2406 if a: 

2407 raise TypeError('parse_intermixed_args: positional arg' 

2408 ' with nargs=%s'%a[0].nargs) 

2409 

2410 if [action.dest for group in self._mutually_exclusive_groups 

2411 for action in group._group_actions if action in positionals]: 

2412 raise TypeError('parse_intermixed_args: positional in' 

2413 ' mutuallyExclusiveGroup') 

2414 

2415 try: 

2416 save_usage = self.usage 

2417 try: 

2418 if self.usage is None: 

2419 # capture the full usage for use in error messages 

2420 self.usage = self.format_usage()[7:] 

2421 for action in positionals: 

2422 # deactivate positionals 

2423 action.save_nargs = action.nargs 

2424 # action.nargs = 0 

2425 action.nargs = SUPPRESS 

2426 action.save_default = action.default 

2427 action.default = SUPPRESS 

2428 namespace, remaining_args = self.parse_known_args(args, 

2429 namespace) 

2430 for action in positionals: 

2431 # remove the empty positional values from namespace 

2432 if (hasattr(namespace, action.dest) 2432 ↛ 2434line 2432 didn't jump to line 2434, because the condition on line 2432 was never true

2433 and getattr(namespace, action.dest)==[]): 

2434 from warnings import warn 

2435 warn('Do not expect %s in %s' % (action.dest, namespace)) 

2436 delattr(namespace, action.dest) 

2437 finally: 

2438 # restore nargs and usage before exiting 

2439 for action in positionals: 

2440 action.nargs = action.save_nargs 

2441 action.default = action.save_default 

2442 optionals = self._get_optional_actions() 

2443 try: 

2444 # parse positionals. optionals aren't normally required, but 

2445 # they could be, so make sure they aren't. 

2446 for action in optionals: 

2447 action.save_required = action.required 

2448 action.required = False 

2449 for group in self._mutually_exclusive_groups: 

2450 group.save_required = group.required 

2451 group.required = False 

2452 namespace, extras = self.parse_known_args(remaining_args, 

2453 namespace) 

2454 finally: 

2455 # restore parser values before exiting 

2456 for action in optionals: 

2457 action.required = action.save_required 

2458 for group in self._mutually_exclusive_groups: 

2459 group.required = group.save_required 

2460 finally: 

2461 self.usage = save_usage 

2462 return namespace, extras 

2463 

2464 # ======================== 

2465 # Value conversion methods 

2466 # ======================== 

2467 def _get_values(self, action, arg_strings): 

2468 # for everything but PARSER, REMAINDER args, strip out first '--' 

2469 if action.nargs not in [PARSER, REMAINDER]: 

2470 try: 

2471 arg_strings.remove('--') 

2472 except ValueError: 

2473 pass 

2474 

2475 # optional argument produces a default when not present 

2476 if not arg_strings and action.nargs == OPTIONAL: 

2477 if action.option_strings: 

2478 value = action.const 

2479 else: 

2480 value = action.default 

2481 if isinstance(value, str): 

2482 value = self._get_value(action, value) 

2483 self._check_value(action, value) 

2484 

2485 # when nargs='*' on a positional, if there were no command-line 

2486 # args, use the default if it is anything other than None 

2487 elif (not arg_strings and action.nargs == ZERO_OR_MORE and 

2488 not action.option_strings): 

2489 if action.default is not None: 

2490 value = action.default 

2491 self._check_value(action, value) 

2492 else: 

2493 # since arg_strings is always [] at this point 

2494 # there is no need to use self._check_value(action, value) 

2495 value = arg_strings 

2496 

2497 # single argument or optional argument produces a single value 

2498 elif len(arg_strings) == 1 and action.nargs in [None, OPTIONAL]: 

2499 arg_string, = arg_strings 

2500 value = self._get_value(action, arg_string) 

2501 self._check_value(action, value) 

2502 

2503 # REMAINDER arguments convert all values, checking none 

2504 elif action.nargs == REMAINDER: 

2505 value = [self._get_value(action, v) for v in arg_strings] 

2506 

2507 # PARSER arguments convert all values, but check only the first 

2508 elif action.nargs == PARSER: 

2509 value = [self._get_value(action, v) for v in arg_strings] 

2510 self._check_value(action, value[0]) 

2511 

2512 # SUPPRESS argument does not put anything in the namespace 

2513 elif action.nargs == SUPPRESS: 

2514 value = SUPPRESS 

2515 

2516 # all other types of nargs produce a list 

2517 else: 

2518 value = [self._get_value(action, v) for v in arg_strings] 

2519 for v in value: 

2520 self._check_value(action, v) 

2521 

2522 # return the converted value 

2523 return value 

2524 

2525 def _get_value(self, action, arg_string): 

2526 type_func = self._registry_get('type', action.type, action.type) 

2527 if not callable(type_func): 2527 ↛ 2528line 2527 didn't jump to line 2528, because the condition on line 2527 was never true

2528 msg = _('%r is not callable') 

2529 raise ArgumentError(action, msg % type_func) 

2530 

2531 # convert the value to the appropriate type 

2532 try: 

2533 result = type_func(arg_string) 

2534 

2535 # ArgumentTypeErrors indicate errors 

2536 except ArgumentTypeError as err: 

2537 msg = str(err) 

2538 raise ArgumentError(action, msg) 

2539 

2540 # TypeErrors or ValueErrors also indicate errors 

2541 except (TypeError, ValueError): 

2542 name = getattr(action.type, '__name__', repr(action.type)) 

2543 args = {'type': name, 'value': arg_string} 

2544 msg = _('invalid %(type)s value: %(value)r') 

2545 raise ArgumentError(action, msg % args) 

2546 

2547 # return the converted value 

2548 return result 

2549 

2550 def _check_value(self, action, value): 

2551 # converted value must be one of the choices (if specified) 

2552 if action.choices is not None and value not in action.choices: 

2553 args = {'value': value, 

2554 'choices': ', '.join(map(repr, action.choices))} 

2555 msg = _('invalid choice: %(value)r (choose from %(choices)s)') 

2556 raise ArgumentError(action, msg % args) 

2557 

2558 # ======================= 

2559 # Help-formatting methods 

2560 # ======================= 

2561 def format_usage(self): 

2562 formatter = self._get_formatter() 

2563 formatter.add_usage(self.usage, self._actions, 

2564 self._mutually_exclusive_groups) 

2565 return formatter.format_help() 

2566 

2567 def format_help(self): 

2568 formatter = self._get_formatter() 

2569 

2570 # usage 

2571 formatter.add_usage(self.usage, self._actions, 

2572 self._mutually_exclusive_groups) 

2573 

2574 # description 

2575 formatter.add_text(self.description) 

2576 

2577 # positionals, optionals and user-defined groups 

2578 for action_group in self._action_groups: 

2579 formatter.start_section(action_group.title) 

2580 formatter.add_text(action_group.description) 

2581 formatter.add_arguments(action_group._group_actions) 

2582 formatter.end_section() 

2583 

2584 # epilog 

2585 formatter.add_text(self.epilog) 

2586 

2587 # determine help from format above 

2588 return formatter.format_help() 

2589 

2590 def _get_formatter(self): 

2591 return self.formatter_class(prog=self.prog) 

2592 

2593 # ===================== 

2594 # Help-printing methods 

2595 # ===================== 

2596 def print_usage(self, file=None): 

2597 if file is None: 

2598 file = _sys.stdout 

2599 self._print_message(self.format_usage(), file) 

2600 

2601 def print_help(self, file=None): 

2602 if file is None: 

2603 file = _sys.stdout 

2604 self._print_message(self.format_help(), file) 

2605 

2606 def _print_message(self, message, file=None): 

2607 if message: 

2608 if file is None: 2608 ↛ 2609line 2608 didn't jump to line 2609, because the condition on line 2608 was never true

2609 file = _sys.stderr 

2610 file.write(message) 

2611 

2612 # =============== 

2613 # Exiting methods 

2614 # =============== 

2615 def exit(self, status=0, message=None): 

2616 if message: 

2617 self._print_message(message, _sys.stderr) 

2618 _sys.exit(status) 

2619 

2620 def error(self, message): 

2621 """error(message: string) 

2622 

2623 Prints a usage message incorporating the message to stderr and 

2624 exits. 

2625 

2626 If you override this in a subclass, it should not return -- it 

2627 should either exit or raise an exception. 

2628 """ 

2629 self.print_usage(_sys.stderr) 

2630 args = {'prog': self.prog, 'message': message} 

2631 self.exit(2, _('%(prog)s: error: %(message)s\n') % args)