~pivanov/ipython/devel : revision 1152

1

# -*- coding: utf-8 -*-

2

3

# Copyright � 2006 Steven J. Bethard <steven.bethard@gmail.com>.

4

#

5

# Redistribution and use in source and binary forms, with or without

6

# modification, are permitted under the terms of the 3-clause BSD

7

# license. No warranty expressed or implied.

8

# For details, see the accompanying file LICENSE.txt.

9

10

"""Command-line parsing library

11

12

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

13

14

* handles both optional and positional arguments

15

* produces highly informative usage messages

16

* supports parsers that dispatch to sub-parsers

17

18

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

19

command-line and writes the result to a file:

20

21

parser = argparse.ArgumentParser(

22

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

23

parser.add_argument(

24

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

25

help='an integer to be summed')

26

parser.add_argument(

27

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

28

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

29

args = parser.parse_args()

30

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

31

args.log.close()

32

33

The module contains the following public classes:

34

35

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

36

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

37

the parser with actions for optional and positional arguments. Then

38

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

39

command-line into an object with attributes.

40

41

ArgumentError -- The exception raised by ArgumentParser objects when

42

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

43

parsing the command-line are caught by ArgumentParser and emitted

44

as command-line messages.

45

46

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

47

example above shows, instances of FileType are typically passed as

48

the type= argument of add_argument() calls.

49

50

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

51

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

52

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

53

customization of ArgumentParser actions, subclasses of Action may

54

be defined and passed as the action= argument.

55

56

HelpFormatter, RawDescriptionHelpFormatter -- Formatter classes which

57

may be passed as the formatter_class= argument to the

58

ArgumentParser constructor. HelpFormatter is the default, while

59

RawDescriptionHelpFormatter tells the parser not to perform any

60

line-wrapping on description text.

61

62

All other classes in this module are considered implementation details.

63

(Also note that HelpFormatter and RawDescriptionHelpFormatter are only

64

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

65

still considered an implementation detail.)

66

"""

67

68

__version__ = '0.8.0'

69

70

import os as _os

71

import re as _re

72

import sys as _sys

73

import textwrap as _textwrap

74

75

from gettext import gettext as _

76

77

SUPPRESS = '==SUPPRESS=='

78

79

OPTIONAL = '?'

80

ZERO_OR_MORE = '*'

81

ONE_OR_MORE = '+'

82

PARSER = '==PARSER=='

83

84

# =============================

85

# Utility functions and classes

86

# =============================

87

88

class _AttributeHolder(object):

89

"""Abstract base class that provides __repr__.

90

91

The __repr__ method returns a string in the format:

92

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

93

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

94

'_kwarg_names', or by inspecting the instance __dict__.

95

"""

96

97

def __repr__(self):

98

type_name = type(self).__name__

99

arg_strings = []

100

for arg in self._get_args():

101

arg_strings.append(repr(arg))

102

for name, value in self._get_kwargs():

103

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

104

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

105

106

def _get_kwargs(self):

107

return sorted(self.__dict__.items())

108

109

def _get_args(self):

110

return []

111

112

def _ensure_value(namespace, name, value):

113

if getattr(namespace, name, None) is None:

114

setattr(namespace, name, value)

115

return getattr(namespace, name)

116

117

118

119

# ===============

120

# Formatting Help

121

# ===============

122

123

class HelpFormatter(object):

124

125

def __init__(self,

126

prog,

127

indent_increment=2,

128

max_help_position=24,

129

width=None):

130

131

# default setting for width

132

if width is None:

133

try:

134

width = int(_os.environ['COLUMNS'])

135

except (KeyError, ValueError):

136

width = 80

137

width -= 2

138

139

self._prog = prog

140

self._indent_increment = indent_increment

141

self._max_help_position = max_help_position

142

self._width = width

143

144

self._current_indent = 0

145

self._level = 0

146

self._action_max_length = 0

147

148

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

149

self._current_section = self._root_section

150

151

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

152

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

153

154

# ===============================

155

# Section and indentation methods

156

# ===============================

157

158

def _indent(self):

159

self._current_indent += self._indent_increment

160

self._level += 1

161

162

def _dedent(self):

163

self._current_indent -= self._indent_increment

164

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

165

self._level -= 1

166

167

class _Section(object):

168

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

169

self.formatter = formatter

170

self.parent = parent

171

self.heading = heading

172

self.items = []

173

174

def format_help(self):

175

# format the indented section

176

if self.parent is not None:

177

self.formatter._indent()

178

join = self.formatter._join_parts

179

for func, args in self.items:

180

func(*args)

181

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

182

if self.parent is not None:

183

self.formatter._dedent()

184

185

# return nothing if the section was empty

186

if not item_help:

187

return ''

188

189

# add the heading if the section was non-empty

190

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

191

current_indent = self.formatter._current_indent

192

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

193

else:

194

heading = ''

195

196

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

197

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

198

199

def _add_item(self, func, args):

200

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

201

202

# ========================

203

# Message building methods

204

# ========================

205

206

def start_section(self, heading):

207

self._indent()

208

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

209

self._add_item(section.format_help, [])

210

self._current_section = section

211

212

def end_section(self):

213

self._current_section = self._current_section.parent

214

self._dedent()

215

216

def add_text(self, text):

217

if text is not SUPPRESS and text is not None:

218

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

219

220

def add_usage(self, usage, optionals, positionals, prefix=None):

221

if usage is not SUPPRESS:

222

args = usage, optionals, positionals, prefix

223

self._add_item(self._format_usage, args)

224

225

def add_argument(self, action):

226

if action.help is not SUPPRESS:

227

228

# find all invocations

229

get_invocation = self._format_action_invocation

230

invocations = [get_invocation(action)]

231

for subaction in self._iter_indented_subactions(action):

232

invocations.append(get_invocation(subaction))

233

234

# update the maximum item length

235

invocation_length = max(len(s) for s in invocations)

236

action_length = invocation_length + self._current_indent

237

self._action_max_length = max(self._action_max_length,

238

action_length)

239

240

# add the item to the list

241

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

242

243

def add_arguments(self, actions):

244

for action in actions:

245

self.add_argument(action)

246

247

# =======================

248

# Help-formatting methods

249

# =======================

250

251

def format_help(self):

252

help = self._root_section.format_help() % dict(prog=self._prog)

253

if help:

254

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

255

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

256

return help

257

258

def _join_parts(self, part_strings):

259

return ''.join(part

260

for part in part_strings

261

if part and part is not SUPPRESS)

262

263

def _format_usage(self, usage, optionals, positionals, prefix):

264

if prefix is None:

265

prefix = _('usage: ')

266

267

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

268

if usage is None and not optionals and not positionals:

269

usage = '%(prog)s'

270

271

# if optionals and positionals are available, calculate usage

272

elif usage is None:

273

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

274

275

# determine width of "usage: PROG" and width of text

276

prefix_width = len(prefix) + len(usage) + 1

277

prefix_indent = self._current_indent + prefix_width

278

text_width = self._width - self._current_indent

279

280

# put them on one line if they're short enough

281

format = self._format_actions_usage

282

action_usage = format(optionals + positionals)

283

if prefix_width + len(action_usage) + 1 < text_width:

284

usage = '%s %s' % (usage, action_usage)

285

286

# if they're long, wrap optionals and positionals individually

287

else:

288

optional_usage = format(optionals)

289

positional_usage = format(positionals)

290

indent = ' ' * prefix_indent

291

292

# usage is made of PROG, optionals and positionals

293

parts = [usage, ' ']

294

295

# options always get added right after PROG

296

if optional_usage:

297

parts.append(_textwrap.fill(

298

optional_usage, text_width,

299

initial_indent=indent,

300

subsequent_indent=indent).lstrip())

301

302

# if there were options, put arguments on the next line

303

# otherwise, start them right after PROG

304

if positional_usage:

305

part = _textwrap.fill(

306

positional_usage, text_width,

307

initial_indent=indent,

308

subsequent_indent=indent).lstrip()

309

if optional_usage:

310

part = '\n' + indent + part

311

parts.append(part)

312

usage = ''.join(parts)

313

314

# prefix with 'usage:'

315

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

316

317

def _format_actions_usage(self, actions):

318

parts = []

319

for action in actions:

320

if action.help is SUPPRESS:

321

continue

322

323

# produce all arg strings

324

if not action.option_strings:

325

parts.append(self._format_args(action, action.dest))

326

327

# produce the first way to invoke the option in brackets

328

else:

329

option_string = action.option_strings[0]

330

331

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

332

# -s or --long

333

if action.nargs == 0:

334

part = '%s' % option_string

335

336

# if the Optional takes a value, format is:

337

# -s ARGS or --long ARGS

338

else:

339

default = action.dest.upper()

340

args_string = self._format_args(action, default)

341

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

342

343

# make it look optional if it's not required

344

if not action.required:

345

part = '[%s]' % part

346

parts.append(part)

347

348

return ' '.join(parts)

349

350

def _format_text(self, text):

351

text_width = self._width - self._current_indent

352

indent = ' ' * self._current_indent

353

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

354

355

def _format_action(self, action):

356

# determine the required width and the entry label

357

help_position = min(self._action_max_length + 2,

358

self._max_help_position)

359

help_width = self._width - help_position

360

action_width = help_position - self._current_indent - 2

361

action_header = self._format_action_invocation(action)

362

363

# ho nelp; start on same line and add a final newline

364

if not action.help:

365

tup = self._current_indent, '', action_header

366

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

367

368

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

369

elif len(action_header) <= action_width:

370

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

371

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

372

indent_first = 0

373

374

# long action name; start on the next line

375

else:

376

tup = self._current_indent, '', action_header

377

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

378

indent_first = help_position

379

380

# collect the pieces of the action help

381

parts = [action_header]

382

383

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

384

if action.help:

385

help_text = self._expand_help(action)

386

help_lines = self._split_lines(help_text, help_width)

387

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

388

for line in help_lines[1:]:

389

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

390

391

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

392

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

393

parts.append('\n')

394

395

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

396

for subaction in self._iter_indented_subactions(action):

397

parts.append(self._format_action(subaction))

398

399

# return a single string

400

return self._join_parts(parts)

401

402

def _format_action_invocation(self, action):

403

if not action.option_strings:

404

return self._format_metavar(action, action.dest)

405

406

else:

407

parts = []

408

409

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

410

# -s, --long

411

if action.nargs == 0:

412

parts.extend(action.option_strings)

413

414

# if the Optional takes a value, format is:

415

# -s ARGS, --long ARGS

416

else:

417

default = action.dest.upper()

418

args_string = self._format_args(action, default)

419

for option_string in action.option_strings:

420

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

421

422

return ', '.join(parts)

423

424

def _format_metavar(self, action, default_metavar):

425

if action.metavar is not None:

426

name = action.metavar

427

elif action.choices is not None:

428

choice_strs = (str(choice) for choice in action.choices)

429

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

430

else:

431

name = default_metavar

432

return name

433

434

def _format_args(self, action, default_metavar):

435

name = self._format_metavar(action, default_metavar)

436

if action.nargs is None:

437

result = name

438

elif action.nargs == OPTIONAL:

439

result = '[%s]' % name

440

elif action.nargs == ZERO_OR_MORE:

441

result = '[%s [%s ...]]' % (name, name)

442

elif action.nargs == ONE_OR_MORE:

443

result = '%s [%s ...]' % (name, name)

444

elif action.nargs is PARSER:

445

result = '%s ...' % name

446

else:

447

result = ' '.join([name] * action.nargs)

448

return result

449

450

def _expand_help(self, action):

451

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

452

for name, value in params.items():

453

if value is SUPPRESS:

454

del params[name]

455

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

456

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

457

params['choices'] = choices_str

458

return action.help % params

459

460

def _iter_indented_subactions(self, action):

461

try:

462

get_subactions = action._get_subactions

463

except AttributeError:

464

pass

465

else:

466

self._indent()

467

for subaction in get_subactions():

468

yield subaction

469

self._dedent()

470

471

def _split_lines(self, text, width):

472

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

473

return _textwrap.wrap(text, width)

474

475

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

476

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

477

return _textwrap.fill(text, width, initial_indent=indent,

478

subsequent_indent=indent)

479

480

class RawDescriptionHelpFormatter(HelpFormatter):

481

482

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

483

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

484

485

class RawTextHelpFormatter(RawDescriptionHelpFormatter):

486

487

def _split_lines(self, text, width):

488

return text.splitlines()

489

490

# =====================

491

# Options and Arguments

492

# =====================

493

494

class ArgumentError(Exception):

495

"""ArgumentError(message, argument)

496

497

Raised whenever there was an error creating or using an argument

498

(optional or positional).

499

500

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

501

information about the argument that caused it.

502

"""

503

504

def __init__(self, argument, message):

505

if argument.option_strings:

506

self.argument_name = '/'.join(argument.option_strings)

507

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

508

self.argument_name = argument.metavar

509

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

510

self.argument_name = argument.dest

511

else:

512

self.argument_name = None

513

self.message = message

514

515

def __str__(self):

516

if self.argument_name is None:

517

format = '%(message)s'

518

else:

519

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

520

return format % dict(message=self.message,

521

argument_name=self.argument_name)

522

523

# ==============

524

# Action classes

525

# ==============

526

527

class Action(_AttributeHolder):

528

"""Action(*strings, **options)

529

530

Action objects hold the information necessary to convert a

531

set of command-line arguments (possibly including an initial option

532

string) into the desired Python object(s).

533

534

Keyword Arguments:

535

536

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

537

should be associated with this action.

538

539

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

540

541

nargs -- The number of command-line arguments that should be consumed.

542

By default, one argument will be consumed and a single value will

543

be produced. Other values include:

544

* N (an integer) consumes N arguments (and produces a list)

545

* '?' consumes zero or one arguments

546

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

547

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

548

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

549

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

550

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

551

552

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

553

option uses an action that takes no values.

554

555

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

556

557

type -- The type which the command-line arguments should be converted

558

to, should be one of 'string', 'int', 'float', 'complex' or a

559

callable object that accepts a single string argument. If None,

560

'string' is assumed.

561

562

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

563

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

564

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

565

collection.

566

567

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

568

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

569

570

help -- The help string describing the argument.

571

572

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

573

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

574

"""

575

576

577

def __init__(self,

578

option_strings,

579

dest,

580

nargs=None,

581

const=None,

582

default=None,

583

type=None,

584

choices=None,

585

required=False,

586

help=None,

587

metavar=None):

588

self.option_strings = option_strings

589

self.dest = dest

590

self.nargs = nargs

591

self.const = const

592

self.default = default

593

self.type = type

594

self.choices = choices

595

self.required = required

596

self.help = help

597

self.metavar = metavar

598

599

def _get_kwargs(self):

600

names = [

601

'option_strings',

602

'dest',

603

'nargs',

604

'const',

605

'default',

606

'type',

607

'choices',

608

'help',

609

'metavar'

610

]

611

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

612

613

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

614

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

615

616

class _StoreAction(Action):

617

def __init__(self,

618

option_strings,

619

dest,

620

nargs=None,

621

const=None,

622

default=None,

623

type=None,

624

choices=None,

625

required=False,

626

help=None,

627

metavar=None):

628

if nargs == 0:

629

raise ValueError('nargs must be > 0')

630

if const is not None and nargs != OPTIONAL:

631

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

632

super(_StoreAction, self).__init__(

633

option_strings=option_strings,

634

dest=dest,

635

nargs=nargs,

636

const=const,

637

default=default,

638

type=type,

639

choices=choices,

640

required=required,

641

help=help,

642

metavar=metavar)

643

644

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

645

setattr(namespace, self.dest, values)

646

647

class _StoreConstAction(Action):

648

def __init__(self,

649

option_strings,

650

dest,

651

const,

652

default=None,

653

required=False,

654

help=None,

655

metavar=None):

656

super(_StoreConstAction, self).__init__(

657

option_strings=option_strings,

658

dest=dest,

659

nargs=0,

660

const=const,

661

default=default,

662

required=required,

663

help=help)

664

665

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

666

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

667

668

class _StoreTrueAction(_StoreConstAction):

669

def __init__(self,

670

option_strings,

671

dest,

672

default=False,

673

required=False,

674

help=None):

675

super(_StoreTrueAction, self).__init__(

676

option_strings=option_strings,

677

dest=dest,

678

const=True,

679

default=default,

680

required=required,

681

help=help)

682

683

class _StoreFalseAction(_StoreConstAction):

684

def __init__(self,

685

option_strings,

686

dest,

687

default=True,

688

required=False,

689

help=None):

690

super(_StoreFalseAction, self).__init__(

691

option_strings=option_strings,

692

dest=dest,

693

const=False,

694

default=default,

695

required=required,

696

help=help)

697

698

class _AppendAction(Action):

699

def __init__(self,

700

option_strings,

701

dest,

702

nargs=None,

703

const=None,

704

default=None,

705

type=None,

706

choices=None,

707

required=False,

708

help=None,

709

metavar=None):

710

if nargs == 0:

711

raise ValueError('nargs must be > 0')

712

if const is not None and nargs != OPTIONAL:

713

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

714

super(_AppendAction, self).__init__(

715

option_strings=option_strings,

716

dest=dest,

717

nargs=nargs,

718

const=const,

719

default=default,

720

type=type,

721

choices=choices,

722

required=required,

723

help=help,

724

metavar=metavar)

725

726

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

727

_ensure_value(namespace, self.dest, []).append(values)

728

729

class _AppendConstAction(Action):

730

def __init__(self,

731

option_strings,

732

dest,

733

const,

734

default=None,

735

required=False,

736

help=None,

737

metavar=None):

738

super(_AppendConstAction, self).__init__(

739

option_strings=option_strings,

740

dest=dest,

741

nargs=0,

742

const=const,

743

default=default,

744

required=required,

745

help=help,

746

metavar=metavar)

747

748

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

749

_ensure_value(namespace, self.dest, []).append(self.const)

750

751

class _CountAction(Action):

752

def __init__(self,

753

option_strings,

754

dest,

755

default=None,

756

required=False,

757

help=None):

758

super(_CountAction, self).__init__(

759

option_strings=option_strings,

760

dest=dest,

761

nargs=0,

762

default=default,

763

required=required,

764

help=help)

765

766

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

767

new_count = _ensure_value(namespace, self.dest, 0) + 1

768

setattr(namespace, self.dest, new_count)

769

770

class _HelpAction(Action):

771

def __init__(self,

772

option_strings,

773

dest=SUPPRESS,

774

default=SUPPRESS,

775

help=None):

776

super(_HelpAction, self).__init__(

777

option_strings=option_strings,

778

dest=dest,

779

default=default,

780

nargs=0,

781

help=help)

782

783

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

784

parser.print_help()

785

parser.exit()

786

787

class _VersionAction(Action):

788

def __init__(self,

789

option_strings,

790

dest=SUPPRESS,

791

default=SUPPRESS,

792

help=None):

793

super(_VersionAction, self).__init__(

794

option_strings=option_strings,

795

dest=dest,

796

default=default,

797

nargs=0,

798

help=help)

799

800

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

801

parser.print_version()

802

parser.exit()

803

804

class _SubParsersAction(Action):

805

806

class _ChoicesPseudoAction(Action):

807

def __init__(self, name, help):

808

sup = super(_SubParsersAction._ChoicesPseudoAction, self)

809

sup.__init__(option_strings=[], dest=name, help=help)

810

811

812

def __init__(self,

813

option_strings,

814

prog,

815

parser_class,

816

dest=SUPPRESS,

817

help=None,

818

metavar=None):

819

820

self._prog_prefix = prog

821

self._parser_class = parser_class

822

self._name_parser_map = {}

823

self._choices_actions = []

824

825

super(_SubParsersAction, self).__init__(

826

option_strings=option_strings,

827

dest=dest,

828

nargs=PARSER,

829

choices=self._name_parser_map,

830

help=help,

831

metavar=metavar)

832

833

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

834

# set prog from the existing prefix

835

if kwargs.get('prog') is None:

836

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

837

838

# create a pseudo-action to hold the choice help

839

if 'help' in kwargs:

840

help = kwargs.pop('help')

841

choice_action = self._ChoicesPseudoAction(name, help)

842

self._choices_actions.append(choice_action)

843

844

# create the parser and add it to the map

845

parser = self._parser_class(**kwargs)

846

self._name_parser_map[name] = parser

847

return parser

848

849

def _get_subactions(self):

850

return self._choices_actions

851

852

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

853

parser_name = values[0]

854

arg_strings = values[1:]

855

856

# set the parser name if requested

857

if self.dest is not SUPPRESS:

858

setattr(namespace, self.dest, parser_name)

859

860

# select the parser

861

try:

862

parser = self._name_parser_map[parser_name]

863

except KeyError:

864

tup = parser_name, ', '.join(self._name_parser_map)

865

msg = _('unknown parser %r (choices: %s)' % tup)

866

raise ArgumentError(self, msg)

867

868

# parse all the remaining options into the namespace

869

parser.parse_args(arg_strings, namespace)

870

871

872

# ==============

873

# Type classes

874

# ==============

875

876

class FileType(object):

877

"""Factory for creating file object types

878

879

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

880

ArgumentParser add_argument() method.

881

882

Keyword Arguments:

883

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

884

same values as the builtin open() function.

885

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

886

the builtin open() function.

887

"""

888

def __init__(self, mode='r', bufsize=None):

889

self._mode = mode

890

self._bufsize = bufsize

891

892

def __call__(self, string):

893

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

894

if string == '-':

895

if self._mode == 'r':

896

return _sys.stdin

897

elif self._mode == 'w':

898

return _sys.stdout

899

else:

900

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

901

raise ValueError(msg)

902

903

# all other arguments are used as file names

904

if self._bufsize:

905

return open(string, self._mode, self._bufsize)

906

else:

907

return open(string, self._mode)

908

909

910

# ===========================

911

# Optional and Positional Parsing

912

# ===========================

913

914

class Namespace(_AttributeHolder):

915

916

def __init__(self, **kwargs):

917

for name, value in kwargs.iteritems():

918

setattr(self, name, value)

919

920

def __eq__(self, other):

921

return vars(self) == vars(other)

922

923

def __ne__(self, other):

924

return not (self == other)

925

926

927

class _ActionsContainer(object):

928

def __init__(self,

929

description,

930

prefix_chars,

931

argument_default,

932

conflict_handler):

933

super(_ActionsContainer, self).__init__()

934

935

self.description = description

936

self.argument_default = argument_default

937

self.prefix_chars = prefix_chars

938

self.conflict_handler = conflict_handler

939

940

# set up registries

941

self._registries = {}

942

943

# register actions

944

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

945

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

946

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

947

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

948

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

949

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

950

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

951

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

952

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

953

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

954

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

955

956

# raise an exception if the conflict handler is invalid

957

self._get_handler()

958

959

# action storage

960

self._optional_actions_list = []

961

self._positional_actions_list = []

962

self._positional_actions_full_list = []

963

self._option_strings = {}

964

965

# defaults storage

966

self._defaults = {}

967

968

# ====================

969

# Registration methods

970

# ====================

971

972

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

973

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

974

registry[value] = object

975

976

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

977

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

978

979

# ==================================

980

# Namespace default settings methods

981

# ==================================

982

983

def set_defaults(self, **kwargs):

984

self._defaults.update(kwargs)

985

986

# if these defaults match any existing arguments, replace

987

# the previous default on the object with the new one

988

for action_list in [self._option_strings.values(),

989

self._positional_actions_full_list]:

990

for action in action_list:

991

if action.dest in kwargs:

992

action.default = kwargs[action.dest]

993

994

# =======================

995

# Adding argument actions

996

# =======================

997

998

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

999

"""

1000

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

1001

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

1002

"""

1003

1004

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

1005

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

1006

# argument

1007

chars = self.prefix_chars

1008

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

1009

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

1010

1011

# otherwise, we're adding an optional argument

1012

else:

1013

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

1014

1015

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

1016

if 'default' not in kwargs:

1017

dest = kwargs['dest']

1018

if dest in self._defaults:

1019

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

1020

elif self.argument_default is not None:

1021

kwargs['default'] = self.argument_default

1022

1023

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

1024

action_class = self._pop_action_class(kwargs)

1025

action = action_class(**kwargs)

1026

return self._add_action(action)

1027

1028

def _add_action(self, action):

1029

# resolve any conflicts

1030

self._check_conflict(action)

1031

1032

# add to optional or positional list

1033

if action.option_strings:

1034

self._optional_actions_list.append(action)

1035

else:

1036

self._positional_actions_list.append(action)

1037

self._positional_actions_full_list.append(action)

1038

action.container = self

1039

1040

# index the action by any option strings it has

1041

for option_string in action.option_strings:

1042

self._option_strings[option_string] = action

1043

1044

# return the created action

1045

return action

1046

1047

def _add_container_actions(self, container):

1048

for action in container._optional_actions_list:

1049

self._add_action(action)

1050

for action in container._positional_actions_list:

1051

self._add_action(action)

1052

1053

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

1054

# make sure required is not specified

1055

if 'required' in kwargs:

1056

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

1057

raise TypeError(msg)

1058

1059

# return the keyword arguments with no option strings

1060

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

1061

1062

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

1063

# determine short and long option strings

1064

option_strings = []

1065

long_option_strings = []

1066

for option_string in args:

1067

# error on one-or-fewer-character option strings

1068

if len(option_string) < 2:

1069

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

1070

'must be at least two characters long')

1071

raise ValueError(msg % option_string)

1072

1073

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

1074

if not option_string[0] in self.prefix_chars:

1075

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

1076

'must start with a character %r')

1077

tup = option_string, self.prefix_chars

1078

raise ValueError(msg % tup)

1079

1080

# error on strings that are all prefix characters

1081

if not (set(option_string) - set(self.prefix_chars)):

1082

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

1083

'must contain characters other than %r')

1084

tup = option_string, self.prefix_chars

1085

raise ValueError(msg % tup)

1086

1087

# strings starting with two prefix characters are long options

1088

option_strings.append(option_string)

1089

if option_string[0] in self.prefix_chars:

1090

if option_string[1] in self.prefix_chars:

1091

long_option_strings.append(option_string)

1092

1093

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

1094

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

1095

if dest is None:

1096

if long_option_strings:

1097

dest_option_string = long_option_strings[0]

1098

else:

1099

dest_option_string = option_strings[0]

1100

dest = dest_option_string.lstrip(self.prefix_chars)

1101

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

1102

1103

# return the updated keyword arguments

1104

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

1105

1106

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

1107

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

1108

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

1109

1110

def _get_handler(self):

1111

# determine function from conflict handler string

1112

handler_func_name = '_handle_conflict_%s' % self.conflict_handler

1113

try:

1114

return getattr(self, handler_func_name)

1115

except AttributeError:

1116

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

1117

raise ValueError(msg % self.conflict_handler)

1118

1119

def _check_conflict(self, action):

1120

1121

# find all options that conflict with this option

1122

confl_optionals = []

1123

for option_string in action.option_strings:

1124

if option_string in self._option_strings:

1125

confl_optional = self._option_strings[option_string]

1126

confl_optionals.append((option_string, confl_optional))

1127

1128

# resolve any conflicts

1129

if confl_optionals:

1130

conflict_handler = self._get_handler()

1131

conflict_handler(action, confl_optionals)

1132

1133

def _handle_conflict_error(self, action, conflicting_actions):

1134

message = _('conflicting option string(s): %s')

1135

conflict_string = ', '.join(option_string

1136

for option_string, action

1137

in conflicting_actions)

1138

raise ArgumentError(action, message % conflict_string)

1139

1140

def _handle_conflict_resolve(self, action, conflicting_actions):

1141

1142

# remove all conflicting options

1143

for option_string, action in conflicting_actions:

1144

1145

# remove the conflicting option

1146

action.option_strings.remove(option_string)

1147

self._option_strings.pop(option_string, None)

1148

1149

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

1150

# container holding it

1151

if not action.option_strings:

1152

action.container._optional_actions_list.remove(action)

1153

1154

1155

class _ArgumentGroup(_ActionsContainer):

1156

1157

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

1158

# add any missing keyword arguments by checking the container

1159

update = kwargs.setdefault

1160

update('conflict_handler', container.conflict_handler)

1161

update('prefix_chars', container.prefix_chars)

1162

update('argument_default', container.argument_default)

1163

super_init = super(_ArgumentGroup, self).__init__

1164

super_init(description=description, **kwargs)

1165

1166

self.title = title

1167

self._registries = container._registries

1168

self._positional_actions_full_list = container._positional_actions_full_list

1169

self._option_strings = container._option_strings

1170

self._defaults = container._defaults

1171

1172

1173

class ArgumentParser(_AttributeHolder, _ActionsContainer):

1174

1175

def __init__(self,

1176

prog=None,

1177

usage=None,

1178

description=None,

1179

epilog=None,

1180

version=None,

1181

parents=[],

1182

formatter_class=HelpFormatter,

1183

prefix_chars='-',

1184

argument_default=None,

1185

conflict_handler='error',

1186

add_help=True):

1187

1188

superinit = super(ArgumentParser, self).__init__

1189

superinit(description=description,

1190

prefix_chars=prefix_chars,

1191

argument_default=argument_default,

1192

conflict_handler=conflict_handler)

1193

1194

# default setting for prog

1195

if prog is None:

1196

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

1197

1198

self.prog = prog

1199

self.usage = usage

1200

self.epilog = epilog

1201

self.version = version

1202

self.formatter_class = formatter_class

1203

self.add_help = add_help

1204

1205

self._argument_group_class = _ArgumentGroup

1206

self._has_subparsers = False

1207

self._argument_groups = []

1208

1209

# register types

1210

def identity(string):

1211

return string

1212

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

1213

1214

# add help and version arguments if necessary

1215

# (using explicit default to override global argument_default)

1216

if self.add_help:

1217

self.add_argument(

1218

'-h', '--help', action='help', default=SUPPRESS,

1219

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

1220

if self.version:

1221

self.add_argument(

1222

'-v', '--version', action='version', default=SUPPRESS,

1223

help=_("show program's version number and exit"))

1224

1225

# add parent arguments and defaults

1226

for parent in parents:

1227

self._add_container_actions(parent)

1228

try:

1229

defaults = parent._defaults

1230

except AttributeError:

1231

pass

1232

else:

1233

self._defaults.update(defaults)

1234

1235

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

1236

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

1237

1238

1239

# =======================

1240

# Pretty __repr__ methods

1241

# =======================

1242

1243

def _get_kwargs(self):

1244

names = [

1245

'prog',

1246

'usage',

1247

'description',

1248

'version',

1249

'formatter_class',

1250

'conflict_handler',

1251

'add_help',

1252

]

1253

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

1254

1255

# ==================================

1256

# Optional/Positional adding methods

1257

# ==================================

1258

1259

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

1260

group = self._argument_group_class(self, *args, **kwargs)

1261

self._argument_groups.append(group)

1262

return group

1263

1264

def add_subparsers(self, **kwargs):

1265

if self._has_subparsers:

1266

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

1267

1268

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

1269

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

1270

1271

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

1272

# optional arguments and with no "usage:" prefix

1273

if kwargs.get('prog') is None:

1274

formatter = self._get_formatter()

1275

formatter.add_usage(self.usage, [],

1276

self._get_positional_actions(), '')

1277

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

1278

1279

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

1280

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

1281

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

1282

self._positional_actions_list.append(action)

1283

self._positional_actions_full_list.append(action)

1284

self._has_subparsers = True

1285

1286

# return the created parsers action

1287

return action

1288

1289

def _add_container_actions(self, container):

1290

super(ArgumentParser, self)._add_container_actions(container)

1291

try:

1292

groups = container._argument_groups

1293

except AttributeError:

1294

pass

1295

else:

1296

for group in groups:

1297

new_group = self.add_argument_group(

1298

title=group.title,

1299

description=group.description,

1300

conflict_handler=group.conflict_handler)

1301

new_group._add_container_actions(group)

1302

1303

def _get_optional_actions(self):

1304

actions = []

1305

actions.extend(self._optional_actions_list)

1306

for argument_group in self._argument_groups:

1307

actions.extend(argument_group._optional_actions_list)

1308

return actions

1309

1310

def _get_positional_actions(self):

1311

return list(self._positional_actions_full_list)

1312

1313

1314

# =====================================

1315

# Command line argument parsing methods

1316

# =====================================

1317

1318

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

1319

# args default to the system args

1320

if args is None:

1321

args = _sys.argv[1:]

1322

1323

# default Namespace built from parser defaults

1324

if namespace is None:

1325

namespace = Namespace()

1326

1327

# add any action defaults that aren't present

1328

optional_actions = self._get_optional_actions()

1329

positional_actions = self._get_positional_actions()

1330

for action in optional_actions + positional_actions:

1331

if action.dest is not SUPPRESS:

1332

if not hasattr(namespace, action.dest):

1333

if action.default is not SUPPRESS:

1334

default = action.default

1335

if isinstance(action.default, basestring):

1336

default = self._get_value(action, default)

1337

setattr(namespace, action.dest, default)

1338

1339

# add any parser defaults that aren't present

1340

for dest, value in self._defaults.iteritems():

1341

if not hasattr(namespace, dest):

1342

setattr(namespace, dest, value)

1343

1344

# parse the arguments and exit if there are any errors

1345

try:

1346

result = self._parse_args(args, namespace)

1347

except ArgumentError, err:

1348

self.error(str(err))

1349

1350

# make sure all required optionals are present

1351

for action in self._get_optional_actions():

1352

if action.required:

1353

if getattr(result, action.dest, None) is None:

1354

opt_strs = '/'.join(action.option_strings)

1355

msg = _('option %s is required' % opt_strs)

1356

self.error(msg)

1357

1358

# return the parsed arguments

1359

return result

1360

1361

def _parse_args(self, arg_strings, namespace):

1362

1363

# find all option indices, and determine the arg_string_pattern

1364

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

1365

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

1366

option_string_indices = {}

1367

arg_string_pattern_parts = []

1368

arg_strings_iter = iter(arg_strings)

1369

for i, arg_string in enumerate(arg_strings_iter):

1370

1371

# all args after -- are non-options

1372

if arg_string == '--':

1373

arg_string_pattern_parts.append('-')

1374

for arg_string in arg_strings_iter:

1375

arg_string_pattern_parts.append('A')

1376

1377

# otherwise, add the arg to the arg strings

1378

# and note the index if it was an option

1379

else:

1380

option_tuple = self._parse_optional(arg_string)

1381

if option_tuple is None:

1382

pattern = 'A'

1383

else:

1384

option_string_indices[i] = option_tuple

1385

pattern = 'O'

1386

arg_string_pattern_parts.append(pattern)

1387

1388

# join the pieces together to form the pattern

1389

arg_strings_pattern = ''.join(arg_string_pattern_parts)

1390

1391

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

1392

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

1393

argument_values = self._get_values(action, argument_strings)

1394

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

1395

# (e.g. from a default)

1396

if argument_values is not SUPPRESS:

1397

action(self, namespace, argument_values, option_string)

1398

1399

# function to convert arg_strings into an optional action

1400

def consume_optional(start_index):

1401

1402

# determine the optional action and parse any explicit

1403

# argument out of the option string

1404

option_tuple = option_string_indices[start_index]

1405

action, option_string, explicit_arg = option_tuple

1406

1407

# loop because single-dash options can be chained

1408

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

1409

match_argument = self._match_argument

1410

action_tuples = []

1411

while True:

1412

1413

# if we found no optional action, raise an error

1414

if action is None:

1415

self.error(_('no such option: %s') % option_string)

1416

1417

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

1418

# optional's string arguments to only this

1419

if explicit_arg is not None:

1420

arg_count = match_argument(action, 'A')

1421

1422

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

1423

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

1424

# of the tail of the option string

1425

chars = self.prefix_chars

1426

if arg_count == 0 and option_string[1] not in chars:

1427

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

1428

parse_optional = self._parse_optional

1429

for char in self.prefix_chars:

1430

option_string = char + explicit_arg

1431

option_tuple = parse_optional(option_string)

1432

if option_tuple[0] is not None:

1433

break

1434

else:

1435

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

1436

raise ArgumentError(action, msg % explicit_arg)

1437

1438

# set the action, etc. for the next loop iteration

1439

action, option_string, explicit_arg = option_tuple

1440

1441

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

1442

# successfully matched the option; exit the loop

1443

elif arg_count == 1:

1444

stop = start_index + 1

1445

args = [explicit_arg]

1446

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

1447

break

1448

1449

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

1450

# explicit argument

1451

else:

1452

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

1453

raise ArgumentError(action, msg % explicit_arg)

1454

1455

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

1456

# optional's string arguments with the following strings

1457

# if successful, exit the loop

1458

else:

1459

start = start_index + 1

1460

selected_patterns = arg_strings_pattern[start:]

1461

arg_count = match_argument(action, selected_patterns)

1462

stop = start + arg_count

1463

args = arg_strings[start:stop]

1464

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

1465

break

1466

1467

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

1468

# the Optional's string args stopped

1469

assert action_tuples

1470

for action, args, option_string in action_tuples:

1471

take_action(action, args, option_string)

1472

return stop

1473

1474

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

1475

# by consume_positionals()

1476

positionals = self._get_positional_actions()

1477

1478

# function to convert arg_strings into positional actions

1479

def consume_positionals(start_index):

1480

# match as many Positionals as possible

1481

match_partial = self._match_arguments_partial

1482

selected_pattern = arg_strings_pattern[start_index:]

1483

arg_counts = match_partial(positionals, selected_pattern)

1484

1485

# slice off the appropriate arg strings for each Positional

1486

# and add the Positional and its args to the list

1487

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

1488

args = arg_strings[start_index: start_index + arg_count]

1489

start_index += arg_count

1490

take_action(action, args)

1491

1492

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

1493

# index at which the Positionals' string args stopped

1494

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

1495

return start_index

1496

1497

# consume Positionals and Optionals alternately, until we have

1498

# passed the last option string

1499

start_index = 0

1500

if option_string_indices:

1501

max_option_string_index = max(option_string_indices)

1502

else:

1503

max_option_string_index = -1

1504

while start_index <= max_option_string_index:

1505

1506

# consume any Positionals preceding the next option

1507

next_option_string_index = min(

1508

index

1509

for index in option_string_indices

1510

if index >= start_index)

1511

if start_index != next_option_string_index:

1512

positionals_end_index = consume_positionals(start_index)

1513

1514

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

1515

# the option string during the positionals parsing

1516

if positionals_end_index > start_index:

1517

start_index = positionals_end_index

1518

continue

1519

else:

1520

start_index = positionals_end_index

1521

1522

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

1523

# at the index of an option string, there were unparseable

1524

# arguments

1525

if start_index not in option_string_indices:

1526

msg = _('extra arguments found: %s')

1527

extras = arg_strings[start_index:next_option_string_index]

1528

self.error(msg % ' '.join(extras))

1529

1530

# consume the next optional and any arguments for it

1531

start_index = consume_optional(start_index)

1532

1533

# consume any positionals following the last Optional

1534

stop_index = consume_positionals(start_index)

1535

1536

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

1537

# many supplied

1538

if stop_index != len(arg_strings):

1539

extras = arg_strings[stop_index:]

1540

self.error(_('extra arguments found: %s') % ' '.join(extras))

1541

1542

# if we didn't use all the Positional objects, there were too few

1543

# arg strings supplied.

1544

if positionals:

1545

self.error(_('too few arguments'))

1546

1547

# return the updated namespace

1548

return namespace

1549

1550

def _match_argument(self, action, arg_strings_pattern):

1551

# match the pattern for this action to the arg strings

1552

nargs_pattern = self._get_nargs_pattern(action)

1553

match = _re.match(nargs_pattern, arg_strings_pattern)

1554

1555

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

1556

if match is None:

1557

nargs_errors = {

1558

None:_('expected one argument'),

1559

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

1560

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

1561

}

1562

default = _('expected %s argument(s)') % action.nargs

1563

msg = nargs_errors.get(action.nargs, default)

1564

raise ArgumentError(action, msg)

1565

1566

# return the number of arguments matched

1567

return len(match.group(1))

1568

1569

def _match_arguments_partial(self, actions, arg_strings_pattern):

1570

# progressively shorten the actions list by slicing off the

1571

# final actions until we find a match

1572

result = []

1573

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

1574

actions_slice = actions[:i]

1575

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

1576

for action in actions_slice)

1577

match = _re.match(pattern, arg_strings_pattern)

1578

if match is not None:

1579

result.extend(len(string) for string in match.groups())

1580

break

1581

1582

# return the list of arg string counts

1583

return result

1584

1585

def _parse_optional(self, arg_string):

1586

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

1587

if not arg_string[0] in self.prefix_chars:

1588

return None

1589

1590

# if it's just dashes, it was meant to be positional

1591

if not arg_string.strip('-'):

1592

return None

1593

1594

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

1595

if arg_string in self._option_strings:

1596

action = self._option_strings[arg_string]

1597

return action, arg_string, None

1598

1599

# search through all possible prefixes of the option string

1600

# and all actions in the parser for possible interpretations

1601

option_tuples = []

1602

prefix_tuples = self._get_option_prefix_tuples(arg_string)

1603

for option_string in self._option_strings:

1604

for option_prefix, explicit_arg in prefix_tuples:

1605

if option_string.startswith(option_prefix):

1606

action = self._option_strings[option_string]

1607

tup = action, option_string, explicit_arg

1608

option_tuples.append(tup)

1609

break

1610

1611

# if multiple actions match, the option string was ambiguous

1612

if len(option_tuples) > 1:

1613

options = ', '.join(opt_str for _, opt_str, _ in option_tuples)

1614

tup = arg_string, options

1615

self.error(_('ambiguous option: %s could match %s') % tup)

1616

1617

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

1618

# so return the parsed action

1619

elif len(option_tuples) == 1:

1620

option_tuple, = option_tuples

1621

return option_tuple

1622

1623

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

1624

# number, it was meant to be positional

1625

if self._negative_number_matcher.match(arg_string):

1626

return None

1627

1628

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

1629

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

1630

return None, arg_string, None

1631

1632

def _get_option_prefix_tuples(self, option_string):

1633

result = []

1634

1635

# option strings starting with two prefix characters are only

1636

# split at the '='

1637

chars = self.prefix_chars

1638

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

1639

if '=' in option_string:

1640

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

1641

else:

1642

option_prefix = option_string

1643

explicit_arg = None

1644

tup = option_prefix, explicit_arg

1645

result.append(tup)

1646

1647

# option strings starting with a single prefix character are

1648

# split at all indices

1649

else:

1650

for first_index, char in enumerate(option_string):

1651

if char not in self.prefix_chars:

1652

break

1653

for i in xrange(len(option_string), first_index, -1):

1654

tup = option_string[:i], option_string[i:] or None

1655

result.append(tup)

1656

1657

# return the collected prefix tuples

1658

return result

1659

1660

def _get_nargs_pattern(self, action):

1661

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

1662

# which are represented as '-' in the pattern

1663

nargs = action.nargs

1664

1665

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

1666

if nargs is None:

1667

nargs_pattern = '(-*A-*)'

1668

1669

# allow zero or one arguments

1670

elif nargs == OPTIONAL:

1671

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

1672

1673

# allow zero or more arguments

1674

elif nargs == ZERO_OR_MORE:

1675

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

1676

1677

# allow one or more arguments

1678

elif nargs == ONE_OR_MORE:

1679

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

1680

1681

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

1682

elif nargs is PARSER:

1683

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

1684

1685

# all others should be integers

1686

else:

1687

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

1688

1689

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

1690

if action.option_strings:

1691

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

1692

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

1693

1694

# return the pattern

1695

return nargs_pattern

1696

1697

# ========================

1698

# Value conversion methods

1699

# ========================

1700

1701

def _get_values(self, action, arg_strings):

1702

# for everything but PARSER args, strip out '--'

1703

if action.nargs is not PARSER:

1704

arg_strings = [s for s in arg_strings if s != '--']

1705

1706

# optional argument produces a default when not present

1707

if not arg_strings and action.nargs == OPTIONAL:

1708

if action.option_strings:

1709

value = action.const

1710

else:

1711

value = action.default

1712

if isinstance(value, basestring):

1713

value = self._get_value(action, value)

1714

self._check_value(action, value)

1715

1716

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

1717

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

1718

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

1719

not action.option_strings):

1720

if action.default is not None:

1721

value = action.default

1722

else:

1723

value = arg_strings

1724

self._check_value(action, value)

1725

1726

# single argument or optional argument produces a single value

1727

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

1728

arg_string, = arg_strings

1729

value = self._get_value(action, arg_string)

1730

self._check_value(action, value)

1731

1732

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

1733

elif action.nargs is PARSER:

1734

value = list(self._get_value(action, v) for v in arg_strings)

1735

self._check_value(action, value[0])

1736

1737

# all other types of nargs produce a list

1738

else:

1739

value = list(self._get_value(action, v) for v in arg_strings)

1740

for v in value:

1741

self._check_value(action, v)

1742

1743

# return the converted value

1744

return value

1745

1746

def _get_value(self, action, arg_string):

1747

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

1748

if not callable(type_func):

1749

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

1750

raise ArgumentError(action, msg % type_func)

1751

1752

# convert the value to the appropriate type

1753

try:

1754

result = type_func(arg_string)

1755

1756

# TypeErrors or ValueErrors indicate errors

1757

except (TypeError, ValueError):

1758

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

1759

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

1760

raise ArgumentError(action, msg % (name, arg_string))

1761

1762

# return the converted value

1763

return result

1764

1765

def _check_value(self, action, value):

1766

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

1767

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

1768

tup = value, ', '.join(map(repr, action.choices))

1769

msg = _('invalid choice: %r (choose from %s)') % tup

1770

raise ArgumentError(action, msg)

1771

1772

1773

1774

# =======================

1775

# Help-formatting methods

1776

# =======================

1777

1778

def format_usage(self):

1779

formatter = self._get_formatter()

1780

formatter.add_usage(self.usage,

1781

self._get_optional_actions(),

1782

self._get_positional_actions())

1783

return formatter.format_help()

1784

1785

def format_help(self):

1786

formatter = self._get_formatter()

1787

1788

# usage

1789

formatter.add_usage(self.usage,

1790

self._get_optional_actions(),

1791

self._get_positional_actions())

1792

1793

# description

1794

formatter.add_text(self.description)

1795

1796

# positionals

1797

formatter.start_section(_('positional arguments'))

1798

formatter.add_arguments(self._positional_actions_list)

1799

formatter.end_section()

1800

1801

# optionals

1802

formatter.start_section(_('optional arguments'))

1803

formatter.add_arguments(self._optional_actions_list)

1804

formatter.end_section()

1805

1806

# user-defined groups

1807

for argument_group in self._argument_groups:

1808

formatter.start_section(argument_group.title)

1809

formatter.add_text(argument_group.description)

1810

formatter.add_arguments(argument_group._positional_actions_list)

1811

formatter.add_arguments(argument_group._optional_actions_list)

1812

formatter.end_section()

1813

1814

# epilog

1815

formatter.add_text(self.epilog)

1816

1817

# determine help from format above

1818

return formatter.format_help()

1819

1820

def format_version(self):

1821

formatter = self._get_formatter()

1822

formatter.add_text(self.version)

1823

return formatter.format_help()

1824

1825

def _get_formatter(self):

1826

return self.formatter_class(prog=self.prog)

1827

1828

# =====================

1829

# Help-printing methods

1830

# =====================

1831

1832

def print_usage(self, file=None):

1833

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

1834

1835

def print_help(self, file=None):

1836

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

1837

1838

def print_version(self, file=None):

1839

self._print_message(self.format_version(), file)

1840

1841

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

1842

if message:

1843

if file is None:

1844

file = _sys.stderr

1845

file.write(message)

1846

1847

1848

# ===============

1849

# Exiting methods

1850

# ===============

1851

1852

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

1853

if message:

1854

_sys.stderr.write(message)

1855

_sys.exit(status)

1856

1857

def error(self, message):

1858

"""error(message: string)

1859

1860

Prints a usage message incorporating the message to stderr and

1861

exits.

1862

1863

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

1864

should either exit or raise an exception.

1865

"""

1866

self.print_usage(_sys.stderr)

1867

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