python-docs-fa/howto/argparse.html at gh-pages · python/python-docs-fa

History

1206 lines (1127 loc) · 107 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html>

<head>

<title>Argparse Tutorial — مستندات Python3.14.6</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

title="جستجو در مستندات Python3.14.6"

href="../_static/opensearch.xml"/>

<style>

@media only screen {

table.full-width-table {

width: 100%;

}

</style>

</head>

<body>

<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">

</label>

</a>

</svg>

</form>

</nav>

Theme

<option value="light">Light</option>

</select>

</label>

<div>

<h3><a href="../contents.html">فهرست عناوین</a></h3>

<ul>

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

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

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

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

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

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

</ul>

</li>

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

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

<li><a class="reference internal" href="#specifying-ambiguous-arguments">Specifying ambiguous arguments</a></li>

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

</ul>

</li>

<li><a class="reference internal" href="#how-to-translate-the-argparse-output">How to translate the argparse output</a></li>

<li><a class="reference internal" href="#custom-type-converters">Custom type converters</a></li>

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

</ul>

</li>

</ul>

</div>

<div>

<h4>موضوع قبلی</h4>

<a href="../library/argparse.html"

title="فصل قبلی"><code class="xref py py-mod docutils literal notranslate">argparse</code> --- Parser for command-line options, arguments and subcommands</a>

</div>

<div>

<h4>موضوع بعدی</h4>

<a href="argparse-optparse.html"

title="فصل بعدی">Migrating <code class="docutils literal notranslate">optparse</code> code to <code class="docutils literal notranslate">argparse</code></a>

</div>

document.addEventListener('DOMContentLoaded', () => {

const title = document.querySelector('meta[property="og:title"]').content;

const elements = document.querySelectorAll('.improvepage');

const pageurl = window.location.href.split('?')[0];

elements.forEach(element => {

const url = new URL(element.href.split('?')[0].replace("-nojs", ""));

url.searchParams.set('pagetitle', title);

url.searchParams.set('pageurl', pageurl);

url.searchParams.set('pagesource', "howto/argparse.rst");

element.href = url.toString();

});

</script>

<li><a href="../bugs.html">گزارش یک اشکال</a></li>

<li><a class="improvepage" href="../improve-page-nojs.html">بهبود این صفحه</a></li>

<li>

<a href="https://github.com/python/cpython/blob/main/Doc/howto/argparse.rst?plain=1"

rel="nofollow">نمایش منبع

</a>

</li>

<li>

<a href="https://github.com/python/python-docs-fa/blob/3.14/howto/argparse.po?plain=1"

rel="nofollow">نمایش منبع ترجمه</a>

</li>

</ul>

</div>

</nav>

</div>

<h3>ناوبری</h3>

<ul>

<a href="../genindex.html" title="فهرست کلی"

accesskey="I">فهرست</a></li>

<a href="../py-modindex.html" title="نمایه ی ماژول های پایتون"

>ماژول ها</a> |</li>

<a href="argparse-optparse.html" title="Migrating optparse code to argparse"

accesskey="N">بعدی</a> |</li>

<a href="../library/argparse.html" title="argparse --- Parser for command-line options, arguments and subcommands"

accesskey="P">قبلی</a> |</li>

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

</li>

<li>

</li>

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

</li>

<li class="nav-item nav-item-1"><a href="../library/index.html" >The Python Standard Library</a> »</li>

<li class="nav-item nav-item-2"><a href="../library/cmdlinelibs.html" >Command-line interface libraries</a> »</li>

<li class="nav-item nav-item-3"><a href="../library/argparse.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate">argparse</code> --- Parser for command-line options, arguments and subcommands</a> »</li>

<li class="nav-item nav-item-this"><a href="">Argparse Tutorial</a></li>

</form>

</div>

</li>

Theme

<option value="light">Light</option>

</select>

</label> |</li>

</ul>

</div>

<h1>Argparse Tutorial<a class="headerlink" href="#argparse-tutorial" title="Link to this heading">¶</a></h1>

<dt class="field-odd">author:</dt>

<dd class="field-odd">Tshepang Mbambo

</dd>

</dl>

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 notranslate">argparse</code></a>, the

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

توجه

The standard library includes two other libraries directly related

to command-line parameter processing: the lower level <a class="reference internal" href="../library/optparse.html#module-optparse" title="optparse: Command-line option parsing library."><code class="xref py py-mod docutils literal notranslate">optparse</code></a>

module (which may require more code to configure for a given application,

but also allows an application to request behaviors that <code class="docutils literal notranslate">argparse</code>

doesn't support), and the very low level <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 notranslate">getopt</code></a> (which specifically

serves as an equivalent to the <code class="xref c c-func docutils literal notranslate">getopt()</code> family of functions

available to C programmers).

While neither of those modules is covered directly in this guide, many of

the core concepts in <code class="docutils literal notranslate">argparse</code> first originated in <code class="docutils literal notranslate">optparse</code>, so

some aspects of this tutorial will also be relevant to <code class="docutils literal notranslate">optparse</code> users.

</div>

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

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

introductory tutorial by making use of the ls command:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ ls

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

$ ls pypy

ctypes_configure demo dotviewer include lib_pypy lib-python ...

$ ls -l

total 20

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

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

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

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

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

$ ls --help

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

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

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

...

</pre></div>

</div>

A few concepts we can learn from the four commands:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</ul>

</section>

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

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

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

parser = argparse.ArgumentParser()

parser.parse_args()

</pre></div>

</div>

Following is a result of running the code:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py

$ python prog.py --help

usage: prog.py [-h]

options:

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

$ python prog.py --verbose

usage: prog.py [-h]

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

$ python prog.py foo

usage: prog.py [-h]

prog.py: error: unrecognized arguments: foo

</pre></div>

</div>

Here is what is happening:

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

stdout. Not so useful.</li>

<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 notranslate">argparse</code></a>

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

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

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

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

also for free.</li>

</ul>

</section>

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

An example:

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

parser = argparse.ArgumentParser()

parser.add_argument("echo")

args = parser.parse_args()

print(args.echo)

</pre></div>

</div>

And running the code:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py

usage: prog.py [-h] echo

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

$ python prog.py --help

usage: prog.py [-h] echo

positional arguments:

echo

options:

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

$ python prog.py foo

foo

</pre></div>

</div>

Here is what's happening:

<li>We've added the <a class="reference internal" href="../library/argparse.html#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> method, which is what we use to specify

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

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

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

<li>The <a class="reference internal" href="../library/argparse.html#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method actually returns some data from the

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

<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 notranslate">argparse</code></a> performs for free

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

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

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

</ul>

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

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

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

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

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

parser = argparse.ArgumentParser()

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

args = parser.parse_args()

print(args.echo)

</pre></div>

</div>

And we get:

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

usage: prog.py [-h] echo

positional arguments:

echo echo the string you use here

options:

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

</pre></div>

</div>

Now, how about doing something even more useful:

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

parser = argparse.ArgumentParser()

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

args = parser.parse_args()

print(args.square**2)

</pre></div>

</div>

Following is a result of running the code:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py 4

Traceback (most recent call last):

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

print(args.square**2)

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

</pre></div>

</div>

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 notranslate">argparse</code></a> treats the options we

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

<code class="xref py py-mod docutils literal notranslate">argparse</code> to treat that input as an integer:

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

parser = argparse.ArgumentParser()

type=int)

args = parser.parse_args()

</pre></div>

</div>

Following is a result of running the code:

16

$ python prog.py four

usage: prog.py [-h] square

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

</pre></div>

</div>

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

before proceeding.

</section>

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

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

have a look on how to add optional ones:

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

parser = argparse.ArgumentParser()

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

args = parser.parse_args()

if args.verbosity:

print("verbosity turned on")

</pre></div>

</div>

And the output:

verbosity turned on

$ python prog.py

$ python prog.py --help

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

options:

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

--verbosity VERBOSITY

increase output verbosity

$ python prog.py --verbosity

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

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

</pre></div>

</div>

Here is what is happening:

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

specified and display nothing when not.</li>

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

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

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

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

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

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

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

any value.</li>

</ul>

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

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

Let's modify the code accordingly:

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

parser = argparse.ArgumentParser()

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

action="store_true")

args = parser.parse_args()

if args.verbose:

print("verbosity turned on")

</pre></div>

</div>

And the output:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py --verbose

verbosity turned on

$ python prog.py --verbose 1

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

prog.py: error: unrecognized arguments: 1

$ python prog.py --help

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

options:

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

--verbose increase output verbosity

</pre></div>

</div>

Here is what is happening:

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

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

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

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

assign the value <code class="docutils literal notranslate">True</code> to <code class="docutils literal notranslate">args.verbose</code>.

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

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

actually are.</li>

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

</ul>

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

If you are familiar with command line usage,

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

versions of the options. It's quite simple:

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

parser = argparse.ArgumentParser()

action="store_true")

args = parser.parse_args()

if args.verbose:

print("verbosity turned on")

</pre></div>

</div>

And here goes:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py -v

verbosity turned on

$ python prog.py --help

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

options:

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

-v, --verbose increase output verbosity

</pre></div>

</div>

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

</section>

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

Our program keeps growing in complexity:

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

parser = argparse.ArgumentParser()

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

if args.verbose:

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

else:

print(answer)

</pre></div>

</div>

And now the output:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py

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

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

$ python prog.py 4

16

$ python prog.py 4 --verbose

the square of 4 equals 16

$ python prog.py --verbose 4

the square of 4 equals 16

</pre></div>

</div>

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

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

</ul>

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

multiple verbosity values, and actually get to use them:

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

parser = argparse.ArgumentParser()

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

if args.verbosity == 2:

elif args.verbosity == 1:

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

else:

print(answer)

</pre></div>

</div>

And the output:

16

$ python prog.py 4 -v

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

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

$ python prog.py 4 -v 1

4^2 == 16

$ python prog.py 4 -v 2

the square of 4 equals 16

$ python prog.py 4 -v 3

16

</pre></div>

</div>

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

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

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

parser = argparse.ArgumentParser()

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

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

if args.verbosity == 2:

elif args.verbosity == 1:

else:

print(answer)

</pre></div>

</div>

And the output:

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

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

$ python prog.py 4 -h

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

positional arguments:

square display a square of a given number

options:

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

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

increase output verbosity

</pre></div>

</div>

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

help string.

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

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

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

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

parser = argparse.ArgumentParser()

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

if args.verbosity == 2:

elif args.verbosity == 1:

else:

print(answer)

</pre></div>

</div>

We have introduced another action, "count",

to count the number of occurrences of specific options.

16

$ python prog.py 4 -v

4^2 == 16

$ python prog.py 4 -vv

the square of 4 equals 16

$ python prog.py 4 --verbosity --verbosity

the square of 4 equals 16

$ python prog.py 4 -v 1

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

prog.py: error: unrecognized arguments: 1

$ python prog.py 4 -h

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

positional arguments:

square display a square of a given number

options:

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

-v, --verbosity increase output verbosity

$ python prog.py 4 -vvv

16

</pre></div>

</div>

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

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

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

<li>Now here's a demonstration of what the "count" action gives. You've probably

seen this sort of usage before.</li>

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

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

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

the same output.</li>

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

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

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

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

</ul>

Let's fix:

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

parser = argparse.ArgumentParser()

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

# bugfix: replace == with >=

if args.verbosity >= 2:

elif args.verbosity >= 1:

else:

print(answer)

</pre></div>

</div>

And this is what it gives:

the square of 4 equals 16

$ python prog.py 4 -vvvv

the square of 4 equals 16

$ python prog.py 4

Traceback (most recent call last):

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

if args.verbosity >= 2:

TypeError: '>=' not supported between instances of 'NoneType' and 'int'

</pre></div>

</div>

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

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

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

</ul>

Let's fix that bug:

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

parser = argparse.ArgumentParser()

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

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

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

help="increase output verbosity")

args = parser.parse_args()

answer = args.square**2

if args.verbosity >= 2:

elif args.verbosity >= 1:

else:

print(answer)

</pre></div>

</div>

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

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

Remember that by default,

if an optional argument isn't specified,

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

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

And:

16

</pre></div>

</div>

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

and we have only scratched the surface.

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 notranslate">argparse</code></a> module is very powerful,

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

</section>

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

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

not just squares:

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

parser = argparse.ArgumentParser()

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

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

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

args = parser.parse_args()

answer = args.x**args.y

if args.verbosity >= 2:

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

elif args.verbosity >= 1:

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

else:

print(answer)

</pre></div>

</div>

Output:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py

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

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

$ python prog.py -h

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

positional arguments:

x the base

y the exponent

options:

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

-v, --verbosity

$ python prog.py 4 2 -v

4^2 == 16

</pre></div>

</div>

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

that gets displayed. The following example instead uses verbosity level

to display more text instead:

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

parser = argparse.ArgumentParser()

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

args = parser.parse_args()

if args.verbosity >= 2:

print(f"Running '{__file__}'")

if args.verbosity >= 1:

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

print(answer)

</pre></div>

</div>

Output:

16

$ python prog.py 4 2 -v

4^2 == 16

$ python prog.py 4 2 -vv

Running 'prog.py'

4^2 == 16

</pre></div>

</div>

<h3>Specifying ambiguous arguments<a class="headerlink" href="#specifying-ambiguous-arguments" title="Link to this heading">¶</a></h3>

When there is ambiguity in deciding whether an argument is positional or for an

argument, <code class="docutils literal notranslate">--</code> can be used to tell <a class="reference internal" href="../library/argparse.html#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> that

everything after that is a positional argument:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> parser = argparse.ArgumentParser(prog='PROG')

>>> parser.add_argument('-n', nargs='+')

>>> parser.add_argument('args', nargs='*')

>>> # ambiguous, so parse_args assumes it's an option

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

usage: PROG [-h] [-n N [N ...]] [args ...]

PROG: error: unrecognized arguments: -f

Namespace(args=['-f'], n=None)

>>> # ambiguous, so the -n option greedily accepts arguments

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

Namespace(args=[], n=['1', '2', '3'])

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

Namespace(args=['2', '3'], n=['1'])

</pre></div>

</div>

</section>

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

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

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

<a class="reference internal" href="../library/argparse.html#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate">add_mutually_exclusive_group()</code></a>. It allows for us to specify options that

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

the new functionality makes more sense:

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

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

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

parser = argparse.ArgumentParser()

group = parser.add_mutually_exclusive_group()

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

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

args = parser.parse_args()

if args.quiet:

print(answer)

elif args.verbose:

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

else:

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

</pre></div>

</div>

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

demonstration. Anyways, here's the output:

4^2 == 16

$ python prog.py 4 2 -q

16

$ python prog.py 4 2 -v

4 to the power 2 equals 16

$ python prog.py 4 2 -vq

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

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

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

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

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

</pre></div>

</div>

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

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

ones.

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

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

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

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

group = parser.add_mutually_exclusive_group()

args = parser.parse_args()

if args.quiet:

print(answer)

elif args.verbose:

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

else:

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

</pre></div>

</div>

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

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

but not both at the same time:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py --help

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

calculate X to the power of Y

positional arguments:

x the base

y the exponent

options:

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

-v, --verbose

-q, --quiet

</pre></div>

</div>

</section>

<h2>How to translate the argparse output<a class="headerlink" href="#how-to-translate-the-argparse-output" title="Link to this heading">¶</a></h2>

The output 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 notranslate">argparse</code></a> module such as its help text and error

messages are all made translatable using the <a class="reference internal" href="../library/gettext.html#module-gettext" title="gettext: Multilingual internationalization services."><code class="xref py py-mod docutils literal notranslate">gettext</code></a> module. This

allows applications to easily localize messages produced by

<code class="xref py py-mod docutils literal notranslate">argparse</code>. See also <a class="reference internal" href="../library/gettext.html#i18n-howto">Internationalizing your programs and modules</a>.

For instance, in this <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 notranslate">argparse</code></a> output:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py --help

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

calculate X to the power of Y

positional arguments:

x the base

y the exponent

options:

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

-v, --verbose

-q, --quiet

</pre></div>

</div>

The strings <code class="docutils literal notranslate">usage:</code>, <code class="docutils literal notranslate">positional arguments:</code>, <code class="docutils literal notranslate">options:</code> and

<code class="docutils literal notranslate">show this help message and exit</code> are all translatable.

In order to translate these strings, they must first be extracted

into a <code class="docutils literal notranslate">.po</code> file. For example, using <a class="reference external" href="https://babel.pocoo.org/">Babel</a>,

run this command:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ pybabel extract -o messages.po /usr/lib/python3.12/argparse.py

</pre></div>

</div>

This command will extract all translatable strings from 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 notranslate">argparse</code></a>

module and output them into a file named <code class="docutils literal notranslate">messages.po</code>. This command assumes

that your Python installation is in <code class="docutils literal notranslate">/usr/lib</code>.

You can find out the location 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 notranslate">argparse</code></a> module on your system

using this script:

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

print(argparse.__file__)

</pre></div>

</div>

Once the messages in the <code class="docutils literal notranslate">.po</code> file are translated and the translations are

installed using <a class="reference internal" href="../library/gettext.html#module-gettext" title="gettext: Multilingual internationalization services."><code class="xref py py-mod docutils literal notranslate">gettext</code></a>, <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 notranslate">argparse</code></a> will be able to display the

translated messages.

To translate your own strings in 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 notranslate">argparse</code></a> output, use <a class="reference internal" href="../library/gettext.html#module-gettext" title="gettext: Multilingual internationalization services."><code class="xref py py-mod docutils literal notranslate">gettext</code></a>.

</section>

<h2>Custom type converters<a class="headerlink" href="#custom-type-converters" title="Link to this heading">¶</a></h2>

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 notranslate">argparse</code></a> module allows you to specify custom type converters for

your command-line arguments. This allows you to modify user input before it's

stored in the <a class="reference internal" href="../library/argparse.html#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">argparse.Namespace</code></a>. This can be useful when you need to

pre-process the input before it is used in your program.

When using a custom type converter, you can use any callable that takes a

single string argument (the argument value) and returns the converted value.

However, if you need to handle more complex scenarios, you can use a custom

action class with the action parameter instead.

View remainder of file in raw view

Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

argparse.html

Latest commit

History

argparse.html

File metadata and controls