Codestin Search App

History

1809 lines (1747 loc) · 129 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 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Argument Clinic How-To — Python 3.7.0 說明文件</title>

title="在 Python 3.7.0 說明文件中搜尋"

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

</head><body>

<ul>

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

accesskey="I">索引</a></li>

<a href="../py-modindex.html" title="Python 模組索引"

>模組</a> |</li>

<a href="instrumentation.html" title="Instrumenting CPython with DTrace and SystemTap"

accesskey="N">下一頁</a> |</li>

<a href="ipaddress.html" title="ipaddress模組介紹"

accesskey="P">上一頁</a> |</li>

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

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

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

<li>

zh_TW

3.7.0

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

</li>

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

</form>

</div>

</li>

</ul>

</div>

<h1>Argument Clinic How-To<a class="headerlink" href="#argument-clinic-how-to" title="本標題的永久連結">¶</a></h1>

<tr class="field-odd field"><th class="field-name">author:</th><td class="field-body">Larry Hastings</td>

</tr>

</tbody>

</table>

Abstract

Argument Clinic is a preprocessor for CPython C files.

Its purpose is to automate all the boilerplate involved

with writing argument parsing code for 「builtins」.

This document shows you how to convert your first C

function to work with Argument Clinic, and then introduces

some advanced topics on Argument Clinic usage.

Currently Argument Clinic is considered internal-only

for CPython. Its use is not supported for files outside

CPython, and no guarantees are made regarding backwards

compatibility for future versions. In other words: if you

maintain an external C extension for CPython, you’re welcome

to experiment with Argument Clinic in your own code. But the

version of Argument Clinic that ships with the next version

of CPython could be totally incompatible and break all your code.

</div>

<h2>The Goals Of Argument Clinic<a class="headerlink" href="#the-goals-of-argument-clinic" title="本標題的永久連結">¶</a></h2>

Argument Clinic’s primary goal

is to take over responsibility for all argument parsing code

inside CPython. This means that, when you convert a function

to work with Argument Clinic, that function should no longer

do any of its own argument parsing—the code generated by

Argument Clinic should be a 「black box」 to you, where CPython

calls in at the top, and your code gets called at the bottom,

with <code class="docutils literal notranslate">PyObject *args</code> (and maybe <code class="docutils literal notranslate">PyObject *kwargs</code>)

magically converted into the C variables and types you need.

In order for Argument Clinic to accomplish its primary goal,

it must be easy to use. Currently, working with CPython’s

argument parsing library is a chore, requiring maintaining

redundant information in a surprising number of places.

When you use Argument Clinic, you don’t have to repeat yourself.

Obviously, no one would want to use Argument Clinic unless

it’s solving their problem—and without creating new problems of

its own.

So it’s paramount that Argument Clinic generate correct code.

It’d be nice if the code was faster, too, but at the very least

it should not introduce a major speed regression. (Eventually Argument

Clinic should make a major speedup possible—we could

rewrite its code generator to produce tailor-made argument

parsing code, rather than calling the general-purpose CPython

argument parsing library. That would make for the fastest

argument parsing possible!)

Additionally, Argument Clinic must be flexible enough to

work with any approach to argument parsing. Python has

some functions with some very strange parsing behaviors;

Argument Clinic’s goal is to support all of them.

Finally, the original motivation for Argument Clinic was

to provide introspection 「signatures」 for CPython builtins.

It used to be, the introspection query functions would throw

an exception if you passed in a builtin. With Argument

Clinic, that’s a thing of the past!

One idea you should keep in mind, as you work with

Argument Clinic: the more information you give it, the

better job it’ll be able to do.

Argument Clinic is admittedly relatively simple right

now. But as it evolves it will get more sophisticated,

and it should be able to do many interesting and smart

things with all the information you give it.

</div>

<h2>Basic Concepts And Usage<a class="headerlink" href="#basic-concepts-and-usage" title="本標題的永久連結">¶</a></h2>

Argument Clinic ships with CPython; you’ll find it in <code class="docutils literal notranslate">Tools/clinic/clinic.py</code>.

If you run that script, specifying a C file as an argument:

<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python3 Tools/clinic/clinic.py foo.c

</pre></div>

</div>

Argument Clinic will scan over the file looking for lines that

look exactly like this:

<div class="highlight-none notranslate"><div class="highlight"><pre>/*[clinic input]

</pre></div>

</div>

When it finds one, it reads everything up to a line that looks

exactly like this:

<div class="highlight-none notranslate"><div class="highlight"><pre>[clinic start generated code]*/

</pre></div>

</div>

Everything in between these two lines is input for Argument Clinic.

All of these lines, including the beginning and ending comment

lines, are collectively called an Argument Clinic 「block」.

When Argument Clinic parses one of these blocks, it

generates output. This output is rewritten into the C file

immediately after the block, followed by a comment containing a checksum.

The Argument Clinic block now looks like this:

<div class="highlight-none notranslate"><div class="highlight"><pre>/*[clinic input]

... clinic input goes here ...

[clinic start generated code]*/

... clinic output goes here ...

/*[clinic end generated code: checksum=...]*/

</pre></div>

</div>

If you run Argument Clinic on the same file a second time, Argument Clinic

will discard the old output and write out the new output with a fresh checksum

line. However, if the input hasn’t changed, the output won’t change either.

You should never modify the output portion of an Argument Clinic block. Instead,

change the input until it produces the output you want. (That’s the purpose of the

checksum—to detect if someone changed the output, as these edits would be lost

the next time Argument Clinic writes out fresh output.)

For the sake of clarity, here’s the terminology we’ll use with Argument Clinic:

<li>The first line of the comment (<code class="docutils literal notranslate">/*[clinic input]</code>) is the start line.</li>

<li>The last line of the initial comment (<code class="docutils literal notranslate">[clinic start generated code]*/</code>) is the end line.</li>

<li>The last line (<code class="docutils literal notranslate">/*[clinic end generated code: checksum=...]*/</code>) is the checksum line.</li>

<li>In between the start line and the end line is the input.</li>

<li>In between the end line and the checksum line is the output.</li>

<li>All the text collectively, from the start line to the checksum line inclusively,

is the block. (A block that hasn’t been successfully processed by Argument

Clinic yet doesn’t have output or a checksum line, but it’s still considered

a block.)</li>

</ul>

</div>

<h2>Converting Your First Function<a class="headerlink" href="#converting-your-first-function" title="本標題的永久連結">¶</a></h2>

The best way to get a sense of how Argument Clinic works is to

convert a function to work with it. Here, then, are the bare

minimum steps you’d need to follow to convert a function to

work with Argument Clinic. Note that for code you plan to

check in to CPython, you really should take the conversion farther,

using some of the advanced concepts you’ll see later on in

the document (like 「return converters」 and 「self converters」).

But we’ll keep it simple for this walkthrough so you can learn.

Let’s dive in!

<li>Make sure you’re working with a freshly updated checkout

of the CPython trunk.

</li>

<li>Find a Python builtin that calls either <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>

or <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a>, and hasn’t been converted

to work with Argument Clinic yet.

For my example I’m using <code class="docutils literal notranslate">_pickle.Pickler.dump()</code>.

</li>

<li>If the call to the <code class="docutils literal notranslate">PyArg_Parse</code> function uses any of the

following format units:

<div class="highlight-none notranslate"><div class="highlight"><pre>O&

es#

et#

</pre></div>

</div>

or if it has multiple calls to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>,

you should choose a different function. Argument Clinic does

support all of these scenarios. But these are advanced

topics—let’s do something simpler for your first function.

Also, if the function has multiple calls to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>

types for the same argument, or if the function uses something besides

PyArg_Parse functions to parse its arguments, it probably

isn’t suitable for conversion to Argument Clinic. Argument Clinic

doesn’t support generic functions or polymorphic parameters.

</li>

<li>Add the following boilerplate above the function, creating our block:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>Cut the docstring and paste it in between the <code class="docutils literal notranslate">[clinic]</code> lines,

removing all the junk that makes it a properly quoted C string.

When you’re done you should have just the text, based at the left

margin, with no line wider than 80 characters.

(Argument Clinic will preserve indents inside the docstring.)

If the old docstring had a first line that looked like a function

signature, throw that line away. (The docstring doesn’t need it

anymore—when you use <code class="docutils literal notranslate">help()</code> on your builtin in the future,

the first line will be built automatically based on the function’s

signature.)

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>If your docstring doesn’t have a 「summary」 line, Argument Clinic will

complain. So let’s make sure it has one. The 「summary」 line should

be a paragraph consisting of a single 80-column line

at the beginning of the docstring.

(Our example docstring consists solely of a summary line, so the sample

code doesn’t have to change for this step.)

</li>

<li>Above the docstring, enter the name of the function, followed

by a blank line. This should be the Python name of the function,

and should be the full dotted path

to the function—it should start with the name of the module,

include any sub-modules, and if the function is a method on

a class it should include the class name too.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

_pickle.Pickler.dump

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>If this is the first time that module or class has been used with Argument

Clinic in this C file,

you must declare the module and/or class. Proper Argument Clinic hygiene

prefers declaring these in a separate block somewhere near the

top of the C file, in the same way that include files and statics go at

the top. (In our sample code we’ll just show the two blocks next to

each other.)

The name of the class and module should be the same as the one

seen by Python. Check the name defined in the <a class="reference internal" href="../c-api/module.html#c.PyModuleDef" title="PyModuleDef"><code class="xref c c-type docutils literal notranslate">PyModuleDef</code></a>

or <a class="reference internal" href="../c-api/type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate">PyTypeObject</code></a> as appropriate.

When you declare a class, you must also specify two aspects of its type

in C: the type declaration you’d use for a pointer to an instance of

this class, and a pointer to the <a class="reference internal" href="../c-api/type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate">PyTypeObject</code></a> for this class.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

module _pickle

class _pickle.Pickler "PicklerObject *" "&Pickler_Type"

[clinic start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>Declare each of the parameters to the function. Each parameter

should get its own line. All the parameter lines should be

indented from the function name and the docstring.

The general form of these parameter lines is as follows:

<div class="highlight-none notranslate"><div class="highlight"><pre>name_of_parameter: converter

</pre></div>

</div>

If the parameter has a default value, add that after the

converter:

<div class="highlight-none notranslate"><div class="highlight"><pre>name_of_parameter: converter = default_value

</pre></div>

</div>

Argument Clinic’s support for 「default values」 is quite sophisticated;

please see <a class="reference internal" href="#default-values">the section below on default values</a>

for more information.

Add a blank line below the parameters.

What’s a 「converter」? It establishes both the type

of the variable used in C, and the method to convert the Python

value into a C value at runtime.

For now you’re going to use what’s called a 「legacy converter」—a

convenience syntax intended to make porting old code into Argument

Clinic easier.

For each parameter, copy the 「format unit」 for that

parameter from the <code class="docutils literal notranslate">PyArg_Parse()</code> format argument and

specify that as its converter, as a quoted

string. (「format unit」 is the formal name for the one-to-three

character substring of the <code class="docutils literal notranslate">format</code> parameter that tells

the argument parsing function what the type of the variable

is and how to convert it. For more on format units please

see <a class="reference internal" href="../c-api/arg.html#arg-parsing">Parsing arguments and building values</a>.)

For multicharacter format units like <code class="docutils literal notranslate">z#</code>, use the

entire two-or-three character string.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre> /*[clinic input]

module _pickle

class _pickle.Pickler "PicklerObject *" "&Pickler_Type"

[clinic start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

obj: 'O'

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>If your function has <code class="docutils literal notranslate">|</code> in the format string, meaning some

parameters have default values, you can ignore it. Argument

Clinic infers which parameters are optional based on whether

or not they have default values.

If your function has <code class="docutils literal notranslate">$</code> in the format string, meaning it

takes keyword-only arguments, specify <code class="docutils literal notranslate">*</code> on a line by

itself before the first keyword-only argument, indented the

same as the parameter lines.

(<code class="docutils literal notranslate">_pickle.Pickler.dump</code> has neither, so our sample is unchanged.)

</li>

<li>If the existing C function calls <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>

(as opposed to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a>), then all its

arguments are positional-only.

To mark all parameters as positional-only in Argument Clinic,

add a <code class="docutils literal notranslate">/</code> on a line by itself after the last parameter,

indented the same as the parameter lines.

Currently this is all-or-nothing; either all parameters are

positional-only, or none of them are. (In the future Argument

Clinic may relax this restriction.)

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

module _pickle

class _pickle.Pickler "PicklerObject *" "&Pickler_Type"

[clinic start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

obj: 'O'

/

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>It’s helpful to write a per-parameter docstring for each parameter.

But per-parameter docstrings are optional; you can skip this step

if you prefer.

Here’s how to add a per-parameter docstring. The first line

of the per-parameter docstring must be indented further than the

parameter definition. The left margin of this first line establishes

the left margin for the whole per-parameter docstring; all the text

you write will be outdented by this amount. You can write as much

text as you like, across multiple lines if you wish.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

module _pickle

class _pickle.Pickler "PicklerObject *" "&Pickler_Type"

[clinic start generated code]*/

/*[clinic input]

_pickle.Pickler.dump

obj: 'O'

The object to be pickled.

/

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

</li>

<li>Save and close the file, then run <code class="docutils literal notranslate">Tools/clinic/clinic.py</code> on

it. With luck everything worked—your block now has output, and

a <code class="docutils literal notranslate">.c.h</code> file has been generated! Reopen the file in your

text editor to see:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

_pickle.Pickler.dump

obj: 'O'

The object to be pickled.

/

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

static PyObject *

_pickle_Pickler_dump(PicklerObject *self, PyObject *obj)

/*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/

</pre></div>

</div>

Obviously, if Argument Clinic didn’t produce any output, it’s because

it found an error in your input. Keep fixing your errors and retrying

until Argument Clinic processes your file without complaint.

For readability, most of the glue code has been generated to a <code class="docutils literal notranslate">.c.h</code>

file. You’ll need to include that in your original <code class="docutils literal notranslate">.c</code> file,

typically right after the clinic module block:

<div class="highlight-c notranslate"><div class="highlight"><pre>#include "clinic/_pickle.c.h"

</pre></div>

</div>

</li>

<li>Double-check that the argument-parsing code Argument Clinic generated

looks basically the same as the existing code.

First, ensure both places use the same argument-parsing function.

The existing code must call either

<a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a> or <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a>;

ensure that the code generated by Argument Clinic calls the

exact same function.

Second, the format string passed in to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a> or

<a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a> should be exactly the same

as the hand-written one in the existing function, up to the colon

or semi-colon.

(Argument Clinic always generates its format strings

with a <code class="docutils literal notranslate">:</code> followed by the name of the function. If the

existing code’s format string ends with <code class="docutils literal notranslate">;</code>, to provide

usage help, this change is harmless—don’t worry about it.)

Third, for parameters whose format units require two arguments

(like a length variable, or an encoding string, or a pointer

to a conversion function), ensure that the second argument is

exactly the same between the two invocations.

Fourth, inside the output portion of the block you’ll find a preprocessor

macro defining the appropriate static <a class="reference internal" href="../c-api/structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> structure for

this builtin:

<div class="highlight-c notranslate"><div class="highlight"><pre>#define __PICKLE_PICKLER_DUMP_METHODDEF \

{"dump", (PyCFunction)__pickle_Pickler_dump, METH_O, __pickle_Pickler_dump__doc__},

</pre></div>

</div>

This static structure should be exactly the same as the existing static

<a class="reference internal" href="../c-api/structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> structure for this builtin.

If any of these items differ in any way,

adjust your Argument Clinic function specification and rerun

<code class="docutils literal notranslate">Tools/clinic/clinic.py</code> until they are the same.

</li>

<li>Notice that the last line of its output is the declaration

of your 「impl」 function. This is where the builtin’s implementation goes.

Delete the existing prototype of the function you’re modifying, but leave

the opening curly brace. Now delete its argument parsing code and the

declarations of all the variables it dumps the arguments into.

Notice how the Python arguments are now arguments to this impl function;

if the implementation used different names for these variables, fix it.

Let’s reiterate, just because it’s kind of weird. Your code should now

look like this:

<div class="highlight-c notranslate"><div class="highlight"><pre>static return_type

your_function_impl(...)

/*[clinic end generated code: checksum=...]*/

{

...

</pre></div>

</div>

Argument Clinic generated the checksum line and the function prototype just

above it. You should write the opening (and closing) curly braces for the

function, and the implementation inside.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

module _pickle

class _pickle.Pickler "PicklerObject *" "&Pickler_Type"

[clinic start generated code]*/

/*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/

/*[clinic input]

_pickle.Pickler.dump

obj: 'O'

The object to be pickled.

/

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

PyDoc_STRVAR(__pickle_Pickler_dump__doc__,

"Write a pickled representation of obj to the open file.\n"

"\n"

...

static PyObject *

_pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)

/*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/

{

/* Check whether the Pickler was initialized correctly (issue3664).

Developers often forget to call __init__() in their subclasses, which

would trigger a segfault without this check. */

if (self->write == NULL) {

PyErr_Format(PicklingError,

"Pickler.__init__() was not called by %s.__init__()",

Py_TYPE(self)->tp_name);

return NULL;

}

if (_Pickler_ClearBuffer(self) < 0)

return NULL;

...

</pre></div>

</div>

</li>

<li>Remember the macro with the <a class="reference internal" href="../c-api/structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> structure for this

function? Find the existing <a class="reference internal" href="../c-api/structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> structure for this

function and replace it with a reference to the macro. (If the builtin

is at module scope, this will probably be very near the end of the file;

if the builtin is a class method, this will probably be below but relatively

near to the implementation.)

Note that the body of the macro contains a trailing comma. So when you

replace the existing static <a class="reference internal" href="../c-api/structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate">PyMethodDef</code></a> structure with the macro,

don’t add a comma to the end.

Sample:

<div class="highlight-c notranslate"><div class="highlight"><pre>static struct PyMethodDef Pickler_methods[] = {

__PICKLE_PICKLER_DUMP_METHODDEF

__PICKLE_PICKLER_CLEAR_MEMO_METHODDEF

{NULL, NULL} /* sentinel */

};

</pre></div>

</div>

</li>

<li>Compile, then run the relevant portions of the regression-test suite.

This change should not introduce any new compile-time warnings or errors,

and there should be no externally-visible change to Python’s behavior.

Well, except for one difference: <code class="docutils literal notranslate">inspect.signature()</code> run on your function

should now provide a valid signature!

Congratulations, you’ve ported your first function to work with Argument Clinic!

</li>

</ol>

</div>

<h2>Advanced Topics<a class="headerlink" href="#advanced-topics" title="本標題的永久連結">¶</a></h2>

Now that you’ve had some experience working with Argument Clinic, it’s time

for some advanced topics.

<h3>Symbolic default values<a class="headerlink" href="#symbolic-default-values" title="本標題的永久連結">¶</a></h3>

The default value you provide for a parameter can’t be any arbitrary

expression. Currently the following are explicitly supported:

<li>Numeric constants (integer and float)</li>

<li>String constants</li>

<li><code class="docutils literal notranslate">True</code>, <code class="docutils literal notranslate">False</code>, and <code class="docutils literal notranslate">None</code></li>

<li>Simple symbolic constants like <code class="docutils literal notranslate">sys.maxsize</code>, which must

start with the name of the module</li>

</ul>

In case you’re curious, this is implemented in <code class="docutils literal notranslate">from_builtin()</code>

in <code class="docutils literal notranslate">Lib/inspect.py</code>.

(In the future, this may need to get even more elaborate,

to allow full expressions like <code class="docutils literal notranslate">CONSTANT - 1</code>.)

</div>

<h3>Renaming the C functions and variables generated by Argument Clinic<a class="headerlink" href="#renaming-the-c-functions-and-variables-generated-by-argument-clinic" title="本標題的永久連結">¶</a></h3>

Argument Clinic automatically names the functions it generates for you.

Occasionally this may cause a problem, if the generated name collides with

the name of an existing C function. There’s an easy solution: override the names

used for the C functions. Just add the keyword <code class="docutils literal notranslate">"as"</code>

to your function declaration line, followed by the function name you wish to use.

Argument Clinic will use that function name for the base (generated) function,

then add <code class="docutils literal notranslate">"_impl"</code> to the end and use that for the name of the impl function.

For example, if we wanted to rename the C function names generated for

<code class="docutils literal notranslate">pickle.Pickler.dump</code>, it’d look like this:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

pickle.Pickler.dump as pickler_dumper

...

</pre></div>

</div>

The base function would now be named <code class="docutils literal notranslate">pickler_dumper()</code>,

and the impl function would now be named <code class="docutils literal notranslate">pickler_dumper_impl()</code>.

Similarly, you may have a problem where you want to give a parameter

a specific Python name, but that name may be inconvenient in C. Argument

Clinic allows you to give a parameter different names in Python and in C,

using the same <code class="docutils literal notranslate">"as"</code> syntax:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

pickle.Pickler.dump

obj: object

file as file_obj: object

protocol: object = NULL

*

fix_imports: bool = True

</pre></div>

</div>

Here, the name used in Python (in the signature and the <code class="docutils literal notranslate">keywords</code>

array) would be <code class="docutils literal notranslate">file</code>, but the C variable would be named <code class="docutils literal notranslate">file_obj</code>.

You can use this to rename the <code class="docutils literal notranslate">self</code> parameter too!

</div>

<h3>Converting functions using PyArg_UnpackTuple<a class="headerlink" href="#converting-functions-using-pyarg-unpacktuple" title="本標題的永久連結">¶</a></h3>

To convert a function parsing its arguments with <a class="reference internal" href="../c-api/arg.html#c.PyArg_UnpackTuple" title="PyArg_UnpackTuple"><code class="xref c c-func docutils literal notranslate">PyArg_UnpackTuple()</code></a>,

simply write out all the arguments, specifying each as an <code class="docutils literal notranslate">object</code>. You

may specify the <code class="docutils literal notranslate">type</code> argument to cast the type as appropriate. All

arguments should be marked positional-only (add a <code class="docutils literal notranslate">/</code> on a line by itself

after the last argument).

Currently the generated code will use <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>, but this

will change soon.

</div>

<h3>Optional Groups<a class="headerlink" href="#optional-groups" title="本標題的永久連結">¶</a></h3>

Some legacy functions have a tricky approach to parsing their arguments:

they count the number of positional arguments, then use a <code class="docutils literal notranslate">switch</code> statement

to call one of several different <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a> calls depending on

how many positional arguments there are. (These functions cannot accept

keyword-only arguments.) This approach was used to simulate optional

arguments back before <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a> was created.

While functions using this approach can often be converted to

use <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a>, optional arguments, and default values,

it’s not always possible. Some of these legacy functions have

behaviors <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTupleAndKeywords()</code></a> doesn’t directly support.

The most obvious example is the builtin function <code class="docutils literal notranslate">range()</code>, which has

an optional argument on the left side of its required argument!

Another example is <code class="docutils literal notranslate">curses.window.addch()</code>, which has a group of two

arguments that must always be specified together. (The arguments are

called <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code>; if you call the function passing in <code class="docutils literal notranslate">x</code>,

you must also pass in <code class="docutils literal notranslate">y</code>—and if you don’t pass in <code class="docutils literal notranslate">x</code> you may not

pass in <code class="docutils literal notranslate">y</code> either.)

In any case, the goal of Argument Clinic is to support argument parsing

for all existing CPython builtins without changing their semantics.

Therefore Argument Clinic supports

this alternate approach to parsing, using what are called optional groups.

Optional groups are groups of arguments that must all be passed in together.

They can be to the left or the right of the required arguments. They

can only be used with positional-only parameters.

備註

Optional groups are only intended for use when converting

functions that make multiple calls to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>!

Functions that use any other approach for parsing arguments

should almost never be converted to Argument Clinic using

optional groups. Functions using optional groups currently

cannot have accurate signatures in Python, because Python just

doesn’t understand the concept. Please avoid using optional

groups wherever possible.

</div>

To specify an optional group, add a <code class="docutils literal notranslate">[</code> on a line by itself before

the parameters you wish to group together, and a <code class="docutils literal notranslate">]</code> on a line by itself

after these parameters. As an example, here’s how <code class="docutils literal notranslate">curses.window.addch</code>

uses optional groups to make the first two parameters and the last

parameter optional:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

curses.window.addch

[

x: int

X-coordinate.

y: int

Y-coordinate.

]

ch: object

Character to add.

[

attr: long

Attributes for the character.

]

/

...

</pre></div>

</div>

註解：

<li>For every optional group, one additional parameter will be passed into the

impl function representing the group. The parameter will be an int named

<code class="docutils literal notranslate">group_{direction}_{number}</code>,

where <code class="docutils literal notranslate">{direction}</code> is either <code class="docutils literal notranslate">right</code> or <code class="docutils literal notranslate">left</code> depending on whether the group

is before or after the required parameters, and <code class="docutils literal notranslate">{number}</code> is a monotonically

increasing number (starting at 1) indicating how far away the group is from

the required parameters. When the impl is called, this parameter will be set

to zero if this group was unused, and set to non-zero if this group was used.

(By used or unused, I mean whether or not the parameters received arguments

in this invocation.)</li>

<li>If there are no required arguments, the optional groups will behave

as if they’re to the right of the required arguments.</li>

<li>In the case of ambiguity, the argument parsing code

favors parameters on the left (before the required parameters).</li>

<li>Optional groups can only contain positional-only parameters.</li>

<li>Optional groups are only intended for legacy code. Please do not

use optional groups for new code.</li>

</ul>

</div>

<h3>Using real Argument Clinic converters, instead of 「legacy converters」<a class="headerlink" href="#using-real-argument-clinic-converters-instead-of-legacy-converters" title="本標題的永久連結">¶</a></h3>

To save time, and to minimize how much you need to learn

to achieve your first port to Argument Clinic, the walkthrough above tells

you to use 「legacy converters」. 「Legacy converters」 are a convenience,

designed explicitly to make porting existing code to Argument Clinic

easier. And to be clear, their use is acceptable when porting code for

Python 3.4.

However, in the long term we probably want all our blocks to

use Argument Clinic’s real syntax for converters. Why? A couple

reasons:

<li>The proper converters are far easier to read and clearer in their intent.</li>

<li>There are some format units that are unsupported as 「legacy converters」,

because they require arguments, and the legacy converter syntax doesn’t

support specifying arguments.</li>

<li>In the future we may have a new argument parsing library that isn’t

restricted to what <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a> supports; this flexibility

won’t be available to parameters using legacy converters.</li>

</ul>

Therefore, if you don’t mind a little extra effort, please use the normal

converters instead of legacy converters.

In a nutshell, the syntax for Argument Clinic (non-legacy) converters

looks like a Python function call. However, if there are no explicit

arguments to the function (all functions take their default values),

you may omit the parentheses. Thus <code class="docutils literal notranslate">bool</code> and <code class="docutils literal notranslate">bool()</code> are exactly

the same converters.

All arguments to Argument Clinic converters are keyword-only.

All Argument Clinic converters accept the following arguments:

<dt><code class="docutils literal notranslate">c_default</code></dt>

<dd>The default value for this parameter when defined in C.

Specifically, this will be the initializer for the variable declared

in the 「parse function」. See <a class="reference internal" href="#default-values">the section on default values</a>

for how to use this.

Specified as a string.</dd>

<dt><code class="docutils literal notranslate">annotation</code></dt>

<dd>The annotation value for this parameter. Not currently supported,

because PEP 8 mandates that the Python library may not use

annotations.</dd>

</dl>

</div></blockquote>

In addition, some converters accept additional arguments. Here is a list

of these arguments, along with their meanings:

<dt><code class="docutils literal notranslate">accept</code></dt>

<dd>A set of Python types (and possibly pseudo-types);

this restricts the allowable Python argument to values of these types.

(This is not a general-purpose facility; as a rule it only supports

specific lists of types as shown in the legacy converter table.)

To accept <code class="docutils literal notranslate">None</code>, add <code class="docutils literal notranslate">NoneType</code> to this set.

</dd>

<dt><code class="docutils literal notranslate">bitwise</code></dt>

<dd>Only supported for unsigned integers. The native integer value of this

Python argument will be written to the parameter without any range checking,

even for negative values.</dd>

<dt><code class="docutils literal notranslate">converter</code></dt>

<dd>Only supported by the <code class="docutils literal notranslate">object</code> converter. Specifies the name of a

<a class="reference internal" href="../c-api/arg.html#o-ampersand">C 「converter function」</a>

to use to convert this object to a native type.</dd>

<dt><code class="docutils literal notranslate">encoding</code></dt>

<dd>Only supported for strings. Specifies the encoding to use when converting

this string from a Python str (Unicode) value into a C <code class="docutils literal notranslate">char *</code> value.</dd>

<dt><code class="docutils literal notranslate">subclass_of</code></dt>

<dd>Only supported for the <code class="docutils literal notranslate">object</code> converter. Requires that the Python

value be a subclass of a Python type, as expressed in C.</dd>

<dd>Only supported for the <code class="docutils literal notranslate">object</code> and <code class="docutils literal notranslate">self</code> converters. Specifies

the C type that will be used to declare the variable. Default value is

<code class="docutils literal notranslate">"PyObject *"</code>.</dd>

<dt><code class="docutils literal notranslate">zeroes</code></dt>

<dd>Only supported for strings. If true, embedded NUL bytes (<code class="docutils literal notranslate">'\\0'</code>) are

permitted inside the value. The length of the string will be passed in

to the impl function, just after the string parameter, as a parameter named

<code class="docutils literal notranslate"><parameter_name>_length</code>.</dd>

</dl>

</div></blockquote>

Please note, not every possible combination of arguments will work.

Usually these arguments are implemented by specific <code class="docutils literal notranslate">PyArg_ParseTuple</code>

format units, with specific behavior. For example, currently you cannot

call <code class="docutils literal notranslate">unsigned_short</code> without also specifying <code class="docutils literal notranslate">bitwise=True</code>.

Although it’s perfectly reasonable to think this would work, these semantics don’t

map to any existing format unit. So Argument Clinic doesn’t support it. (Or, at

least, not yet.)

Below is a table showing the mapping of legacy converters into real

Argument Clinic converters. On the left is the legacy converter,

on the right is the text you’d replace it with.

</colgroup>

<td><code class="docutils literal notranslate">unsigned_char(bitwise=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">unsigned_char</code></td>

</tr>

</tr>

<td><code class="docutils literal notranslate">int(accept={str})</code></td>

</tr>

<td><code class="docutils literal notranslate">double</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_complex</code></td>

</tr>

<td><code class="docutils literal notranslate">str(encoding='name_of_encoding')</code></td>

</tr>

<td><code class="docutils literal notranslate">str(encoding='name_of_encoding', zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">str(encoding='name_of_encoding', accept={bytes, bytearray, str})</code></td>

</tr>

</tr>

<td><code class="docutils literal notranslate">float</code></td>

</tr>

<td><code class="docutils literal notranslate">short</code></td>

</tr>

<td><code class="docutils literal notranslate">unsigned_short(bitwise=True)</code></td>

</tr>

</tr>

<td><code class="docutils literal notranslate">unsigned_int(bitwise=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">unsigned_long(bitwise=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">unsigned_long_long(bitwise=True)</code></td>

</tr>

</tr>

</tr>

<td><code class="docutils literal notranslate">Py_ssize_t</code></td>

</tr>

<td><code class="docutils literal notranslate">object</code></td>

</tr>

<td><code class="docutils literal notranslate">object(subclass_of='&PySomething_Type')</code></td>

</tr>

<td><code class="docutils literal notranslate">object(converter='name_of_c_function')</code></td>

</tr>

</tr>

<td><code class="docutils literal notranslate">PyBytesObject</code></td>

</tr>

</tr>

<td><code class="docutils literal notranslate">str(zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_buffer(accept={buffer, str})</code></td>

</tr>

<td><code class="docutils literal notranslate">unicode</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_UNICODE</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_UNICODE(zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_buffer(accept={rwbuffer})</code></td>

</tr>

<td><code class="docutils literal notranslate">PyByteArrayObject</code></td>

</tr>

<td><code class="docutils literal notranslate">str(accept={bytes})</code></td>

</tr>

<td><code class="docutils literal notranslate">str(accept={robuffer}, zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_buffer</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_UNICODE(accept={str, NoneType})</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_UNICODE(accept={str, NoneType}, zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">str(accept={str, NoneType})</code></td>

</tr>

<td><code class="docutils literal notranslate">str(accept={str, NoneType}, zeroes=True)</code></td>

</tr>

<td><code class="docutils literal notranslate">Py_buffer(accept={buffer, str, NoneType})</code></td>

</tr>

</tbody>

</table>

As an example, here’s our sample <code class="docutils literal notranslate">pickle.Pickler.dump</code> using the proper

converter:

<div class="highlight-c notranslate"><div class="highlight"><pre>/*[clinic input]

pickle.Pickler.dump

obj: object

The object to be pickled.

/

Write a pickled representation of obj to the open file.

[clinic start generated code]*/

</pre></div>

</div>

Argument Clinic will show you all the converters it has

available. For each converter it’ll show you all the parameters

it accepts, along with the default value for each parameter.

Just run <code class="docutils literal notranslate">Tools/clinic/clinic.py --converters</code> to see the full list.

</div>

<h3>Py_buffer<a class="headerlink" href="#py-buffer" title="本標題的永久連結">¶</a></h3>

When using the <code class="docutils literal notranslate">Py_buffer</code> converter

(or the <code class="docutils literal notranslate">'s*'</code>, <code class="docutils literal notranslate">'w*'</code>, <code class="docutils literal notranslate">'*y'</code>, or <code class="docutils literal notranslate">'z*'</code> legacy converters),

you must not call <a class="reference internal" href="../c-api/buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal notranslate">PyBuffer_Release()</code></a> on the provided buffer.

Argument Clinic generates code that does it for you (in the parsing function).

</div>

<h3>Advanced converters<a class="headerlink" href="#advanced-converters" title="本標題的永久連結">¶</a></h3>

Remember those format units you skipped for your first

time because they were advanced? Here’s how to handle those too.

The trick is, all those format units take arguments—either

conversion functions, or types, or strings specifying an encoding.

(But 「legacy converters」 don’t support arguments. That’s why we

skipped them for your first function.) The argument you specified

to the format unit is now an argument to the converter; this

argument is either <code class="docutils literal notranslate">converter</code> (for <code class="docutils literal notranslate">O&</code>), <code class="docutils literal notranslate">subclass_of</code> (for <code class="docutils literal notranslate">O!</code>),

or <code class="docutils literal notranslate">encoding</code> (for all the format units that start with <code class="docutils literal notranslate">e</code>).

When using <code class="docutils literal notranslate">subclass_of</code>, you may also want to use the other

custom argument for <code class="docutils literal notranslate">object()</code>: <code class="docutils literal notranslate">type</code>, which lets you set the type

actually used for the parameter. For example, if you want to ensure

that the object is a subclass of <code class="docutils literal notranslate">PyUnicode_Type</code>, you probably want

to use the converter <code class="docutils literal notranslate">object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')</code>.

One possible problem with using Argument Clinic: it takes away some possible

flexibility for the format units starting with <code class="docutils literal notranslate">e</code>. When writing a

<code class="docutils literal notranslate">PyArg_Parse</code> call by hand, you could theoretically decide at runtime what

encoding string to pass in to <a class="reference internal" href="../c-api/arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate">PyArg_ParseTuple()</code></a>. But now this string must

be hard-coded at Argument-Clinic-preprocessing-time. This limitation is deliberate;

it made supporting this format unit much easier, and may allow for future optimizations.

This restriction doesn’t seem unreasonable; CPython itself always passes in static

View remainder of file in raw view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

clinic.html

Latest commit

History

clinic.html

File metadata and controls