~dkuhlman/python-training-materials/Materials

This tutorial is intended to be a gentle introduction to <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a>, the

104

recommended command-line parsing module in the Python standard library.

105

106

Note

107

There are two other modules that fulfill the same task, namely

108

<a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-mod docutils literal">getopt</code></a> (an equivalent for <code class="xref c c-func docutils literal">getopt()</code> from the C

109

language) and the deprecated <a class="reference internal" href="../library/optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal">optparse</code></a>.

110

Note also that <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> is based on <a class="reference internal" href="../library/optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal">optparse</code></a>,

111

and therefore very similar in terms of usage.

112

</div>

113

114

<h2>Concepts<a class="headerlink" href="#concepts" title="Permalink to this headline">¶</a></h2>

115

Let’s show the sort of functionality that we are going to explore in this

116

introductory tutorial by making use of the ls command:

117

<div class="highlight-sh"><div class="highlight"><pre>$ ls

118

cpython devguide prog.py pypy rm-unused-function.patch

119

$ ls pypy

120

ctypes_configure demo dotviewer include lib_pypy lib-python ...

121

$ ls -l

122

total 20

123

drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython

124

drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide

125

-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py

126

drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy

127

-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch

128

$ ls --help

129

Usage: ls [OPTION]... [FILE]...

130

List information about the FILEs (the current directory by default).

131

Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

132

...

133

</pre></div>

134

</div>

135

A few concepts we can learn from the four commands:

136

137

<li>The ls command is useful when run without any options at all. It defaults

138

to displaying the contents of the current directory.</li>

139

<li>If we want beyond what it provides by default, we tell it a bit more. In

140

this case, we want it to display a different directory, <code class="docutils literal">pypy</code>.

141

What we did is specify what is known as a positional argument. It’s named so

142

because the program should know what to do with the value, solely based on

143

where it appears on the command line. This concept is more relevant

144

to a command like cp, whose most basic usage is <code class="docutils literal">cp SRC DEST</code>.

145

The first position is what you want copied, and the second

146

position is where you want it copied to.</li>

147

<li>Now, say we want to change behaviour of the program. In our example,

148

we display more info for each file instead of just showing the file names.

149

The <code class="docutils literal">-l</code> in that case is known as an optional argument.</li>

150

<li>That’s a snippet of the help text. It’s very useful in that you can

151

come across a program you have never used before, and can figure out

152

how it works simply by reading its help text.</li>

153

</ul>

154

</div>

155

156

<h2>The basics<a class="headerlink" href="#the-basics" title="Permalink to this headline">¶</a></h2>

157

Let us start with a very simple example which does (almost) nothing:

158

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

159

parser = argparse.ArgumentParser()

160

parser.parse_args()

161

</pre></div>

162

</div>

163

Following is a result of running the code:

164

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py

165

$ python3 prog.py --help

166

usage: prog.py [-h]

167

168

optional arguments:

169

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

170

$ python3 prog.py --verbose

171

usage: prog.py [-h]

172

prog.py: error: unrecognized arguments: --verbose

173

$ python3 prog.py foo

174

usage: prog.py [-h]

175

prog.py: error: unrecognized arguments: foo

176

</pre></div>

177

</div>

178

Here is what is happening:

179

180

<li>Running the script without any options results in nothing displayed to

181

stdout. Not so useful.</li>

182

<li>The second one starts to display the usefulness of the <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a>

183

module. We have done almost nothing, but already we get a nice help message.</li>

184

<li>The <code class="docutils literal">--help</code> option, which can also be shortened to <code class="docutils literal">-h</code>, is the only

185

option we get for free (i.e. no need to specify it). Specifying anything

186

else results in an error. But even then, we do get a useful usage message,

187

also for free.</li>

188

</ul>

189

</div>

190

191

<h2>Introducing Positional arguments<a class="headerlink" href="#introducing-positional-arguments" title="Permalink to this headline">¶</a></h2>

192

An example:

193

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

194

parser = argparse.ArgumentParser()

195

parser.add_argument("echo")

196

args = parser.parse_args()

197

print(args.echo)

198

</pre></div>

199

</div>

200

And running the code:

201

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py

202

usage: prog.py [-h] echo

203

prog.py: error: the following arguments are required: echo

204

$ python3 prog.py --help

205

usage: prog.py [-h] echo

206

207

positional arguments:

208

echo

209

210

optional arguments:

211

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

212

$ python3 prog.py foo

213

foo

214

</pre></div>

215

</div>

216

Here is what’s happening:

217

218

<li>We’ve added the <code class="xref py py-meth docutils literal">add_argument()</code> method, which is what we use to specify

219

which command-line options the program is willing to accept. In this case,

220

I’ve named it <code class="docutils literal">echo</code> so that it’s in line with its function.</li>

221

<li>Calling our program now requires us to specify an option.</li>

222

<li>The <code class="xref py py-meth docutils literal">parse_args()</code> method actually returns some data from the

223

options specified, in this case, <code class="docutils literal">echo</code>.</li>

224

<li>The variable is some form of ‘magic’ that <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> performs for free

225

(i.e. no need to specify which variable that value is stored in).

226

You will also notice that its name matches the string argument given

227

to the method, <code class="docutils literal">echo</code>.</li>

228

</ul>

229

Note however that, although the help display looks nice and all, it currently

230

is not as helpful as it can be. For example we see that we got <code class="docutils literal">echo</code> as a

231

positional argument, but we don’t know what it does, other than by guessing or

232

by reading the source code. So, let’s make it a bit more useful:

233

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

234

parser = argparse.ArgumentParser()

235

parser.add_argument("echo", help="echo the string you use here")

236

args = parser.parse_args()

237

print(args.echo)

238

</pre></div>

239

</div>

240

And we get:

241

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

242

usage: prog.py [-h] echo

243

244

positional arguments:

245

echo echo the string you use here

246

247

optional arguments:

248

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

249

</pre></div>

250

</div>

251

Now, how about doing something even more useful:

252

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

253

parser = argparse.ArgumentParser()

254

parser.add_argument("square", help="display a square of a given number")

255

args = parser.parse_args()

256

print(args.square**2)

257

</pre></div>

258

</div>

259

Following is a result of running the code:

260

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4

261

Traceback (most recent call last):

262

File "prog.py", line 5, in <module>

263

print(args.square**2)

264

TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'

265

</pre></div>

266

</div>

267

That didn’t go so well. That’s because <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> treats the options we

268

give it as strings, unless we tell it otherwise. So, let’s tell

269

<a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> to treat that input as an integer:

270

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

271

parser = argparse.ArgumentParser()

272

273

type=int)

274

args = parser.parse_args()

275

276

</pre></div>

277

</div>

278

Following is a result of running the code:

279

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4

280

281

$ python3 prog.py four

282

usage: prog.py [-h] square

283

prog.py: error: argument square: invalid int value: 'four'

284

</pre></div>

285

</div>

286

That went well. The program now even helpfully quits on bad illegal input

287

before proceeding.

288

</div>

289

290

<h2>Introducing Optional arguments<a class="headerlink" href="#introducing-optional-arguments" title="Permalink to this headline">¶</a></h2>

291

So far we, have been playing with positional arguments. Let us

292

have a look on how to add optional ones:

293

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

294

parser = argparse.ArgumentParser()

295

parser.add_argument("--verbosity", help="increase output verbosity")

296

args = parser.parse_args()

297

if args.verbosity:

298

print("verbosity turned on")

299

</pre></div>

300

</div>

301

And the output:

302

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py --verbosity 1

303

verbosity turned on

304

$ python3 prog.py

305

$ python3 prog.py --help

306

usage: prog.py [-h] [--verbosity VERBOSITY]

307

308

optional arguments:

309

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

310

--verbosity VERBOSITY

311

increase output verbosity

312

$ python3 prog.py --verbosity

313

usage: prog.py [-h] [--verbosity VERBOSITY]

314

prog.py: error: argument --verbosity: expected one argument

315

</pre></div>

316

</div>

317

Here is what is happening:

318

319

<li>The program is written so as to display something when <code class="docutils literal">--verbosity</code> is

320

specified and display nothing when not.</li>

321

<li>To show that the option is actually optional, there is no error when running

322

the program without it. Note that by default, if an optional argument isn’t

323

used, the relevant variable, in this case <code class="xref py py-attr docutils literal">args.verbosity</code>, is

324

given <code class="docutils literal">None</code> as a value, which is the reason it fails the truth

325

test of the <a class="reference internal" href="../reference/compound_stmts.html#if"><code class="xref std std-keyword docutils literal">if</code></a> statement.</li>

326

<li>The help message is a bit different.</li>

327

<li>When using the <code class="docutils literal">--verbosity</code> option, one must also specify some value,

328

any value.</li>

329

</ul>

330

The above example accepts arbitrary integer values for <code class="docutils literal">--verbosity</code>, but for

331

our simple program, only two values are actually useful, <code class="docutils literal">True</code> or <code class="docutils literal">False</code>.

332

Let’s modify the code accordingly:

333

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

334

parser = argparse.ArgumentParser()

335

parser.add_argument("--verbose", help="increase output verbosity",

336

action="store_true")

337

args = parser.parse_args()

338

if args.verbose:

339

print("verbosity turned on")

340

</pre></div>

341

</div>

342

And the output:

343

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py --verbose

344

verbosity turned on

345

$ python3 prog.py --verbose 1

346

usage: prog.py [-h] [--verbose]

347

prog.py: error: unrecognized arguments: 1

348

$ python3 prog.py --help

349

usage: prog.py [-h] [--verbose]

350

351

optional arguments:

352

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

353

--verbose increase output verbosity

354

</pre></div>

355

</div>

356

Here is what is happening:

357

358

<li>The option is now more of a flag than something that requires a value.

359

We even changed the name of the option to match that idea.

360

Note that we now specify a new keyword, <code class="docutils literal">action</code>, and give it the value

361

<code class="docutils literal">"store_true"</code>. This means that, if the option is specified,

362

assign the value <code class="docutils literal">True</code> to <code class="xref py py-data docutils literal">args.verbose</code>.

363

Not specifying it implies <code class="docutils literal">False</code>.</li>

364

<li>It complains when you specify a value, in true spirit of what flags

365

actually are.</li>

366

<li>Notice the different help text.</li>

367

</ul>

368

369

<h3>Short options<a class="headerlink" href="#short-options" title="Permalink to this headline">¶</a></h3>

370

If you are familiar with command line usage,

371

you will notice that I haven’t yet touched on the topic of short

372

versions of the options. It’s quite simple:

373

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

374

parser = argparse.ArgumentParser()

375

376

action="store_true")

377

args = parser.parse_args()

378

if args.verbose:

379

print("verbosity turned on")

380

</pre></div>

381

</div>

382

And here goes:

383

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py -v

384

verbosity turned on

385

$ python3 prog.py --help

386

usage: prog.py [-h] [-v]

387

388

optional arguments:

389

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

390

-v, --verbose increase output verbosity

391

</pre></div>

392

</div>

393

Note that the new ability is also reflected in the help text.

394

</div>

395

</div>

396

397

<h2>Combining Positional and Optional arguments<a class="headerlink" href="#combining-positional-and-optional-arguments" title="Permalink to this headline">¶</a></h2>

398

Our program keeps growing in complexity:

399

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

400

parser = argparse.ArgumentParser()

401

parser.add_argument("square", type=int,

402

help="display a square of a given number")

403

404

help="increase output verbosity")

405

args = parser.parse_args()

406

answer = args.square**2

407

if args.verbose:

408

print("the square of {} equals {}".format(args.square, answer))

409

else:

410

print(answer)

411

</pre></div>

412

</div>

413

And now the output:

414

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py

415

usage: prog.py [-h] [-v] square

416

prog.py: error: the following arguments are required: square

417

$ python3 prog.py 4

418

419

$ python3 prog.py 4 --verbose

420

the square of 4 equals 16

421

$ python3 prog.py --verbose 4

422

the square of 4 equals 16

423

</pre></div>

424

</div>

425

426

<li>We’ve brought back a positional argument, hence the complaint.</li>

427

<li>Note that the order does not matter.</li>

428

</ul>

429

How about we give this program of ours back the ability to have

430

multiple verbosity values, and actually get to use them:

431

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

432

parser = argparse.ArgumentParser()

433

parser.add_argument("square", type=int,

434

help="display a square of a given number")

435

436

help="increase output verbosity")

437

args = parser.parse_args()

438

answer = args.square**2

439

if args.verbosity == 2:

440

441

elif args.verbosity == 1:

442

print("{}^2 == {}".format(args.square, answer))

443

else:

444

print(answer)

445

</pre></div>

446

</div>

447

And the output:

448

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4

449

450

$ python3 prog.py 4 -v

451

usage: prog.py [-h] [-v VERBOSITY] square

452

prog.py: error: argument -v/--verbosity: expected one argument

453

$ python3 prog.py 4 -v 1

454

4^2 == 16

455

$ python3 prog.py 4 -v 2

456

the square of 4 equals 16

457

$ python3 prog.py 4 -v 3

458

459

</pre></div>

460

</div>

461

These all look good except the last one, which exposes a bug in our program.

462

Let’s fix it by restricting the values the <code class="docutils literal">--verbosity</code> option can accept:

463

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

464

parser = argparse.ArgumentParser()

465

parser.add_argument("square", type=int,

466

help="display a square of a given number")

467

parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],

468

help="increase output verbosity")

469

args = parser.parse_args()

470

answer = args.square**2

471

if args.verbosity == 2:

472

473

elif args.verbosity == 1:

474

475

else:

476

print(answer)

477

</pre></div>

478

</div>

479

And the output:

480

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4 -v 3

481

usage: prog.py [-h] [-v {0,1,2}] square

482

prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)

483

$ python3 prog.py 4 -h

484

usage: prog.py [-h] [-v {0,1,2}] square

485

486

positional arguments:

487

square display a square of a given number

488

489

optional arguments:

490

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

491

-v {0,1,2}, --verbosity {0,1,2}

492

increase output verbosity

493

</pre></div>

494

</div>

495

Note that the change also reflects both in the error message as well as the

496

help string.

497

Now, let’s use a different approach of playing with verbosity, which is pretty

498

common. It also matches the way the CPython executable handles its own

499

verbosity argument (check the output of <code class="docutils literal">python --help</code>):

500

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

501

parser = argparse.ArgumentParser()

502

parser.add_argument("square", type=int,

503

help="display the square of a given number")

504

505

help="increase output verbosity")

506

args = parser.parse_args()

507

answer = args.square**2

508

if args.verbosity == 2:

509

510

elif args.verbosity == 1:

511

512

else:

513

print(answer)

514

</pre></div>

515

</div>

516

We have introduced another action, “count”,

517

to count the number of occurrences of a specific optional arguments:

518

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4

519

520

$ python3 prog.py 4 -v

521

4^2 == 16

522

$ python3 prog.py 4 -vv

523

the square of 4 equals 16

524

$ python3 prog.py 4 --verbosity --verbosity

525

the square of 4 equals 16

526

$ python3 prog.py 4 -v 1

527

usage: prog.py [-h] [-v] square

528

prog.py: error: unrecognized arguments: 1

529

$ python3 prog.py 4 -h

530

usage: prog.py [-h] [-v] square

531

532

positional arguments:

533

square display a square of a given number

534

535

optional arguments:

536

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

537

-v, --verbosity increase output verbosity

538

$ python3 prog.py 4 -vvv

539

540

</pre></div>

541

</div>

542

543

<li>Yes, it’s now more of a flag (similar to <code class="docutils literal">action="store_true"</code>) in the

544

previous version of our script. That should explain the complaint.</li>

545

<li>It also behaves similar to “store_true” action.</li>

546

<li>Now here’s a demonstration of what the “count” action gives. You’ve probably

547

seen this sort of usage before.</li>

548

<li>And if you don’t specify the <code class="docutils literal">-v</code> flag, that flag is considered to have

549

<code class="docutils literal">None</code> value.</li>

550

<li>As should be expected, specifying the long form of the flag, we should get

551

the same output.</li>

552

<li>Sadly, our help output isn’t very informative on the new ability our script

553

has acquired, but that can always be fixed by improving the documentation for

554

our script (e.g. via the <code class="docutils literal">help</code> keyword argument).</li>

555

<li>That last output exposes a bug in our program.</li>

556

</ul>

557

Let’s fix:

558

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

559

parser = argparse.ArgumentParser()

560

parser.add_argument("square", type=int,

561

help="display a square of a given number")

562

563

help="increase output verbosity")

564

args = parser.parse_args()

565

answer = args.square**2

566

567

# bugfix: replace == with >=

568

if args.verbosity >= 2:

569

570

elif args.verbosity >= 1:

571

572

else:

573

print(answer)

574

</pre></div>

575

</div>

576

And this is what it gives:

577

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4 -vvv

578

the square of 4 equals 16

579

$ python3 prog.py 4 -vvvv

580

the square of 4 equals 16

581

$ python3 prog.py 4

582

Traceback (most recent call last):

583

File "prog.py", line 11, in <module>

584

if args.verbosity >= 2:

585

TypeError: unorderable types: NoneType() >= int()

586

</pre></div>

587

</div>

588

589

<li>First output went well, and fixes the bug we had before.

590

That is, we want any value >= 2 to be as verbose as possible.</li>

591

<li>Third output not so good.</li>

592

</ul>

593

Let’s fix that bug:

594

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

595

parser = argparse.ArgumentParser()

596

parser.add_argument("square", type=int,

597

help="display a square of a given number")

598

parser.add_argument("-v", "--verbosity", action="count", default=0,

599

help="increase output verbosity")

600

args = parser.parse_args()

601

answer = args.square**2

602

if args.verbosity >= 2:

603

604

elif args.verbosity >= 1:

605

606

else:

607

print(answer)

608

</pre></div>

609

</div>

610

We’ve just introduced yet another keyword, <code class="docutils literal">default</code>.

611

We’ve set it to <code class="docutils literal">0</code> in order to make it comparable to the other int values.

612

Remember that by default,

613

if an optional argument isn’t specified,

614

it gets the <code class="docutils literal">None</code> value, and that cannot be compared to an int value

615

(hence the <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> exception).

616

And:

617

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4

618

619

</pre></div>

620

</div>

621

You can go quite far just with what we’ve learned so far,

622

and we have only scratched the surface.

623

The <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> module is very powerful,

624

and we’ll explore a bit more of it before we end this tutorial.

625

</div>

626

627

<h2>Getting a little more advanced<a class="headerlink" href="#getting-a-little-more-advanced" title="Permalink to this headline">¶</a></h2>

628

What if we wanted to expand our tiny program to perform other powers,

629

not just squares:

630

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

631

parser = argparse.ArgumentParser()

632

parser.add_argument("x", type=int, help="the base")

633

parser.add_argument("y", type=int, help="the exponent")

634

parser.add_argument("-v", "--verbosity", action="count", default=0)

635

args = parser.parse_args()

636

answer = args.x**args.y

637

if args.verbosity >= 2:

638

print("{} to the power {} equals {}".format(args.x, args.y, answer))

639

elif args.verbosity >= 1:

640

print("{}^{} == {}".format(args.x, args.y, answer))

641

else:

642

print(answer)

643

</pre></div>

644

</div>

645

Output:

646

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py

647

usage: prog.py [-h] [-v] x y

648

prog.py: error: the following arguments are required: x, y

649

$ python3 prog.py -h

650

usage: prog.py [-h] [-v] x y

651

652

positional arguments:

653

x the base

654

y the exponent

655

656

optional arguments:

657

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

658

-v, --verbosity

659

$ python3 prog.py 4 2 -v

660

4^2 == 16

661

</pre></div>

662

</div>

663

Notice that so far we’ve been using verbosity level to change the text

664

that gets displayed. The following example instead uses verbosity level

665

to display more text instead:

666

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

667

parser = argparse.ArgumentParser()

668

669

670

parser.add_argument("-v", "--verbosity", action="count", default=0)

671

args = parser.parse_args()

672

673

if args.verbosity >= 2:

674

print("Running '{}'".format(__file__))

675

if args.verbosity >= 1:

676

print("{}^{} == ".format(args.x, args.y), end="")

677

print(answer)

678

</pre></div>

679

</div>

680

Output:

681

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4 2

682

683

$ python3 prog.py 4 2 -v

684

4^2 == 16

685

$ python3 prog.py 4 2 -vv

686

Running 'prog.py'

687

4^2 == 16

688

</pre></div>

689

</div>

690

691

<h3>Conflicting options<a class="headerlink" href="#conflicting-options" title="Permalink to this headline">¶</a></h3>

692

So far, we have been working with two methods of an

693

<a class="reference internal" href="../library/argparse.html#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal">argparse.ArgumentParser</code></a> instance. Let’s introduce a third one,

694

<code class="xref py py-meth docutils literal">add_mutually_exclusive_group()</code>. It allows for us to specify options that

695

conflict with each other. Let’s also change the rest of the program so that

696

the new functionality makes more sense:

697

we’ll introduce the <code class="docutils literal">--quiet</code> option,

698

which will be the opposite of the <code class="docutils literal">--verbose</code> one:

699

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

700

701

parser = argparse.ArgumentParser()

702

group = parser.add_mutually_exclusive_group()

703

group.add_argument("-v", "--verbose", action="store_true")

704

group.add_argument("-q", "--quiet", action="store_true")

705

706

707

args = parser.parse_args()

708

709

710

if args.quiet:

711

print(answer)

712

elif args.verbose:

713

714

else:

715

716

</pre></div>

717

</div>

718

Our program is now simpler, and we’ve lost some functionality for the sake of

719

demonstration. Anyways, here’s the output:

720

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py 4 2

721

4^2 == 16

722

$ python3 prog.py 4 2 -q

723

724

$ python3 prog.py 4 2 -v

725

4 to the power 2 equals 16

726

$ python3 prog.py 4 2 -vq

727

usage: prog.py [-h] [-v | -q] x y

728

prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

729

$ python3 prog.py 4 2 -v --quiet

730

usage: prog.py [-h] [-v | -q] x y

731

prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

732

</pre></div>

733

</div>

734

That should be easy to follow. I’ve added that last output so you can see the

735

sort of flexibility you get, i.e. mixing long form options with short form

736

ones.

737

Before we conclude, you probably want to tell your users the main purpose of

738

your program, just in case they don’t know:

739

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

740

741

parser = argparse.ArgumentParser(description="calculate X to the power of Y")

742

group = parser.add_mutually_exclusive_group()

743

744

745

746

747

args = parser.parse_args()

748

749

750

if args.quiet:

751

print(answer)

752

elif args.verbose:

753

754

else:

755

756

</pre></div>

757

</div>

758

Note that slight difference in the usage text. Note the <code class="docutils literal">[-v | -q]</code>,

759

which tells us that we can either use <code class="docutils literal">-v</code> or <code class="docutils literal">-q</code>,

760

but not both at the same time:

761

<div class="highlight-sh"><div class="highlight"><pre>$ python3 prog.py --help

762

usage: prog.py [-h] [-v | -q] x y

763

764

calculate X to the power of Y

765

766

positional arguments:

767

x the base

768

y the exponent

769

770

optional arguments:

771

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

772

-v, --verbose

773

-q, --quiet

774

</pre></div>

775

</div>

776

</div>

777

</div>

778

779

<h2>Conclusion<a class="headerlink" href="#conclusion" title="Permalink to this headline">¶</a></h2>

780

The <a class="reference internal" href="../library/argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal">argparse</code></a> module offers a lot more than shown here.

781

Its docs are quite detailed and thorough, and full of examples.

782

Having gone through this tutorial, you should easily digest them

783

without feeling overwhelmed.

784

</div>

785

</div>

786

787

788

</div>

789

</div>

790

</div>

791

792

793

<h3><a href="../contents.html">Table Of Contents</a></h3>

794

<ul>

795

<li><a class="reference internal" href="#">Argparse Tutorial</a><ul>

796

<li><a class="reference internal" href="#concepts">Concepts</a></li>

797

<li><a class="reference internal" href="#the-basics">The basics</a></li>

798

<li><a class="reference internal" href="#introducing-positional-arguments">Introducing Positional arguments</a></li>

799

<li><a class="reference internal" href="#introducing-optional-arguments">Introducing Optional arguments</a><ul>

800

<li><a class="reference internal" href="#short-options">Short options</a></li>

801

</ul>

802

</li>

803

<li><a class="reference internal" href="#combining-positional-and-optional-arguments">Combining Positional and Optional arguments</a></li>

804

<li><a class="reference internal" href="#getting-a-little-more-advanced">Getting a little more advanced</a><ul>

805

<li><a class="reference internal" href="#conflicting-options">Conflicting options</a></li>

806

</ul>

807

</li>

808

<li><a class="reference internal" href="#conclusion">Conclusion</a></li>

809

</ul>

810

</li>

811

</ul>

812

813

<h4>Previous topic</h4>

814

<a href="urllib2.html"

815

title="previous chapter">HOWTO Fetch Internet Resources Using The urllib Package</a>

816

<h4>Next topic</h4>

817

<a href="ipaddress.html"

818

title="next chapter">An introduction to the ipaddress module</a>

819

820

821

822

<li><a href="../bugs.html">Report a Bug</a></li>

823

<li><a href="../_sources/howto/argparse.txt"

824

rel="nofollow">Show Source</a></li>

825

</ul>

826

</div>

827

</div>

828

</div>

829

830

</div>

831

832

<h3>Navigation</h3>

833

<ul>

834

835

<a href="../genindex.html" title="General Index"

836

>index</a></li>

837

838

<a href="../py-modindex.html" title="Python Module Index"

839

>modules</a> |</li>

840

841

<a href="ipaddress.html" title="An introduction to the ipaddress module"

842

>next</a> |</li>

843

844

<a href="urllib2.html" title="HOWTO Fetch Internet Resources Using The urllib Package"

845

>previous</a> |</li>

846

<li><img src="../_static/py.png" alt=""

847

style="vertical-align: middle; margin-top: -1px"/></li>

848

<li><a href="https://www.python.org/">Python</a> »</li>

849

<li>

850

3.5.2

851

<a href="../index.html">Documentation </a> »

852

</li>

853

854

<li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> »</li>

855

856

857

858

859

860

861

862

863

864

</form>

865

</div>

866

867

868

</li>

869

870

</ul>

871

</div>

872

873

874

875

The Python Software Foundation is a non-profit corporation.

876

<a href="https://www.python.org/psf/donations/">Please donate.</a>

877

878

Last updated on Sep 23, 2016.

879

<a href="../bugs.html">Found a bug</a>?

880

881

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

882

</div>

883

884

</body>

885

</html>

b'\\ No newline at end of file'

Older »