~dkuhlman/python-training-materials/Materials

<h1>15.4. <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> — Parser for command-line options, arguments and sub-commands<a class="headerlink" href="#module-argparse" title="Permalink to this headline">¶</a></h1>

New in version 2.7.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/2.7/Lib/argparse.py">Lib/argparse.py</a>

Tutorial

This page contains the API reference information. For a more gentle

introduction to Python command-line parsing, have a look at the

<a class="reference internal" href="../howto/argparse.html#id1">argparse tutorial</a>.

</div>

interfaces. The program defines what arguments it requires, and <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a>

will figure out how to parse those out of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><tt class="xref py py-data docutils literal">sys.argv</tt></a>. The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a>

module also automatically generates help and usage messages and issues errors

when users give the program invalid arguments.

<h2>15.4.1. Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>

The following code is a Python program that takes a list of integers and

produces either the sum or the max:

<div class="highlight-python"><div class="highlight"><pre>import argparse

100

101

parser = argparse.ArgumentParser(description='Process some integers.')

102

parser.add_argument('integers', metavar='N', type=int, nargs='+',

103

help='an integer for the accumulator')

104

parser.add_argument('--sum', dest='accumulate', action='store_const',

105

const=sum, default=max,

106

help='sum the integers (default: find the max)')

107

108

args = parser.parse_args()

109

print args.accumulate(args.integers)

110

</pre></div>

111

</div>

112

Assuming the Python code above is saved into a file called <tt class="docutils literal">prog.py</tt>, it can

113

be run at the command line and provides useful help messages:

114

<div class="highlight-python"><div class="highlight"><pre>$ python prog.py -h

115

usage: prog.py [-h] [--sum] N [N ...]

116

117

Process some integers.

118

119

positional arguments:

120

N an integer for the accumulator

121

122

optional arguments:

123

-h, --help show this help message and exit

124

--sum sum the integers (default: find the max)

125

</pre></div>

126

</div>

127

When run with the appropriate arguments, it prints either the sum or the max of

128

the command-line integers:

129

<div class="highlight-python"><div class="highlight"><pre>$ python prog.py 1 2 3 4

130

131

132

$ python prog.py 1 2 3 4 --sum

133

134

</pre></div>

135

</div>

136

If invalid arguments are passed in, it will issue an error:

137

<div class="highlight-python"><div class="highlight"><pre>$ python prog.py a b c

138

usage: prog.py [-h] [--sum] N [N ...]

139

prog.py: error: argument N: invalid int value: 'a'

140

</pre></div>

141

</div>

142

The following sections walk you through this example.

143

144

<h3>15.4.1.1. Creating a parser<a class="headerlink" href="#creating-a-parser" title="Permalink to this headline">¶</a></h3>

145

The first step in using the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> is creating an

146

147

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(description='Process some integers.')

148

</pre></div>

149

</div>

150

The <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> object will hold all the information necessary to

151

parse the command line into Python data types.

152

</div>

153

154

<h3>15.4.1.2. Adding arguments<a class="headerlink" href="#adding-arguments" title="Permalink to this headline">¶</a></h3>

155

Filling an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> with information about program arguments is

156

done by making calls to the <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> method.

157

Generally, these calls tell the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> how to take the strings

158

on the command line and turn them into objects. This information is stored and

159

used when <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> is called. For example:

160

<div class="highlight-python"><div class="highlight"><pre>>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',

161

... help='an integer for the accumulator')

162

163

... const=sum, default=max,

164

... help='sum the integers (default: find the max)')

165

</pre></div>

166

</div>

167

Later, calling <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> will return an object with

168

two attributes, <tt class="docutils literal">integers</tt> and <tt class="docutils literal">accumulate</tt>. The <tt class="docutils literal">integers</tt> attribute

169

will be a list of one or more ints, and the <tt class="docutils literal">accumulate</tt> attribute will be

170

either the <a class="reference internal" href="functions.html#sum" title="sum"><tt class="xref py py-func docutils literal">sum()</tt></a> function, if <tt class="docutils literal">--sum</tt> was specified at the command line,

171

or the <a class="reference internal" href="functions.html#max" title="max"><tt class="xref py py-func docutils literal">max()</tt></a> function if it was not.

172

</div>

173

174

<h3>15.4.1.3. Parsing arguments<a class="headerlink" href="#parsing-arguments" title="Permalink to this headline">¶</a></h3>

175

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> parses arguments through the

176

<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> method. This will inspect the command line,

177

convert each argument to the appropriate type and then invoke the appropriate action.

178

In most cases, this means a simple <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><tt class="xref py py-class docutils literal">Namespace</tt></a> object will be built up from

179

attributes parsed out of the command line:

180

<div class="highlight-python"><div class="highlight"><pre>>>> parser.parse_args(['--sum', '7', '-1', '42'])

181

Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

182

</pre></div>

183

</div>

184

In a script, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> will typically be called with no

185

arguments, and the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> will automatically determine the

186

command-line arguments from <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><tt class="xref py py-data docutils literal">sys.argv</tt></a>.

187

</div>

188

</div>

189

190

<h2>15.4.2. ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Permalink to this headline">¶</a></h2>

191

192

193

class <tt class="descclassname">argparse.</tt><tt class="descname">ArgumentParser</tt><big>(</big>prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True<big>)</big><a class="headerlink" href="#argparse.ArgumentParser" title="Permalink to this definition">¶</a></dt>

194

<dd>Create a new <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> object. All parameters should be passed

195

as keyword arguments. Each parameter has its own more detailed description

196

below, but in short they are:

197

198

<li><a class="reference internal" href="#prog">prog</a> - The name of the program (default: <tt class="docutils literal">sys.argv[0]</tt>)</li>

199

<li><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from

200

arguments added to parser)</li>

201

<li><a class="reference internal" href="#description">description</a> - Text to display before the argument help (default: none)</li>

202

<li><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (default: none)</li>

203

<li><a class="reference internal" href="#parents">parents</a> - A list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> objects whose arguments should

204

also be included</li>

205

<li><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</li>

206

<li><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments

207

(default: ‘-‘)</li>

208

<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from

209

which additional arguments should be read (default: <tt class="docutils literal">None</tt>)</li>

210

<li><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments

211

(default: <tt class="docutils literal">None</tt>)</li>

212

<li><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals

213

(usually unnecessary)</li>

214

<li><a class="reference internal" href="#add-help">add_help</a> - Add a -h/–help option to the parser (default: <tt class="docutils literal">True</tt>)</li>

215

</ul>

216

</dd></dl>

217

218

The following sections describe how each of these are used.

219

220

221

By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> objects uses <tt class="docutils literal">sys.argv[0]</tt> to determine

222

how to display the name of the program in help messages. This default is almost

223

always desirable because it will make the help messages match how the program was

224

invoked on the command line. For example, consider a file named

225

<tt class="docutils literal">myprogram.py</tt> with the following code:

226

<div class="highlight-python"><div class="highlight"><pre>import argparse

227

parser = argparse.ArgumentParser()

228

parser.add_argument('--foo', help='foo help')

229

args = parser.parse_args()

230

</pre></div>

231

</div>

232

The help for this program will display <tt class="docutils literal">myprogram.py</tt> as the program name

233

(regardless of where the program was invoked from):

234

<div class="highlight-python"><div class="highlight"><pre>$ python myprogram.py --help

235

usage: myprogram.py [-h] [--foo FOO]

236

237

optional arguments:

238

-h, --help show this help message and exit

239

--foo FOO foo help

240

$ cd ..

241

$ python subdir\myprogram.py --help

242

usage: myprogram.py [-h] [--foo FOO]

243

244

optional arguments:

245

-h, --help show this help message and exit

246

--foo FOO foo help

247

</pre></div>

248

</div>

249

To change this default behavior, another value can be supplied using the

250

<tt class="docutils literal">prog=</tt> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>:

251

252

>>> parser.print_help()

253

usage: myprogram [-h]

254

255

optional arguments:

256

-h, --help show this help message and exit

257

</pre></div>

258

</div>

259

Note that the program name, whether determined from <tt class="docutils literal">sys.argv[0]</tt> or from the

260

<tt class="docutils literal">prog=</tt> argument, is available to help messages using the <tt class="docutils literal">%(prog)s</tt> format

261

specifier.

262

263

264

>>> parser.print_help()

265

usage: myprogram [-h] [--foo FOO]

266

267

optional arguments:

268

-h, --help show this help message and exit

269

--foo FOO foo of the myprogram program

270

</pre></div>

271

</div>

272

</div>

273

274

<h3>15.4.2.2. usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3>

275

276

arguments it contains:

277

278

279

280

>>> parser.print_help()

281

usage: PROG [-h] [--foo [FOO]] bar [bar ...]

282

283

positional arguments:

284

bar bar help

285

286

optional arguments:

287

-h, --help show this help message and exit

288

--foo [FOO] foo help

289

</pre></div>

290

</div>

291

The default message can be overridden with the <tt class="docutils literal">usage=</tt> keyword argument:

292

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')

293

294

295

>>> parser.print_help()

296

usage: PROG [options]

297

298

positional arguments:

299

bar bar help

300

301

optional arguments:

302

-h, --help show this help message and exit

303

--foo [FOO] foo help

304

</pre></div>

305

</div>

306

The <tt class="docutils literal">%(prog)s</tt> format specifier is available to fill in the program name in

307

your usage messages.

308

</div>

309

310

<h3>15.4.2.3. description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3>

311

Most calls to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> constructor will use the

312

<tt class="docutils literal">description=</tt> keyword argument. This argument gives a brief description of

313

what the program does and how it works. In help messages, the description is

314

displayed between the command-line usage string and the help messages for the

315

various arguments:

316

317

>>> parser.print_help()

318

usage: argparse.py [-h]

319

320

A foo that bars

321

322

optional arguments:

323

-h, --help show this help message and exit

324

</pre></div>

325

</div>

326

By default, the description will be line-wrapped so that it fits within the

327

given space. To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.

328

</div>

329

330

<h3>15.4.2.4. epilog<a class="headerlink" href="#epilog" title="Permalink to this headline">¶</a></h3>

331

Some programs like to display additional description of the program after the

332

description of the arguments. Such text can be specified using the <tt class="docutils literal">epilog=</tt>

333

argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>:

334

335

... description='A foo that bars',

336

... epilog="And that's how you'd foo a bar")

337

>>> parser.print_help()

338

usage: argparse.py [-h]

339

340

A foo that bars

341

342

optional arguments:

343

-h, --help show this help message and exit

344

345

And that's how you'd foo a bar

346

</pre></div>

347

</div>

348

As with the <a class="reference internal" href="#description">description</a> argument, the <tt class="docutils literal">epilog=</tt> text is by default

349

line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a>

350

351

</div>

352

353

<h3>15.4.2.5. parents<a class="headerlink" href="#parents" title="Permalink to this headline">¶</a></h3>

354

Sometimes, several parsers share a common set of arguments. Rather than

355

repeating the definitions of these arguments, a single parser with all the

356

shared arguments and passed to <tt class="docutils literal">parents=</tt> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>

357

can be used. The <tt class="docutils literal">parents=</tt> argument takes a list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>

358

objects, collects all the positional and optional actions from them, and adds

359

these actions to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> object being constructed:

360

<div class="highlight-python"><div class="highlight"><pre>>>> parent_parser = argparse.ArgumentParser(add_help=False)

361

>>> parent_parser.add_argument('--parent', type=int)

362

363

>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])

364

>>> foo_parser.add_argument('foo')

365

>>> foo_parser.parse_args(['--parent', '2', 'XXX'])

366

Namespace(foo='XXX', parent=2)

367

368

>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])

369

>>> bar_parser.add_argument('--bar')

370

>>> bar_parser.parse_args(['--bar', 'YYY'])

371

Namespace(bar='YYY', parent=None)

372

</pre></div>

373

</div>

374

Note that most parent parsers will specify <tt class="docutils literal">add_help=False</tt>. Otherwise, the

375

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> will see two <tt class="docutils literal">-h/--help</tt> options (one in the parent

376

and one in the child) and raise an error.

377

378

Note

379

You must fully initialize the parsers before passing them via <tt class="docutils literal">parents=</tt>.

380

If you change the parent parsers after the child parser, those changes will

381

not be reflected in the child.

382

</div>

383

</div>

384

385

<h3>15.4.2.6. formatter_class<a class="headerlink" href="#formatter-class" title="Permalink to this headline">¶</a></h3>

386

387

specifying an alternate formatting class. Currently, there are three such

388

classes:

389

390

391

class <tt class="descclassname">argparse.</tt><tt class="descname">RawDescriptionHelpFormatter</tt><a class="headerlink" href="#argparse.RawDescriptionHelpFormatter" title="Permalink to this definition">¶</a></dt>

392

393

class <tt class="descclassname">argparse.</tt><tt class="descname">RawTextHelpFormatter</tt><a class="headerlink" href="#argparse.RawTextHelpFormatter" title="Permalink to this definition">¶</a></dt>

394

395

class <tt class="descclassname">argparse.</tt><tt class="descname">ArgumentDefaultsHelpFormatter</tt><a class="headerlink" href="#argparse.ArgumentDefaultsHelpFormatter" title="Permalink to this definition">¶</a></dt>

396

397

398

The first two allow more control over how textual descriptions are displayed,

399

while the last automatically adds information about argument default values.

400

By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> objects line-wrap the <a class="reference internal" href="#description">description</a> and

401

<a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:

402

403

... prog='PROG',

404

... description='''this description

405

... was indented weird

406

... but that is okay''',

407

... epilog='''

408

... likewise for this epilog whose whitespace will

409

... be cleaned up and whose words will be wrapped

410

... across a couple lines''')

411

>>> parser.print_help()

412

usage: PROG [-h]

413

414

this description was indented weird but that is okay

415

416

optional arguments:

417

-h, --help show this help message and exit

418

419

likewise for this epilog whose whitespace will be cleaned up and whose words

420

will be wrapped across a couple lines

421

</pre></div>

422

</div>

423

Passing <a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><tt class="xref py py-class docutils literal">RawDescriptionHelpFormatter</tt></a> as <tt class="docutils literal">formatter_class=</tt>

424

indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and

425

should not be line-wrapped:

426

427

... prog='PROG',

428

... formatter_class=argparse.RawDescriptionHelpFormatter,

429

... description=textwrap.dedent('''\

430

... Please do not mess up this text!

431

... --------------------------------

432

... I have indented it

433

... exactly the way

434

... I want it

435

... '''))

436

>>> parser.print_help()

437

usage: PROG [-h]

438

439

Please do not mess up this text!

440

--------------------------------

441

I have indented it

442

exactly the way

443

I want it

444

445

optional arguments:

446

-h, --help show this help message and exit

447

</pre></div>

448

</div>

449

<a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><tt class="xref py py-class docutils literal">RawTextHelpFormatter</tt></a> maintains whitespace for all sorts of help text,

450

including argument descriptions.

451

The other formatter class available, <a class="reference internal" href="#argparse.ArgumentDefaultsHelpFormatter" title="argparse.ArgumentDefaultsHelpFormatter"><tt class="xref py py-class docutils literal">ArgumentDefaultsHelpFormatter</tt></a>,

452

will add information about the default value of each of the arguments:

453

454

... prog='PROG',

455

... formatter_class=argparse.ArgumentDefaultsHelpFormatter)

456

>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')

457

>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')

458

>>> parser.print_help()

459

usage: PROG [-h] [--foo FOO] [bar [bar ...]]

460

461

positional arguments:

462

bar BAR! (default: [1, 2, 3])

463

464

optional arguments:

465

-h, --help show this help message and exit

466

--foo FOO FOO! (default: 42)

467

</pre></div>

468

</div>

469

</div>

470

471

<h3>15.4.2.7. prefix_chars<a class="headerlink" href="#prefix-chars" title="Permalink to this headline">¶</a></h3>

472

Most command-line options will use <tt class="docutils literal">-</tt> as the prefix, e.g. <tt class="docutils literal">-f/--foo</tt>.

473

Parsers that need to support different or additional prefix

474

characters, e.g. for options

475

like <tt class="docutils literal">+f</tt> or <tt class="docutils literal">/foo</tt>, may specify them using the <tt class="docutils literal">prefix_chars=</tt> argument

476

to the ArgumentParser constructor:

477

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')

478

>>> parser.add_argument('+f')

479

>>> parser.add_argument('++bar')

480

>>> parser.parse_args('+f X ++bar Y'.split())

481

Namespace(bar='Y', f='X')

482

</pre></div>

483

</div>

484

The <tt class="docutils literal">prefix_chars=</tt> argument defaults to <tt class="docutils literal">'-'</tt>. Supplying a set of

485

characters that does not include <tt class="docutils literal">-</tt> will cause <tt class="docutils literal">-f/--foo</tt> options to be

486

disallowed.

487

</div>

488

489

<h3>15.4.2.8. fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Permalink to this headline">¶</a></h3>

490

Sometimes, for example when dealing with a particularly long argument lists, it

491

may make sense to keep the list of arguments in a file rather than typing it out

492

at the command line. If the <tt class="docutils literal">fromfile_prefix_chars=</tt> argument is given to the

493

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> constructor, then arguments that start with any of the

494

specified characters will be treated as files, and will be replaced by the

495

arguments they contain. For example:

496

<div class="highlight-python"><div class="highlight"><pre>>>> with open('args.txt', 'w') as fp:

497

... fp.write('-f\nbar')

498

>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')

499

>>> parser.add_argument('-f')

500

>>> parser.parse_args(['-f', 'foo', '@args.txt'])

501

Namespace(f='bar')

502

</pre></div>

503

</div>

504

Arguments read from a file must by default be one per line (but see also

505

<a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><tt class="xref py py-meth docutils literal">convert_arg_line_to_args()</tt></a>) and are treated as if they

506

were in the same place as the original file referencing argument on the command

507

line. So in the example above, the expression <tt class="docutils literal">['-f', 'foo', '@args.txt']</tt>

508

is considered equivalent to the expression <tt class="docutils literal">['-f', 'foo', '-f', 'bar']</tt>.

509

The <tt class="docutils literal">fromfile_prefix_chars=</tt> argument defaults to <tt class="docutils literal">None</tt>, meaning that

510

arguments will never be treated as file references.

511

</div>

512

513

<h3>15.4.2.9. argument_default<a class="headerlink" href="#argument-default" title="Permalink to this headline">¶</a></h3>

514

Generally, argument defaults are specified either by passing a default to

515

516

<a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><tt class="xref py py-meth docutils literal">set_defaults()</tt></a> methods with a specific set of name-value

517

pairs. Sometimes however, it may be useful to specify a single parser-wide

518

default for arguments. This can be accomplished by passing the

519

<tt class="docutils literal">argument_default=</tt> keyword argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>. For example,

520

to globally suppress attribute creation on <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a>

521

calls, we supply <tt class="docutils literal">argument_default=SUPPRESS</tt>:

522

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)

523

>>> parser.add_argument('--foo')

524

525

>>> parser.parse_args(['--foo', '1', 'BAR'])

526

Namespace(bar='BAR', foo='1')

527

>>> parser.parse_args([])

528

Namespace()

529

</pre></div>

530

</div>

531

</div>

532

533

<h3>15.4.2.10. conflict_handler<a class="headerlink" href="#conflict-handler" title="Permalink to this headline">¶</a></h3>

534

535

string. By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> objects raises an exception if an

536

attempt is made to create an argument with an option string that is already in

537

use:

538

539

540

541

Traceback (most recent call last):

542

..

543

ArgumentError: argument --foo: conflicting option string(s): --foo

544

</pre></div>

545

</div>

546

Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any

547

older arguments with the same option string. To get this behavior, the value

548

<tt class="docutils literal">'resolve'</tt> can be supplied to the <tt class="docutils literal">conflict_handler=</tt> argument of

549

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>:

550

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')

551

552

553

>>> parser.print_help()

554

usage: PROG [-h] [-f FOO] [--foo FOO]

555

556

optional arguments:

557

-h, --help show this help message and exit

558

-f FOO old foo help

559

--foo FOO new foo help

560

</pre></div>

561

</div>

562

Note that <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> objects only remove an action if all of its

563

option strings are overridden. So, in the example above, the old <tt class="docutils literal">-f/--foo</tt>

564

action is retained as the <tt class="docutils literal">-f</tt> action, because only the <tt class="docutils literal">--foo</tt> option

565

string was overridden.

566

</div>

567

568

569

By default, ArgumentParser objects add an option which simply displays

570

the parser’s help message. For example, consider a file named

571

<tt class="docutils literal">myprogram.py</tt> containing the following code:

572

<div class="highlight-python"><div class="highlight"><pre>import argparse

573

parser = argparse.ArgumentParser()

574

575

args = parser.parse_args()

576

</pre></div>

577

</div>

578

If <tt class="docutils literal">-h</tt> or <tt class="docutils literal">--help</tt> is supplied at the command line, the ArgumentParser

579

help will be printed:

580

<div class="highlight-python"><div class="highlight"><pre>$ python myprogram.py --help

581

usage: myprogram.py [-h] [--foo FOO]

582

583

optional arguments:

584

-h, --help show this help message and exit

585

--foo FOO foo help

586

</pre></div>

587

</div>

588

Occasionally, it may be useful to disable the addition of this help option.

589

This can be achieved by passing <tt class="docutils literal">False</tt> as the <tt class="docutils literal">add_help=</tt> argument to

590

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>:

591

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)

592

593

>>> parser.print_help()

594

usage: PROG [--foo FOO]

595

596

optional arguments:

597

--foo FOO foo help

598

</pre></div>

599

</div>

600

The help option is typically <tt class="docutils literal">-h/--help</tt>. The exception to this is

601

if the <tt class="docutils literal">prefix_chars=</tt> is specified and does not include <tt class="docutils literal">-</tt>, in

602

which case <tt class="docutils literal">-h</tt> and <tt class="docutils literal">--help</tt> are not valid options. In

603

this case, the first character in <tt class="docutils literal">prefix_chars</tt> is used to prefix

604

the help options:

605

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')

606

>>> parser.print_help()

607

usage: PROG [+h]

608

609

optional arguments:

610

+h, ++help show this help message and exit

611

</pre></div>

612

</div>

613

</div>

614

</div>

615

616

<h2>15.4.3. The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Permalink to this headline">¶</a></h2>

617

618

619

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">add_argument</tt><big>(</big>name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest]<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.add_argument" title="Permalink to this definition">¶</a></dt>

620

<dd>Define how a single command-line argument should be parsed. Each parameter

621

has its own more detailed description below, but in short they are:

622

623

<li><a class="reference internal" href="#name-or-flags">name or flags</a> - Either a name or a list of option strings, e.g. <tt class="docutils literal">foo</tt>

624

or <tt class="docutils literal">-f, --foo</tt>.</li>

625

<li><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is

626

encountered at the command line.</li>

627

<li><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</li>

628

<li><a class="reference internal" href="#const">const</a> - A constant value required by some <a class="reference internal" href="#action">action</a> and <a class="reference internal" href="#nargs">nargs</a> selections.</li>

629

<li><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the

630

command line.</li>

631

<li><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</li>

632

<li><a class="reference internal" href="#choices">choices</a> - A container of the allowable values for the argument.</li>

633

<li><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted

634

(optionals only).</li>

635

<li><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</li>

636

<li><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</li>

637

<li><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by

638

639

</ul>

640

</dd></dl>

641

642

The following sections describe how each of these are used.

643

644

<h3>15.4.3.1. name or flags<a class="headerlink" href="#name-or-flags" title="Permalink to this headline">¶</a></h3>

645

The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> method must know whether an optional

646

argument, like <tt class="docutils literal">-f</tt> or <tt class="docutils literal">--foo</tt>, or a positional argument, like a list of

647

filenames, is expected. The first arguments passed to

648

649

flags, or a simple argument name. For example, an optional argument could

650

be created like:

651

652

</pre></div>

653

</div>

654

while a positional argument could be created like:

655

656

</pre></div>

657

</div>

658

When <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> is called, optional arguments will be

659

identified by the <tt class="docutils literal">-</tt> prefix, and the remaining arguments will be assumed to

660

be positional:

661

662

663

>>> parser.add_argument('bar')

664

>>> parser.parse_args(['BAR'])

665

Namespace(bar='BAR', foo=None)

666

>>> parser.parse_args(['BAR', '--foo', 'FOO'])

667

Namespace(bar='BAR', foo='FOO')

668

>>> parser.parse_args(['--foo', 'FOO'])

669

usage: PROG [-h] [-f FOO] bar

670

PROG: error: too few arguments

671

</pre></div>

672

</div>

673

</div>

674

675

<h3>15.4.3.2. action<a class="headerlink" href="#action" title="Permalink to this headline">¶</a></h3>

676

677

actions can do just about anything with the command-line arguments associated with

678

them, though most actions simply add an attribute to the object returned by

679

680

how the command-line arguments should be handled. The supplied actions are:

681

<ul>

682

<li><tt class="docutils literal">'store'</tt> - This just stores the argument’s value. This is the default

683

action. For example:

684

685

>>> parser.add_argument('--foo')

686

>>> parser.parse_args('--foo 1'.split())

687

Namespace(foo='1')

688

</pre></div>

689

</div>

690

</li>

691

<li><tt class="docutils literal">'store_const'</tt> - This stores the value specified by the <a class="reference internal" href="#const">const</a> keyword

692

argument. (Note that the <a class="reference internal" href="#const">const</a> keyword argument defaults to the rather

693

unhelpful <tt class="docutils literal">None</tt>.) The <tt class="docutils literal">'store_const'</tt> action is most commonly used with

694

optional arguments that specify some sort of flag. For example:

695

696

697

>>> parser.parse_args('--foo'.split())

698

Namespace(foo=42)

699

</pre></div>

700

</div>

701

</li>

702

<li><tt class="docutils literal">'store_true'</tt> and <tt class="docutils literal">'store_false'</tt> - These are special cases of

703

<tt class="docutils literal">'store_const'</tt> using for storing the values <tt class="docutils literal">True</tt> and <tt class="docutils literal">False</tt>

704

respectively. In addition, they create default values of False and True

705

respectively. For example:

706

707

708

709

710

>>> parser.parse_args('--foo --bar'.split())

711

Namespace(bar=False, baz=True, foo=True)

712

</pre></div>

713

</div>

714

</li>

715

<li><tt class="docutils literal">'append'</tt> - This stores a list, and appends each argument value to the

716

list. This is useful to allow an option to be specified multiple times.

717

Example usage:

718

719

720

>>> parser.parse_args('--foo 1 --foo 2'.split())

721

Namespace(foo=['1', '2'])

722

</pre></div>

723

</div>

724

</li>

725

<li><tt class="docutils literal">'append_const'</tt> - This stores a list, and appends the value specified by

726

the <a class="reference internal" href="#const">const</a> keyword argument to the list. (Note that the <a class="reference internal" href="#const">const</a> keyword

727

argument defaults to <tt class="docutils literal">None</tt>.) The <tt class="docutils literal">'append_const'</tt> action is typically

728

useful when multiple arguments need to store constants to the same list. For

729

example:

730

731

>>> parser.add_argument('--str', dest='types', action='append_const', const=str)

732

>>> parser.add_argument('--int', dest='types', action='append_const', const=int)

733

>>> parser.parse_args('--str --int'.split())

734

Namespace(types=[<type 'str'>, <type 'int'>])

735

</pre></div>

736

</div>

737

</li>

738

<li><tt class="docutils literal">'count'</tt> - This counts the number of times a keyword argument occurs. For

739

example, this is useful for increasing verbosity levels:

740

741

742

>>> parser.parse_args('-vvv'.split())

743

Namespace(verbose=3)

744

</pre></div>

745

</div>

746

</li>

747

<li><tt class="docutils literal">'help'</tt> - This prints a complete help message for all the options in the

748

current parser and then exits. By default a help action is automatically

749

added to the parser. See <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> for details of how the

750

output is created.

751

</li>

752

<li><tt class="docutils literal">'version'</tt> - This expects a <tt class="docutils literal">version=</tt> keyword argument in the

753

754

and exits when invoked:

755

<div class="highlight-python"><div class="highlight"><pre>>>> import argparse

756

>>> parser = argparse.ArgumentParser(prog='PROG')

757

>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')

758

>>> parser.parse_args(['--version'])

759

PROG 2.0

760

</pre></div>

761

</div>

762

</li>

763

</ul>

764

You may also specify an arbitrary action by passing an Action subclass or

765

other object that implements the same interface. The recommended way to do

766

this is to extend <a class="reference internal" href="#argparse.Action" title="argparse.Action"><tt class="xref py py-class docutils literal">Action</tt></a>, overriding the <tt class="docutils literal">__call__</tt> method

767

and optionally the <tt class="docutils literal">__init__</tt> method.

768

An example of a custom action:

769

<div class="highlight-python"><div class="highlight"><pre>>>> class FooAction(argparse.Action):

770

... def __init__(self, option_strings, dest, nargs=None, **kwargs):

771

... if nargs is not None:

772

... raise ValueError("nargs not allowed")

773

... super(FooAction, self).__init__(option_strings, dest, **kwargs)

774

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

775

... print '%r %r %r' % (namespace, values, option_string)

776

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

777

...

778

779

780

781

>>> args = parser.parse_args('1 --foo 2'.split())

782

Namespace(bar=None, foo=None) '1' None

783

Namespace(bar='1', foo=None) '2' '--foo'

784

>>> args

785

Namespace(bar='1', foo='2')

786

</pre></div>

787

</div>

788

For more details, see <a class="reference internal" href="#argparse.Action" title="argparse.Action"><tt class="xref py py-class docutils literal">Action</tt></a>.

789

</div>

790

791

<h3>15.4.3.3. nargs<a class="headerlink" href="#nargs" title="Permalink to this headline">¶</a></h3>

792

ArgumentParser objects usually associate a single command-line argument with a

793

single action to be taken. The <tt class="docutils literal">nargs</tt> keyword argument associates a

794

different number of command-line arguments with a single action. The supported

795

values are:

796

<ul>

797

<li><tt class="docutils literal">N</tt> (an integer). <tt class="docutils literal">N</tt> arguments from the command line will be gathered

798

together into a list. For example:

799

800

801

802

>>> parser.parse_args('c --foo a b'.split())

803

Namespace(bar=['c'], foo=['a', 'b'])

804

</pre></div>

805

</div>

806

Note that <tt class="docutils literal">nargs=1</tt> produces a list of one item. This is different from

807

the default, in which the item is produced by itself.

808

</li>

809

<li><tt class="docutils literal">'?'</tt>. One argument will be consumed from the command line if possible, and

810

produced as a single item. If no command-line argument is present, the value from

811

<a class="reference internal" href="#default">default</a> will be produced. Note that for optional arguments, there is an

812

additional case - the option string is present but not followed by a

813

command-line argument. In this case the value from <a class="reference internal" href="#const">const</a> will be produced. Some

814

examples to illustrate this:

815

816

>>> parser.add_argument('--foo', nargs='?', const='c', default='d')

817

818

>>> parser.parse_args('XX --foo YY'.split())

819

Namespace(bar='XX', foo='YY')

820

>>> parser.parse_args('XX --foo'.split())

821

Namespace(bar='XX', foo='c')

822

>>> parser.parse_args(''.split())

823

Namespace(bar='d', foo='d')

824

</pre></div>

825

</div>

826

One of the more common uses of <tt class="docutils literal">nargs='?'</tt> is to allow optional input and

827

output files:

828

829

>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),

830

... default=sys.stdin)

831

>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),

832

... default=sys.stdout)

833

>>> parser.parse_args(['input.txt', 'output.txt'])

834

Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>,

835

outfile=<open file 'output.txt', mode 'w' at 0x...>)

836

>>> parser.parse_args([])

837

Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,

838

outfile=<open file '<stdout>', mode 'w' at 0x...>)

839

</pre></div>

840

</div>

841

</li>

842

<li><tt class="docutils literal">'*'</tt>. All command-line arguments present are gathered into a list. Note that

843

it generally doesn’t make much sense to have more than one positional argument

844

with <tt class="docutils literal">nargs='*'</tt>, but multiple optional arguments with <tt class="docutils literal">nargs='*'</tt> is

845

possible. For example:

846

847

848

849

850

>>> parser.parse_args('a b --foo x y --bar 1 2'.split())

851

Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

852

</pre></div>

853

</div>

854

</li>

855

<li><tt class="docutils literal">'+'</tt>. Just like <tt class="docutils literal">'*'</tt>, all command-line args present are gathered into a

856

list. Additionally, an error message will be generated if there wasn’t at

857

least one command-line argument present. For example:

858

859

860

>>> parser.parse_args('a b'.split())

861

Namespace(foo=['a', 'b'])

862

863

usage: PROG [-h] foo [foo ...]

864

PROG: error: too few arguments

865

</pre></div>

866

</div>

867

</li>

868

<li><tt class="docutils literal">argparse.REMAINDER</tt>. All the remaining command-line arguments are gathered

869

into a list. This is commonly useful for command line utilities that dispatch

870

to other command line utilities:

871

872

>>> parser.add_argument('--foo')

873

>>> parser.add_argument('command')

874

875

>>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())

876

Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

877

</pre></div>

878

</div>

879

</li>

880

</ul>

881

If the <tt class="docutils literal">nargs</tt> keyword argument is not provided, the number of arguments consumed

882

is determined by the <a class="reference internal" href="#action">action</a>. Generally this means a single command-line argument

883

will be consumed and a single item (not a list) will be produced.

884

</div>

885

886

<h3>15.4.3.4. const<a class="headerlink" href="#const" title="Permalink to this headline">¶</a></h3>

887

The <tt class="docutils literal">const</tt> argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> is used to hold

888

constant values that are not read from the command line but are required for

889

the various <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> actions. The two most common uses of it are:

890

891

<li>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> is called with

892

<tt class="docutils literal">action='store_const'</tt> or <tt class="docutils literal">action='append_const'</tt>. These actions add the

893

<tt class="docutils literal">const</tt> value to one of the attributes of the object returned by

894

895

896

(like <tt class="docutils literal">-f</tt> or <tt class="docutils literal">--foo</tt>) and <tt class="docutils literal">nargs='?'</tt>. This creates an optional

897

argument that can be followed by zero or one command-line arguments.

898

When parsing the command line, if the option string is encountered with no

899

command-line argument following it, the value of <tt class="docutils literal">const</tt> will be assumed instead.

900

See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</li>

901

</ul>

902

The <tt class="docutils literal">const</tt> keyword argument defaults to <tt class="docutils literal">None</tt>.

903

</div>

904

905

<h3>15.4.3.5. default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h3>

906

All optional arguments and some positional arguments may be omitted at the

907

command line. The <tt class="docutils literal">default</tt> keyword argument of

908

<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a>, whose value defaults to <tt class="docutils literal">None</tt>,

909

specifies what value should be used if the command-line argument is not present.

910

For optional arguments, the <tt class="docutils literal">default</tt> value is used when the option string

911

was not present at the command line:

912

913

914

>>> parser.parse_args('--foo 2'.split())

915

Namespace(foo='2')

916

917

Namespace(foo=42)

918

</pre></div>

919

</div>

920

If the <tt class="docutils literal">default</tt> value is a string, the parser parses the value as if it

921

were a command-line argument. In particular, the parser applies any <a class="reference internal" href="#type">type</a>

922

conversion argument, if provided, before setting the attribute on the

923

<a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><tt class="xref py py-class docutils literal">Namespace</tt></a> return value. Otherwise, the parser uses the value as is:

924

925

926

927

>>> parser.parse_args()

928

Namespace(length=10, width=10.5)

929

</pre></div>

930

</div>

931

For positional arguments with <a class="reference internal" href="#nargs">nargs</a> equal to <tt class="docutils literal">?</tt> or <tt class="docutils literal">*</tt>, the <tt class="docutils literal">default</tt> value

932

is used when no command-line argument was present:

933

934

935

>>> parser.parse_args('a'.split())

936

Namespace(foo='a')

937

938

Namespace(foo=42)

939

</pre></div>

940

</div>

941

Providing <tt class="docutils literal">default=argparse.SUPPRESS</tt> causes no attribute to be added if the

942

command-line argument was not present.:

943

944

945

>>> parser.parse_args([])

946

Namespace()

947

948

Namespace(foo='1')

949

</pre></div>

950

</div>

951

</div>

952

953

954

955

strings. However, quite often the command-line string should instead be

956

interpreted as another type, like a <a class="reference internal" href="functions.html#float" title="float"><tt class="xref py py-class docutils literal">float</tt></a> or <a class="reference internal" href="functions.html#int" title="int"><tt class="xref py py-class docutils literal">int</tt></a>. The

957

<tt class="docutils literal">type</tt> keyword argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> allows any

958

necessary type-checking and type conversions to be performed. Common built-in

959

types and functions can be used directly as the value of the <tt class="docutils literal">type</tt> argument:

960

961

962

963

>>> parser.parse_args('2 temp.txt'.split())

964

Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)

965

</pre></div>

966

</div>

967

See the section on the <a class="reference internal" href="#default">default</a> keyword argument for information on when the

968

<tt class="docutils literal">type</tt> argument is applied to default arguments.

969

To ease the use of various types of files, the argparse module provides the

970

factory FileType which takes the <tt class="docutils literal">mode=</tt> and <tt class="docutils literal">bufsize=</tt> arguments of the

971

<tt class="docutils literal">file</tt> object. For example, <tt class="docutils literal">FileType('w')</tt> can be used to create a

972

writable file:

973

974

975

>>> parser.parse_args(['out.txt'])

976

Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)

977

</pre></div>

978

</div>

979

<tt class="docutils literal">type=</tt> can take any callable that takes a single string argument and returns

980

the converted value:

981

<div class="highlight-python"><div class="highlight"><pre>>>> def perfect_square(string):

982

... value = int(string)

983

... sqrt = math.sqrt(value)

984

... if sqrt != int(sqrt):

985

... msg = "%r is not a perfect square" % string

986

... raise argparse.ArgumentTypeError(msg)

987

... return value

988

...

989

>>> parser = argparse.ArgumentParser(prog='PROG')

990

991

>>> parser.parse_args('9'.split())

992

Namespace(foo=9)

993

>>> parser.parse_args('7'.split())

994

usage: PROG [-h] foo

995

PROG: error: argument foo: '7' is not a perfect square

996

</pre></div>

997

</div>

998

The <a class="reference internal" href="#choices">choices</a> keyword argument may be more convenient for type checkers that

999

simply check against a range of values:

1000

1001

>>> parser.add_argument('foo', type=int, choices=xrange(5, 10))

1002

1003

Namespace(foo=7)

1004

>>> parser.parse_args('11'.split())

1005

usage: PROG [-h] {5,6,7,8,9}

1006

PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

1007

</pre></div>

1008

</div>

1009

See the <a class="reference internal" href="#choices">choices</a> section for more details.

1010

</div>

1011

1012

<h3>15.4.3.7. choices<a class="headerlink" href="#choices" title="Permalink to this headline">¶</a></h3>

1013

Some command-line arguments should be selected from a restricted set of values.

1014

These can be handled by passing a container object as the choices keyword

1015

argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a>. When the command line is

1016

parsed, argument values will be checked, and an error message will be displayed

1017

if the argument was not one of the acceptable values:

1018

1019

1020

>>> parser.parse_args(['rock'])

1021

Namespace(move='rock')

1022

>>> parser.parse_args(['fire'])

1023

usage: game.py [-h] {rock,paper,scissors}

1024

game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',

1025

'paper', 'scissors')

1026

</pre></div>

1027

</div>

1028

Note that inclusion in the choices container is checked after any <a class="reference internal" href="#type">type</a>

1029

conversions have been performed, so the type of the objects in the choices

1030

container should match the <a class="reference internal" href="#type">type</a> specified:

1031

1032

>>> parser.add_argument('door', type=int, choices=range(1, 4))

1033

>>> print(parser.parse_args(['3']))

1034

Namespace(door=3)

1035

>>> parser.parse_args(['4'])

1036

usage: doors.py [-h] {1,2,3}

1037

doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

1038

</pre></div>

1039

</div>

1040

Any object that supports the <tt class="docutils literal">in</tt> operator can be passed as the choices

1041

value, so <a class="reference internal" href="stdtypes.html#dict" title="dict"><tt class="xref py py-class docutils literal">dict</tt></a> objects, <a class="reference internal" href="stdtypes.html#set" title="set"><tt class="xref py py-class docutils literal">set</tt></a> objects, custom containers,

1042

etc. are all supported.

1043

</div>

1044

1045

<h3>15.4.3.8. required<a class="headerlink" href="#required" title="Permalink to this headline">¶</a></h3>

1046

In general, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> module assumes that flags like <tt class="docutils literal">-f</tt> and <tt class="docutils literal">--bar</tt>

1047

indicate optional arguments, which can always be omitted at the command line.

1048

To make an option required, <tt class="docutils literal">True</tt> can be specified for the <tt class="docutils literal">required=</tt>

1049

keyword argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a>:

1050

1051

1052

>>> parser.parse_args(['--foo', 'BAR'])

1053

Namespace(foo='BAR')

1054

>>> parser.parse_args([])

1055

usage: argparse.py [-h] [--foo FOO]

1056

argparse.py: error: option --foo is required

1057

</pre></div>

1058

</div>

1059

As the example shows, if an option is marked as <tt class="docutils literal">required</tt>,

1060

1061

present at the command line.

1062

1063

Note

1064

Required options are generally considered bad form because users expect

1065

options to be optional, and thus they should be avoided when possible.

1066

</div>

1067

</div>

1068

1069

1070

The <tt class="docutils literal">help</tt> value is a string containing a brief description of the argument.

1071

When a user requests help (usually by using <tt class="docutils literal">-h</tt> or <tt class="docutils literal">--help</tt> at the

1072

command line), these <tt class="docutils literal">help</tt> descriptions will be displayed with each

1073

argument:

1074

1075

1076

... help='foo the bars before frobbling')

1077

1078

... help='one of the bars to be frobbled')

1079

>>> parser.parse_args('-h'.split())

1080

usage: frobble [-h] [--foo] bar [bar ...]

1081

1082

positional arguments:

1083

bar one of the bars to be frobbled

1084

1085

optional arguments:

1086

-h, --help show this help message and exit

1087

--foo foo the bars before frobbling

1088

</pre></div>

1089

</div>

1090

The <tt class="docutils literal">help</tt> strings can include various format specifiers to avoid repetition

1091

of things like the program name or the argument <a class="reference internal" href="#default">default</a>. The available

1092

specifiers include the program name, <tt class="docutils literal">%(prog)s</tt> and most keyword arguments to

1093

<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a>, e.g. <tt class="docutils literal">%(default)s</tt>, <tt class="docutils literal">%(type)s</tt>, etc.:

1094

1095

>>> parser.add_argument('bar', nargs='?', type=int, default=42,

1096

... help='the bar to %(prog)s (default: %(default)s)')

1097

>>> parser.print_help()

1098

usage: frobble [-h] [bar]

1099

1100

positional arguments:

1101

bar the bar to frobble (default: 42)

1102

1103

optional arguments:

1104

-h, --help show this help message and exit

1105

</pre></div>

1106

</div>

1107

<a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> supports silencing the help entry for certain options, by

1108

setting the <tt class="docutils literal">help</tt> value to <tt class="docutils literal">argparse.SUPPRESS</tt>:

1109

1110

1111

>>> parser.print_help()

1112

usage: frobble [-h]

1113

1114

optional arguments:

1115

-h, --help show this help message and exit

1116

</pre></div>

1117

</div>

1118

</div>

1119

1120

<h3>15.4.3.10. metavar<a class="headerlink" href="#metavar" title="Permalink to this headline">¶</a></h3>

1121

When <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> generates help messages, it needs some way to refer

1122

to each expected argument. By default, ArgumentParser objects use the <a class="reference internal" href="#dest">dest</a>

1123

value as the “name” of each object. By default, for positional argument

1124

actions, the <a class="reference internal" href="#dest">dest</a> value is used directly, and for optional argument actions,

1125

the <a class="reference internal" href="#dest">dest</a> value is uppercased. So, a single positional argument with

1126

<tt class="docutils literal">dest='bar'</tt> will be referred to as <tt class="docutils literal">bar</tt>. A single

1127

optional argument <tt class="docutils literal">--foo</tt> that should be followed by a single command-line argument

1128

will be referred to as <tt class="docutils literal">FOO</tt>. An example:

1129

1130

>>> parser.add_argument('--foo')

1131

>>> parser.add_argument('bar')

1132

>>> parser.parse_args('X --foo Y'.split())

1133

Namespace(bar='X', foo='Y')

1134

>>> parser.print_help()

1135

usage: [-h] [--foo FOO] bar

1136

1137

positional arguments:

1138

bar

1139

1140

optional arguments:

1141

-h, --help show this help message and exit

1142

--foo FOO

1143

</pre></div>

1144

</div>

1145

An alternative name can be specified with <tt class="docutils literal">metavar</tt>:

1146

1147

1148

1149

1150

Namespace(bar='X', foo='Y')

1151

>>> parser.print_help()

1152

usage: [-h] [--foo YYY] XXX

1153

1154

positional arguments:

1155

XXX

1156

1157

optional arguments:

1158

-h, --help show this help message and exit

1159

--foo YYY

1160

</pre></div>

1161

</div>

1162

Note that <tt class="docutils literal">metavar</tt> only changes the displayed name - the name of the

1163

attribute on the <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> object is still determined

1164

by the <a class="reference internal" href="#dest">dest</a> value.

1165

Different values of <tt class="docutils literal">nargs</tt> may cause the metavar to be used multiple times.

1166

Providing a tuple to <tt class="docutils literal">metavar</tt> specifies a different display for each of the

1167

arguments:

1168

1169

1170

>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))

1171

>>> parser.print_help()

1172

usage: PROG [-h] [-x X X] [--foo bar baz]

1173

1174

optional arguments:

1175

-h, --help show this help message and exit

1176

-x X X

1177

--foo bar baz

1178

</pre></div>

1179

</div>

1180

</div>

1181

1182

1183

Most <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> actions add some value as an attribute of the

1184

object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a>. The name of this

1185

attribute is determined by the <tt class="docutils literal">dest</tt> keyword argument of

1186

1187

<tt class="docutils literal">dest</tt> is normally supplied as the first argument to

1188

1189

1190

>>> parser.add_argument('bar')

1191

>>> parser.parse_args('XXX'.split())

1192

Namespace(bar='XXX')

1193

</pre></div>

1194

</div>

1195

For optional argument actions, the value of <tt class="docutils literal">dest</tt> is normally inferred from

1196

the option strings. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> generates the value of <tt class="docutils literal">dest</tt> by

1197

taking the first long option string and stripping away the initial <tt class="docutils literal">--</tt>

1198

string. If no long option strings were supplied, <tt class="docutils literal">dest</tt> will be derived from

1199

the first short option string by stripping the initial <tt class="docutils literal">-</tt> character. Any

1200

internal <tt class="docutils literal">-</tt> characters will be converted to <tt class="docutils literal">_</tt> characters to make sure

1201

the string is a valid attribute name. The examples below illustrate this

1202

behavior:

1203

1204

1205

1206

>>> parser.parse_args('-f 1 -x 2'.split())

1207

Namespace(foo_bar='1', x='2')

1208

>>> parser.parse_args('--foo 1 -y 2'.split())

1209

Namespace(foo_bar='1', x='2')

1210

</pre></div>

1211

</div>

1212

<tt class="docutils literal">dest</tt> allows a custom attribute name to be provided:

1213

1214

1215

>>> parser.parse_args('--foo XXX'.split())

1216

Namespace(bar='XXX')

1217

</pre></div>

1218

</div>

1219

</div>

1220

1221

<h3>15.4.3.12. Action classes<a class="headerlink" href="#action-classes" title="Permalink to this headline">¶</a></h3>

1222

Action classes implement the Action API, a callable which returns a callable

1223

which processes arguments from the command-line. Any object which follows this

1224

API may be passed as the <tt class="docutils literal">action</tt> parameter to <tt class="xref py py-meth docutils literal">add_argument()</tt>.

1225

1226

1227

class <tt class="descclassname">argparse.</tt><tt class="descname">Action</tt><big>(</big>option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None<big>)</big><a class="headerlink" href="#argparse.Action" title="Permalink to this definition">¶</a></dt>

1228

1229

1230

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

1231

to parse a single argument from one or more strings from the command line. The

1232

Action class must accept the two positional arguments plus any keyword arguments

1233

passed to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">ArgumentParser.add_argument()</tt></a> except for the <tt class="docutils literal">action</tt> itself.

1234

Instances of Action (or return value of any callable to the <tt class="docutils literal">action</tt>

1235

parameter) should have attributes “dest”, “option_strings”, “default”, “type”,

1236

“required”, “help”, etc. defined. The easiest way to ensure these attributes

1237

are defined is to call <tt class="docutils literal">Action.__init__</tt>.

1238

Action instances should be callable, so subclasses must override the

1239

<tt class="docutils literal">__call__</tt> method, which should accept four parameters:

1240

1241

<li><tt class="docutils literal">parser</tt> - The ArgumentParser object which contains this action.</li>

1242

<li><tt class="docutils literal">namespace</tt> - The <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><tt class="xref py py-class docutils literal">Namespace</tt></a> object that will be returned by

1243

1244

object using <a class="reference internal" href="functions.html#setattr" title="setattr"><tt class="xref py py-func docutils literal">setattr()</tt></a>.</li>

1245

<li><tt class="docutils literal">values</tt> - The associated command-line arguments, with any type conversions

1246

applied. Type conversions are specified with the <a class="reference internal" href="#type">type</a> keyword argument to

1247

1248

<li><tt class="docutils literal">option_string</tt> - The option string that was used to invoke this action.

1249

The <tt class="docutils literal">option_string</tt> argument is optional, and will be absent if the action

1250

is associated with a positional argument.</li>

1251

</ul>

1252

The <tt class="docutils literal">__call__</tt> method may perform arbitrary actions, but will typically set

1253

attributes on the <tt class="docutils literal">namespace</tt> based on <tt class="docutils literal">dest</tt> and <tt class="docutils literal">values</tt>.

1254

</div>

1255

</div>

1256

1257

<h2>15.4.4. The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Permalink to this headline">¶</a></h2>

1258

1259

1260

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">parse_args</tt><big>(</big>args=None, namespace=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.parse_args" title="Permalink to this definition">¶</a></dt>

1261

<dd>Convert argument strings to objects and assign them as attributes of the

1262

namespace. Return the populated namespace.

1263

Previous calls to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> determine exactly what objects are

1264

created and how they are assigned. See the documentation for

1265

1266

By default, the argument strings are taken from <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><tt class="xref py py-data docutils literal">sys.argv</tt></a>, and a new empty

1267

1268

</dd></dl>

1269

1270

1271

<h3>15.4.4.1. Option value syntax<a class="headerlink" href="#option-value-syntax" title="Permalink to this headline">¶</a></h3>

1272

The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> method supports several ways of

1273

specifying the value of an option (if it takes one). In the simplest case, the

1274

option and its value are passed as two separate arguments:

1275

1276

>>> parser.add_argument('-x')

1277

>>> parser.add_argument('--foo')

1278

>>> parser.parse_args('-x X'.split())

1279

Namespace(foo=None, x='X')

1280

>>> parser.parse_args('--foo FOO'.split())

1281

Namespace(foo='FOO', x=None)

1282

</pre></div>

1283

</div>

1284

For long options (options with names longer than a single character), the option

1285

and value can also be passed as a single command-line argument, using <tt class="docutils literal">=</tt> to

1286

separate them:

1287

<div class="highlight-python"><div class="highlight"><pre>>>> parser.parse_args('--foo=FOO'.split())

1288

Namespace(foo='FOO', x=None)

1289

</pre></div>

1290

</div>

1291

For short options (options only one character long), the option and its value

1292

can be concatenated:

1293

<div class="highlight-python"><div class="highlight"><pre>>>> parser.parse_args('-xX'.split())

1294

Namespace(foo=None, x='X')

1295

</pre></div>

1296

</div>

1297

Several short options can be joined together, using only a single <tt class="docutils literal">-</tt> prefix,

1298

as long as only the last option (or none of them) requires a value:

1299

1300

1301

1302

>>> parser.add_argument('-z')

1303

>>> parser.parse_args('-xyzZ'.split())

1304

Namespace(x=True, y=True, z='Z')

1305

</pre></div>

1306

</div>

1307

</div>

1308

1309

<h3>15.4.4.2. Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Permalink to this headline">¶</a></h3>

1310

While parsing the command line, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> checks for a

1311

variety of errors, including ambiguous options, invalid types, invalid options,

1312

wrong number of positional arguments, etc. When it encounters such an error,

1313

it exits and prints the error along with a usage message:

1314

1315

1316

1317

1318

>>> # invalid type

1319

>>> parser.parse_args(['--foo', 'spam'])

1320

usage: PROG [-h] [--foo FOO] [bar]

1321

PROG: error: argument --foo: invalid int value: 'spam'

1322

1323

>>> # invalid option

1324

>>> parser.parse_args(['--bar'])

1325

usage: PROG [-h] [--foo FOO] [bar]

1326

PROG: error: no such option: --bar

1327

1328

>>> # wrong number of arguments

1329

>>> parser.parse_args(['spam', 'badger'])

1330

usage: PROG [-h] [--foo FOO] [bar]

1331

PROG: error: extra arguments found: badger

1332

</pre></div>

1333

</div>

1334

</div>

1335

1336

<h3>15.4.4.3. Arguments containing <tt class="docutils literal">-</tt><a class="headerlink" href="#arguments-containing" title="Permalink to this headline">¶</a></h3>

1337

1338

the user has clearly made a mistake, but some situations are inherently

1339

ambiguous. For example, the command-line argument <tt class="docutils literal">-1</tt> could either be an

1340

attempt to specify an option or an attempt to provide a positional argument.

1341

The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> method is cautious here: positional

1342

arguments may only begin with <tt class="docutils literal">-</tt> if they look like negative numbers and

1343

there are no options in the parser that look like negative numbers:

1344

1345

>>> parser.add_argument('-x')

1346

1347

1348

>>> # no negative number options, so -1 is a positional argument

1349

1350

Namespace(foo=None, x='-1')

1351

1352

>>> # no negative number options, so -1 and -5 are positional arguments

1353

>>> parser.parse_args(['-x', '-1', '-5'])

1354

Namespace(foo='-5', x='-1')

1355

1356

>>> parser = argparse.ArgumentParser(prog='PROG')

1357

1358

1359

1360

>>> # negative number options present, so -1 is an option

1361

1362

Namespace(foo=None, one='X')

1363

1364

>>> # negative number options present, so -2 is an option

1365

>>> parser.parse_args(['-2'])

1366

usage: PROG [-h] [-1 ONE] [foo]

1367

PROG: error: no such option: -2

1368

1369

>>> # negative number options present, so both -1s are options

1370

1371

usage: PROG [-h] [-1 ONE] [foo]

1372

PROG: error: argument -1: expected one argument

1373

</pre></div>

1374

</div>

1375

If you have positional arguments that must begin with <tt class="docutils literal">-</tt> and don’t look

1376

like negative numbers, you can insert the pseudo-argument <tt class="docutils literal">'--'</tt> which tells

1377

1378

argument:

1379

<div class="highlight-python"><div class="highlight"><pre>>>> parser.parse_args(['--', '-f'])

1380

Namespace(foo='-f', one=None)

1381

</pre></div>

1382

</div>

1383

</div>

1384

1385

<h3>15.4.4.4. Argument abbreviations (prefix matching)<a class="headerlink" href="#argument-abbreviations-prefix-matching" title="Permalink to this headline">¶</a></h3>

1386

1387

abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches

1388

a unique option):

1389

1390

>>> parser.add_argument('-bacon')

1391

>>> parser.add_argument('-badger')

1392

>>> parser.parse_args('-bac MMM'.split())

1393

Namespace(bacon='MMM', badger=None)

1394

>>> parser.parse_args('-bad WOOD'.split())

1395

Namespace(bacon=None, badger='WOOD')

1396

>>> parser.parse_args('-ba BA'.split())

1397

usage: PROG [-h] [-bacon BACON] [-badger BADGER]

1398

PROG: error: ambiguous option: -ba could match -badger, -bacon

1399

</pre></div>

1400

</div>

1401

An error is produced for arguments that could produce more than one options.

1402

</div>

1403

1404

<h3>15.4.4.5. Beyond <tt class="docutils literal">sys.argv</tt><a class="headerlink" href="#beyond-sys-argv" title="Permalink to this headline">¶</a></h3>

1405

Sometimes it may be useful to have an ArgumentParser parse arguments other than those

1406

of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><tt class="xref py py-data docutils literal">sys.argv</tt></a>. This can be accomplished by passing a list of strings to

1407

1408

interactive prompt:

1409

1410

>>> parser.add_argument(

1411

... 'integers', metavar='int', type=int, choices=xrange(10),

1412

... nargs='+', help='an integer in the range 0..9')

1413

>>> parser.add_argument(

1414

... '--sum', dest='accumulate', action='store_const', const=sum,

1415

... default=max, help='sum the integers (default: find the max)')

1416

>>> parser.parse_args(['1', '2', '3', '4'])

1417

Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])

1418

>>> parser.parse_args('1 2 3 4 --sum'.split())

1419

Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])

1420

</pre></div>

1421

</div>

1422

</div>

1423

1424

<h3>15.4.4.6. The Namespace object<a class="headerlink" href="#the-namespace-object" title="Permalink to this headline">¶</a></h3>

1425

1426

1427

class <tt class="descclassname">argparse.</tt><tt class="descname">Namespace</tt><a class="headerlink" href="#argparse.Namespace" title="Permalink to this definition">¶</a></dt>

1428

<dd>Simple class used by default by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> to create

1429

an object holding attributes and return it.

1430

</dd></dl>

1431

1432

This class is deliberately simple, just an <a class="reference internal" href="functions.html#object" title="object"><tt class="xref py py-class docutils literal">object</tt></a> subclass with a

1433

readable string representation. If you prefer to have dict-like view of the

1434

attributes, you can use the standard Python idiom, <a class="reference internal" href="functions.html#vars" title="vars"><tt class="xref py py-func docutils literal">vars()</tt></a>:

1435

1436

>>> parser.add_argument('--foo')

1437

>>> args = parser.parse_args(['--foo', 'BAR'])

1438

>>> vars(args)

1439

{'foo': 'BAR'}

1440

</pre></div>

1441

</div>

1442

It may also be useful to have an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> assign attributes to an

1443

already existing object, rather than a new <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><tt class="xref py py-class docutils literal">Namespace</tt></a> object. This can

1444

be achieved by specifying the <tt class="docutils literal">namespace=</tt> keyword argument:

1445

<div class="highlight-python"><div class="highlight"><pre>>>> class C(object):

1446

... pass

1447

...

1448

>>> c = C()

1449

1450

>>> parser.add_argument('--foo')

1451

>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)

1452

>>> c.foo

1453

'BAR'

1454

</pre></div>

1455

</div>

1456

</div>

1457

</div>

1458

1459

<h2>15.4.5. Other utilities<a class="headerlink" href="#other-utilities" title="Permalink to this headline">¶</a></h2>

1460

1461

<h3>15.4.5.1. Sub-commands<a class="headerlink" href="#sub-commands" title="Permalink to this headline">¶</a></h3>

1462

1463

1464

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">add_subparsers</tt><big>(</big>[title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar]<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.add_subparsers" title="Permalink to this definition">¶</a></dt>

1465

<dd>Many programs split up their functionality into a number of sub-commands,

1466

for example, the <tt class="docutils literal">svn</tt> program can invoke sub-commands like <tt class="docutils literal">svn

1467

checkout</tt>, <tt class="docutils literal">svn update</tt>, and <tt class="docutils literal">svn commit</tt>. Splitting up functionality

1468

this way can be a particularly good idea when a program performs several

1469

different functions which require different kinds of command-line arguments.

1470

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> supports the creation of such sub-commands with the

1471

<a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> method. The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> method is normally

1472

called with no arguments and returns a special action object. This object

1473

has a single method, <tt class="xref py py-meth docutils literal">add_parser()</tt>, which takes a

1474

command name and any <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> constructor arguments, and

1475

returns an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> object that can be modified as usual.

1476

Description of parameters:

1477

1478

<li>title - title for the sub-parser group in help output; by default

1479

“subcommands” if description is provided, otherwise uses title for

1480

positional arguments</li>

1481

<li>description - description for the sub-parser group in help output, by

1482

default None</li>

1483

<li>prog - usage information that will be displayed with sub-command help,

1484

by default the name of the program and any positional arguments before the

1485

subparser argument</li>

1486

<li>parser_class - class which will be used to create sub-parser instances, by

1487

default the class of the current parser (e.g. ArgumentParser)</li>

1488

<li><a class="reference internal" href="#action">action</a> - the basic type of action to be taken when this argument is

1489

encountered at the command line</li>

1490

<li><a class="reference internal" href="#dest">dest</a> - name of the attribute under which sub-command name will be

1491

stored; by default None and no value is stored</li>

1492

<li><a class="reference internal" href="#help">help</a> - help for sub-parser group in help output, by default None</li>

1493

<li><a class="reference internal" href="#metavar">metavar</a> - string presenting available sub-commands in help; by default it

1494

is None and presents sub-commands in form {cmd1, cmd2, ..}</li>

1495

</ul>

1496

Some example usage:

1497

<div class="highlight-python"><div class="highlight"><pre>>>> # create the top-level parser

1498

>>> parser = argparse.ArgumentParser(prog='PROG')

1499

1500

>>> subparsers = parser.add_subparsers(help='sub-command help')

1501

>>>

1502

>>> # create the parser for the "a" command

1503

>>> parser_a = subparsers.add_parser('a', help='a help')

1504

>>> parser_a.add_argument('bar', type=int, help='bar help')

1505

>>>

1506

>>> # create the parser for the "b" command

1507

>>> parser_b = subparsers.add_parser('b', help='b help')

1508

>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')

1509

>>>

1510

>>> # parse some argument lists

1511

>>> parser.parse_args(['a', '12'])

1512

Namespace(bar=12, foo=False)

1513

>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])

1514

Namespace(baz='Z', foo=True)

1515

</pre></div>

1516

</div>

1517

Note that the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> will only contain

1518

attributes for the main parser and the subparser that was selected by the

1519

command line (and not any other subparsers). So in the example above, when

1520

the <tt class="docutils literal">a</tt> command is specified, only the <tt class="docutils literal">foo</tt> and <tt class="docutils literal">bar</tt> attributes are

1521

present, and when the <tt class="docutils literal">b</tt> command is specified, only the <tt class="docutils literal">foo</tt> and

1522

<tt class="docutils literal">baz</tt> attributes are present.

1523

Similarly, when a help message is requested from a subparser, only the help

1524

for that particular parser will be printed. The help message will not

1525

include parent parser or sibling parser messages. (A help message for each

1526

subparser command, however, can be given by supplying the <tt class="docutils literal">help=</tt> argument

1527

to <tt class="xref py py-meth docutils literal">add_parser()</tt> as above.)

1528

1529

usage: PROG [-h] [--foo] {a,b} ...

1530

1531

positional arguments:

1532

{a,b} sub-command help

1533

a a help

1534

b b help

1535

1536

optional arguments:

1537

-h, --help show this help message and exit

1538

--foo foo help

1539

1540

1541

usage: PROG a [-h] bar

1542

1543

positional arguments:

1544

bar bar help

1545

1546

optional arguments:

1547

-h, --help show this help message and exit

1548

1549

>>> parser.parse_args(['b', '--help'])

1550

usage: PROG b [-h] [--baz {X,Y,Z}]

1551

1552

optional arguments:

1553

-h, --help show this help message and exit

1554

--baz {X,Y,Z} baz help

1555

</pre></div>

1556

</div>

1557

The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> method also supports <tt class="docutils literal">title</tt> and <tt class="docutils literal">description</tt>

1558

keyword arguments. When either is present, the subparser’s commands will

1559

appear in their own group in the help output. For example:

1560

1561

>>> subparsers = parser.add_subparsers(title='subcommands',

1562

... description='valid subcommands',

1563

... help='additional help')

1564

>>> subparsers.add_parser('foo')

1565

>>> subparsers.add_parser('bar')

1566

>>> parser.parse_args(['-h'])

1567

usage: [-h] {foo,bar} ...

1568

1569

optional arguments:

1570

-h, --help show this help message and exit

1571

1572

subcommands:

1573

valid subcommands

1574

1575

{foo,bar} additional help

1576

</pre></div>

1577

</div>

1578

One particularly effective way of handling sub-commands is to combine the use

1579

of the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> method with calls to <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><tt class="xref py py-meth docutils literal">set_defaults()</tt></a> so

1580

that each subparser knows which Python function it should execute. For

1581

example:

1582

<div class="highlight-python"><div class="highlight"><pre>>>> # sub-command functions

1583

>>> def foo(args):

1584

... print args.x * args.y

1585

...

1586

>>> def bar(args):

1587

... print '((%s))' % args.z

1588

...

1589

>>> # create the top-level parser

1590

1591

1592

>>>

1593

>>> # create the parser for the "foo" command

1594

>>> parser_foo = subparsers.add_parser('foo')

1595

>>> parser_foo.add_argument('-x', type=int, default=1)

1596

>>> parser_foo.add_argument('y', type=float)

1597

>>> parser_foo.set_defaults(func=foo)

1598

>>>

1599

>>> # create the parser for the "bar" command

1600

>>> parser_bar = subparsers.add_parser('bar')

1601

>>> parser_bar.add_argument('z')

1602

>>> parser_bar.set_defaults(func=bar)

1603

>>>

1604

>>> # parse the args and call whatever function was selected

1605

>>> args = parser.parse_args('foo 1 -x 2'.split())

1606

>>> args.func(args)

1607

2.0

1608

>>>

1609

>>> # parse the args and call whatever function was selected

1610

>>> args = parser.parse_args('bar XYZYX'.split())

1611

>>> args.func(args)

1612

((XYZYX))

1613

</pre></div>

1614

</div>

1615

This way, you can let <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> do the job of calling the

1616

appropriate function after argument parsing is complete. Associating

1617

functions with actions like this is typically the easiest way to handle the

1618

different actions for each of your subparsers. However, if it is necessary

1619

to check the name of the subparser that was invoked, the <tt class="docutils literal">dest</tt> keyword

1620

argument to the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> call will work:

1621

1622

>>> subparsers = parser.add_subparsers(dest='subparser_name')

1623

>>> subparser1 = subparsers.add_parser('1')

1624

>>> subparser1.add_argument('-x')

1625

>>> subparser2 = subparsers.add_parser('2')

1626

>>> subparser2.add_argument('y')

1627

>>> parser.parse_args(['2', 'frobble'])

1628

Namespace(subparser_name='2', y='frobble')

1629

</pre></div>

1630

</div>

1631

</dd></dl>

1632

1633

</div>

1634

1635

<h3>15.4.5.2. FileType objects<a class="headerlink" href="#filetype-objects" title="Permalink to this headline">¶</a></h3>

1636

1637

1638

class <tt class="descclassname">argparse.</tt><tt class="descname">FileType</tt><big>(</big>mode='r', bufsize=None<big>)</big><a class="headerlink" href="#argparse.FileType" title="Permalink to this definition">¶</a></dt>

1639

<dd>The <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><tt class="xref py py-class docutils literal">FileType</tt></a> factory creates objects that can be passed to the type

1640

argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">ArgumentParser.add_argument()</tt></a>. Arguments that have

1641

<a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><tt class="xref py py-class docutils literal">FileType</tt></a> objects as their type will open command-line arguments as files

1642

with the requested modes and buffer sizes:

1643

1644

>>> parser.add_argument('--output', type=argparse.FileType('wb', 0))

1645

>>> parser.parse_args(['--output', 'out'])

1646

Namespace(output=<open file 'out', mode 'wb' at 0x...>)

1647

</pre></div>

1648

</div>

1649

FileType objects understand the pseudo-argument <tt class="docutils literal">'-'</tt> and automatically

1650

convert this into <tt class="docutils literal">sys.stdin</tt> for readable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><tt class="xref py py-class docutils literal">FileType</tt></a> objects and

1651

<tt class="docutils literal">sys.stdout</tt> for writable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><tt class="xref py py-class docutils literal">FileType</tt></a> objects:

1652

1653

1654

>>> parser.parse_args(['-'])

1655

Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)

1656

</pre></div>

1657

</div>

1658

</dd></dl>

1659

1660

</div>

1661

1662

<h3>15.4.5.3. Argument groups<a class="headerlink" href="#argument-groups" title="Permalink to this headline">¶</a></h3>

1663

1664

1665

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">add_argument_group</tt><big>(</big>title=None, description=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.add_argument_group" title="Permalink to this definition">¶</a></dt>

1666

<dd>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> groups command-line arguments into

1667

“positional arguments” and “optional arguments” when displaying help

1668

messages. When there is a better conceptual grouping of arguments than this

1669

default one, appropriate groups can be created using the

1670

<a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><tt class="xref py py-meth docutils literal">add_argument_group()</tt></a> method:

1671

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)

1672

>>> group = parser.add_argument_group('group')

1673

>>> group.add_argument('--foo', help='foo help')

1674

>>> group.add_argument('bar', help='bar help')

1675

>>> parser.print_help()

1676

usage: PROG [--foo FOO] bar

1677

1678

group:

1679

bar bar help

1680

--foo FOO foo help

1681

</pre></div>

1682

</div>

1683

The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><tt class="xref py py-meth docutils literal">add_argument_group()</tt></a> method returns an argument group object which

1684

has an <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">add_argument()</tt></a> method just like a regular

1685

<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>. When an argument is added to the group, the parser

1686

treats it just like a normal argument, but displays the argument in a

1687

separate group for help messages. The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><tt class="xref py py-meth docutils literal">add_argument_group()</tt></a> method

1688

accepts title and description arguments which can be used to

1689

customize this display:

1690

<div class="highlight-python"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)

1691

>>> group1 = parser.add_argument_group('group1', 'group1 description')

1692

>>> group1.add_argument('foo', help='foo help')

1693

>>> group2 = parser.add_argument_group('group2', 'group2 description')

1694

>>> group2.add_argument('--bar', help='bar help')

1695

>>> parser.print_help()

1696

usage: PROG [--bar BAR] foo

1697

1698

group1:

1699

group1 description

1700

1701

foo foo help

1702

1703

group2:

1704

group2 description

1705

1706

--bar BAR bar help

1707

</pre></div>

1708

</div>

1709

Note that any arguments not in your user-defined groups will end up back

1710

in the usual “positional arguments” and “optional arguments” sections.

1711

</dd></dl>

1712

1713

</div>

1714

1715

<h3>15.4.5.4. Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Permalink to this headline">¶</a></h3>

1716

1717

1718

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">add_mutually_exclusive_group</tt><big>(</big>required=False<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="Permalink to this definition">¶</a></dt>

1719

<dd>Create a mutually exclusive group. <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> will make sure that only

1720

one of the arguments in the mutually exclusive group was present on the

1721

command line:

1722

1723

1724

>>> group.add_argument('--foo', action='store_true')

1725

>>> group.add_argument('--bar', action='store_false')

1726

>>> parser.parse_args(['--foo'])

1727

Namespace(bar=True, foo=True)

1728

>>> parser.parse_args(['--bar'])

1729

Namespace(bar=False, foo=False)

1730

>>> parser.parse_args(['--foo', '--bar'])

1731

usage: PROG [-h] [--foo | --bar]

1732

PROG: error: argument --bar: not allowed with argument --foo

1733

</pre></div>

1734

</div>

1735

The <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><tt class="xref py py-meth docutils literal">add_mutually_exclusive_group()</tt></a> method also accepts a required

1736

argument, to indicate that at least one of the mutually exclusive arguments

1737

is required:

1738

1739

>>> group = parser.add_mutually_exclusive_group(required=True)

1740

>>> group.add_argument('--foo', action='store_true')

1741

>>> group.add_argument('--bar', action='store_false')

1742

>>> parser.parse_args([])

1743

usage: PROG [-h] (--foo | --bar)

1744

PROG: error: one of the arguments --foo --bar is required

1745

</pre></div>

1746

</div>

1747

Note that currently mutually exclusive argument groups do not support the

1748

title and description arguments of

1749

1750

</dd></dl>

1751

1752

</div>

1753

1754

<h3>15.4.5.5. Parser defaults<a class="headerlink" href="#parser-defaults" title="Permalink to this headline">¶</a></h3>

1755

1756

1757

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">set_defaults</tt><big>(</big>**kwargs<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.set_defaults" title="Permalink to this definition">¶</a></dt>

1758

<dd>Most of the time, the attributes of the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a>

1759

will be fully determined by inspecting the command-line arguments and the argument

1760

actions. <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><tt class="xref py py-meth docutils literal">set_defaults()</tt></a> allows some additional

1761

attributes that are determined without any inspection of the command line to

1762

be added:

1763

1764

1765

>>> parser.set_defaults(bar=42, baz='badger')

1766

>>> parser.parse_args(['736'])

1767

Namespace(bar=42, baz='badger', foo=736)

1768

</pre></div>

1769

</div>

1770

Note that parser-level defaults always override argument-level defaults:

1771

1772

1773

>>> parser.set_defaults(foo='spam')

1774

>>> parser.parse_args([])

1775

Namespace(foo='spam')

1776

</pre></div>

1777

</div>

1778

Parser-level defaults can be particularly useful when working with multiple

1779

parsers. See the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><tt class="xref py py-meth docutils literal">add_subparsers()</tt></a> method for an

1780

example of this type.

1781

</dd></dl>

1782

1783

1784

1785

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">get_default</tt><big>(</big>dest<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.get_default" title="Permalink to this definition">¶</a></dt>

1786

<dd>Get the default value for a namespace attribute, as set by either

1787

1788

1789

1790

1791

>>> parser.get_default('foo')

1792

'badger'

1793

</pre></div>

1794

</div>

1795

</dd></dl>

1796

1797

</div>

1798

1799

<h3>15.4.5.6. Printing help<a class="headerlink" href="#printing-help" title="Permalink to this headline">¶</a></h3>

1800

In most typical applications, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><tt class="xref py py-meth docutils literal">parse_args()</tt></a> will take

1801

care of formatting and printing any usage or error messages. However, several

1802

formatting methods are available:

1803

1804

1805

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">print_usage</tt><big>(</big>file=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.print_usage" title="Permalink to this definition">¶</a></dt>

1806

<dd>Print a brief description of how the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> should be

1807

invoked on the command line. If file is <tt class="docutils literal">None</tt>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><tt class="xref py py-data docutils literal">sys.stdout</tt></a> is

1808

assumed.

1809

</dd></dl>

1810

1811

1812

1813

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">print_help</tt><big>(</big>file=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.print_help" title="Permalink to this definition">¶</a></dt>

1814

<dd>Print a help message, including the program usage and information about the

1815

arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>. If file is

1816

<tt class="docutils literal">None</tt>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><tt class="xref py py-data docutils literal">sys.stdout</tt></a> is assumed.

1817

</dd></dl>

1818

1819

There are also variants of these methods that simply return a string instead of

1820

printing it:

1821

1822

1823

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">format_usage</tt><big>(</big><big>)</big><a class="headerlink" href="#argparse.ArgumentParser.format_usage" title="Permalink to this definition">¶</a></dt>

1824

<dd>Return a string containing a brief description of how the

1825

1826

</dd></dl>

1827

1828

1829

1830

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">format_help</tt><big>(</big><big>)</big><a class="headerlink" href="#argparse.ArgumentParser.format_help" title="Permalink to this definition">¶</a></dt>

1831

<dd>Return a string containing a help message, including the program usage and

1832

information about the arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a>.

1833

</dd></dl>

1834

1835

</div>

1836

1837

<h3>15.4.5.7. Partial parsing<a class="headerlink" href="#partial-parsing" title="Permalink to this headline">¶</a></h3>

1838

1839

1840

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">parse_known_args</tt><big>(</big>args=None, namespace=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.parse_known_args" title="Permalink to this definition">¶</a></dt>

1841

1842

1843

Sometimes a script may only parse a few of the command-line arguments, passing

1844

the remaining arguments on to another script or program. In these cases, the

1845

<a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><tt class="xref py py-meth docutils literal">parse_known_args()</tt></a> method can be useful. It works much like

1846

1847

extra arguments are present. Instead, it returns a two item tuple containing

1848

the populated namespace and the list of remaining argument strings.

1849

1850

1851

>>> parser.add_argument('bar')

1852

>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])

1853

(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

1854

</pre></div>

1855

</div>

1856

1857

Warning

1858

<a class="reference internal" href="#prefix-matching">Prefix matching</a> rules apply to

1859

<tt class="xref py py-meth docutils literal">parse_known_args()</tt>. The parser may consume an option even if it’s just

1860

a prefix of one of its known options, instead of leaving it in the remaining

1861

arguments list.

1862

</div>

1863

</div>

1864

1865

<h3>15.4.5.8. Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Permalink to this headline">¶</a></h3>

1866

1867

1868

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">convert_arg_line_to_args</tt><big>(</big>arg_line<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="Permalink to this definition">¶</a></dt>

1869

<dd>Arguments that are read from a file (see the fromfile_prefix_chars

1870

keyword argument to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><tt class="xref py py-class docutils literal">ArgumentParser</tt></a> constructor) are read one

1871

argument per line. <a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><tt class="xref py py-meth docutils literal">convert_arg_line_to_args()</tt></a> can be overriden for

1872

fancier reading.

1873

This method takes a single argument arg_line which is a string read from

1874

the argument file. It returns a list of arguments parsed from this string.

1875

The method is called once per line read from the argument file, in order.

1876

A useful override of this method is one that treats each space-separated word

1877

as an argument:

1878

<div class="highlight-python"><div class="highlight"><pre>def convert_arg_line_to_args(self, arg_line):

1879

return arg_line.split()

1880

</pre></div>

1881

</div>

1882

</dd></dl>

1883

1884

</div>

1885

1886

<h3>15.4.5.9. Exiting methods<a class="headerlink" href="#exiting-methods" title="Permalink to this headline">¶</a></h3>

1887

1888

1889

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">exit</tt><big>(</big>status=0, message=None<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.exit" title="Permalink to this definition">¶</a></dt>

1890

<dd>This method terminates the program, exiting with the specified status

1891

and, if given, it prints a message before that.

1892

</dd></dl>

1893

1894

1895

1896

<tt class="descclassname">ArgumentParser.</tt><tt class="descname">error</tt><big>(</big>message<big>)</big><a class="headerlink" href="#argparse.ArgumentParser.error" title="Permalink to this definition">¶</a></dt>

1897

<dd>This method prints a usage message including the message to the

1898

standard error and terminates the program with a status code of 2.

1899

</dd></dl>

1900

1901

</div>

1902

</div>

1903

1904

<h2>15.4.6. Upgrading optparse code<a class="headerlink" href="#upgrading-optparse-code" title="Permalink to this headline">¶</a></h2>

1905

Originally, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> module had attempted to maintain compatibility

1906

with <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><tt class="xref py py-mod docutils literal">optparse</tt></a>. However, <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><tt class="xref py py-mod docutils literal">optparse</tt></a> was difficult to extend

1907

transparently, particularly with the changes required to support the new

1908

<tt class="docutils literal">nargs=</tt> specifiers and better usage messages. When most everything in

1909

<a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><tt class="xref py py-mod docutils literal">optparse</tt></a> had either been copy-pasted over or monkey-patched, it no

1910

longer seemed practical to try to maintain the backwards compatibility.

1911

The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> module improves on the standard library <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><tt class="xref py py-mod docutils literal">optparse</tt></a>

1912

module in a number of ways including:

1913

1914

<li>Handling positional arguments.</li>

1915

<li>Supporting sub-commands.</li>

1916

<li>Allowing alternative option prefixes like <tt class="docutils literal">+</tt> and <tt class="docutils literal">/</tt>.</li>

1917

<li>Handling zero-or-more and one-or-more style arguments.</li>

1918

<li>Producing more informative usage messages.</li>

1919

<li>Providing a much simpler interface for custom <tt class="docutils literal">type</tt> and <tt class="docutils literal">action</tt>.</li>

1920

</ul>

1921

A partial upgrade path from <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><tt class="xref py py-mod docutils literal">optparse</tt></a> to <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a>:

1922

1923

<li>Replace all <a class="reference internal" href="optparse.html#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><tt class="xref py py-meth docutils literal">optparse.OptionParser.add_option()</tt></a> calls with

1924

1925

<li>Replace <tt class="docutils literal">(options, args) = parser.parse_args()</tt> with <tt class="docutils literal">args =

1926

parser.parse_args()</tt> and add additional <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><tt class="xref py py-meth docutils literal">ArgumentParser.add_argument()</tt></a>

1927

calls for the positional arguments. Keep in mind that what was previously

1928

called <tt class="docutils literal">options</tt>, now in <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><tt class="xref py py-mod docutils literal">argparse</tt></a> context is called <tt class="docutils literal">args</tt>.</li>

1929

<li>Replace callback actions and the <tt class="docutils literal">callback_*</tt> keyword arguments with

1930

<tt class="docutils literal">type</tt> or <tt class="docutils literal">action</tt> arguments.</li>

1931

<li>Replace string names for <tt class="docutils literal">type</tt> keyword arguments with the corresponding

1932

type objects (e.g. int, float, complex, etc).</li>

1933

<li>Replace <tt class="xref py py-class docutils literal">optparse.Values</tt> with <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><tt class="xref py py-class docutils literal">Namespace</tt></a> and

1934

<tt class="xref py py-exc docutils literal">optparse.OptionError</tt> and <tt class="xref py py-exc docutils literal">optparse.OptionValueError</tt> with

1935

<tt class="xref py py-exc docutils literal">ArgumentError</tt>.</li>

1936

<li>Replace strings with implicit arguments such as <tt class="docutils literal">%default</tt> or <tt class="docutils literal">%prog</tt> with

1937

the standard Python syntax to use dictionaries to format strings, that is,

1938

<tt class="docutils literal">%(default)s</tt> and <tt class="docutils literal">%(prog)s</tt>.</li>

1939

<li>Replace the OptionParser constructor <tt class="docutils literal">version</tt> argument with a call to

1940

<tt class="docutils literal">parser.add_argument('--version', action='version', version='<the version>')</tt></li>

1941

</ul>

1942

</div>

1943

</div>

1944

1945

1946

</div>

1947

</div>

1948

</div>

1949

1950

1951

<h3><a href="../contents.html">Table Of Contents</a></h3>

1952

<ul>

1953

<li><a class="reference internal" href="#">15.4. <tt class="docutils literal">argparse</tt> — Parser for command-line options, arguments and sub-commands</a><ul>

1954

<li><a class="reference internal" href="#example">15.4.1. Example</a><ul>

1955

<li><a class="reference internal" href="#creating-a-parser">15.4.1.1. Creating a parser</a></li>

1956

<li><a class="reference internal" href="#adding-arguments">15.4.1.2. Adding arguments</a></li>

1957

<li><a class="reference internal" href="#parsing-arguments">15.4.1.3. Parsing arguments</a></li>

1958

</ul>

1959

</li>

1960

<li><a class="reference internal" href="#argumentparser-objects">15.4.2. ArgumentParser objects</a><ul>

1961

1962

<li><a class="reference internal" href="#usage">15.4.2.2. usage</a></li>

1963

<li><a class="reference internal" href="#description">15.4.2.3. description</a></li>

1964

<li><a class="reference internal" href="#epilog">15.4.2.4. epilog</a></li>

1965

<li><a class="reference internal" href="#parents">15.4.2.5. parents</a></li>

1966

<li><a class="reference internal" href="#formatter-class">15.4.2.6. formatter_class</a></li>

1967

<li><a class="reference internal" href="#prefix-chars">15.4.2.7. prefix_chars</a></li>

1968

<li><a class="reference internal" href="#fromfile-prefix-chars">15.4.2.8. fromfile_prefix_chars</a></li>

1969

<li><a class="reference internal" href="#argument-default">15.4.2.9. argument_default</a></li>

1970

<li><a class="reference internal" href="#conflict-handler">15.4.2.10. conflict_handler</a></li>

1971

1972

</ul>

1973

</li>

1974

<li><a class="reference internal" href="#the-add-argument-method">15.4.3. The add_argument() method</a><ul>

1975

<li><a class="reference internal" href="#name-or-flags">15.4.3.1. name or flags</a></li>

1976

<li><a class="reference internal" href="#action">15.4.3.2. action</a></li>

1977

<li><a class="reference internal" href="#nargs">15.4.3.3. nargs</a></li>

1978

<li><a class="reference internal" href="#const">15.4.3.4. const</a></li>

1979

<li><a class="reference internal" href="#default">15.4.3.5. default</a></li>

1980

1981

<li><a class="reference internal" href="#choices">15.4.3.7. choices</a></li>

1982

<li><a class="reference internal" href="#required">15.4.3.8. required</a></li>

1983

1984

<li><a class="reference internal" href="#metavar">15.4.3.10. metavar</a></li>

1985

1986

<li><a class="reference internal" href="#action-classes">15.4.3.12. Action classes</a></li>

1987

</ul>

1988

</li>

1989

<li><a class="reference internal" href="#the-parse-args-method">15.4.4. The parse_args() method</a><ul>

1990

<li><a class="reference internal" href="#option-value-syntax">15.4.4.1. Option value syntax</a></li>

1991

<li><a class="reference internal" href="#invalid-arguments">15.4.4.2. Invalid arguments</a></li>

1992

<li><a class="reference internal" href="#arguments-containing">15.4.4.3. Arguments containing <tt class="docutils literal">-</tt></a></li>

1993

<li><a class="reference internal" href="#argument-abbreviations-prefix-matching">15.4.4.4. Argument abbreviations (prefix matching)</a></li>

1994

<li><a class="reference internal" href="#beyond-sys-argv">15.4.4.5. Beyond <tt class="docutils literal">sys.argv</tt></a></li>

1995

<li><a class="reference internal" href="#the-namespace-object">15.4.4.6. The Namespace object</a></li>

1996

</ul>

1997

</li>

1998

<li><a class="reference internal" href="#other-utilities">15.4.5. Other utilities</a><ul>

1999

<li><a class="reference internal" href="#sub-commands">15.4.5.1. Sub-commands</a></li>

2000

<li><a class="reference internal" href="#filetype-objects">15.4.5.2. FileType objects</a></li>

2001

<li><a class="reference internal" href="#argument-groups">15.4.5.3. Argument groups</a></li>

2002

<li><a class="reference internal" href="#mutual-exclusion">15.4.5.4. Mutual exclusion</a></li>

2003

<li><a class="reference internal" href="#parser-defaults">15.4.5.5. Parser defaults</a></li>

2004

<li><a class="reference internal" href="#printing-help">15.4.5.6. Printing help</a></li>

2005

<li><a class="reference internal" href="#partial-parsing">15.4.5.7. Partial parsing</a></li>

2006

<li><a class="reference internal" href="#customizing-file-parsing">15.4.5.8. Customizing file parsing</a></li>

2007

<li><a class="reference internal" href="#exiting-methods">15.4.5.9. Exiting methods</a></li>

2008

</ul>

2009

</li>

2010

<li><a class="reference internal" href="#upgrading-optparse-code">15.4.6. Upgrading optparse code</a></li>

2011

</ul>

2012

</li>

2013

</ul>

2014

2015

<h4>Previous topic</h4>

2016

<a href="time.html"

2017

title="previous chapter">15.3. <tt class="docutils literal">time</tt> — Time access and conversions</a>

2018

<h4>Next topic</h4>

2019

<a href="optparse.html"

2020

title="next chapter">15.5. <tt class="docutils literal">optparse</tt> — Parser for command line options</a>

2021

2022

2023

<li><a href="../bugs.html">Report a Bug</a></li>

2024

<li><a href="../_sources/library/argparse.txt"

2025

rel="nofollow">Show Source</a></li>

2026

</ul>

2027

2028

2029

<h3>Quick search</h3>

2030

2031

2032

2033

2034

2035

</form>

2036

2037

Enter search terms or a module, class or function name.

2038

2039

</div>

2040

2041

</div>

2042

</div>

2043

2044

</div>

2045

2046

<h3>Navigation</h3>

2047

<ul>

2048

2049

<a href="../genindex.html" title="General Index"

2050

>index</a></li>

2051

2052

<a href="../py-modindex.html" title="Python Module Index"

2053

>modules</a> |</li>

2054

2055

<a href="optparse.html" title="15.5. optparse — Parser for command line options"

2056

>next</a> |</li>

2057

2058

<a href="time.html" title="15.3. time — Time access and conversions"

2059

>previous</a> |</li>

2060

<li><img src="../_static/py.png" alt=""

2061

style="vertical-align: middle; margin-top: -1px"/></li>

2062

<li><a href="https://www.python.org/">Python</a> »</li>

2063

<li>

2064

2.7.10

2065

<a href="../index.html">Documentation</a> »

2066

</li>

2067

2068

<li><a href="index.html" >The Python Standard Library</a> »</li>

2069

<li><a href="allos.html" >15. Generic Operating System Services</a> »</li>

2070

</ul>

2071

</div>

2072

2073

2074

2075

The Python Software Foundation is a non-profit corporation.

2076

<a href="https://www.python.org/psf/donations/">Please donate.</a>

2077

2078

Last updated on May 23, 2015.

2079

<a href="../bugs.html">Found a bug</a>?

2080

2081

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2.3.

2082

</div>

2083

2084

</body>

2085

</html>

b'\\ No newline at end of file'

Older »