python-docs-fa/extending/extending.html at gh-pages · python/python-docs-fa

History

1655 lines (1562 loc) · 171 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>1. Extending Python with C or C++ — مستندات 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="#">1. Extending Python with C or C++</a><ul>

<li><a class="reference internal" href="#a-simple-example">1.1. A Simple Example</a></li>

<li><a class="reference internal" href="#intermezzo-errors-and-exceptions">1.2. Intermezzo: Errors and Exceptions</a></li>

<li><a class="reference internal" href="#back-to-the-example">1.3. Back to the Example</a></li>

<li><a class="reference internal" href="#the-module-s-method-table-and-initialization-function">1.4. The Module's Method Table and Initialization Function</a></li>

<li><a class="reference internal" href="#compilation-and-linkage">1.5. Compilation and Linkage</a></li>

<li><a class="reference internal" href="#calling-python-functions-from-c">1.6. Calling Python Functions from C</a></li>

<li><a class="reference internal" href="#extracting-parameters-in-extension-functions">1.7. Extracting Parameters in Extension Functions</a></li>

<li><a class="reference internal" href="#keyword-parameters-for-extension-functions">1.8. Keyword Parameters for Extension Functions</a></li>

<li><a class="reference internal" href="#building-arbitrary-values">1.9. Building Arbitrary Values</a></li>

<li><a class="reference internal" href="#reference-counts">1.10. Reference Counts</a><ul>

<li><a class="reference internal" href="#reference-counting-in-python">1.10.1. Reference Counting in Python</a></li>

<li><a class="reference internal" href="#ownership-rules">1.10.2. Ownership Rules</a></li>

<li><a class="reference internal" href="#null-pointers">1.10.4. NULL Pointers</a></li>

</ul>

</li>

<li><a class="reference internal" href="#writing-extensions-in-c">1.11. Writing Extensions in C++</a></li>

<li><a class="reference internal" href="#providing-a-c-api-for-an-extension-module">1.12. Providing a C API for an Extension Module</a></li>

</ul>

</li>

</ul>

</div>

<div>

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

<a href="index.html"

title="فصل قبلی">Extending and Embedding the Python Interpreter</a>

</div>

<div>

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

<a href="newtypes_tutorial.html"

title="فصل بعدی">2. Defining Extension Types: Tutorial</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', "extending/extending.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/extending/extending.rst?plain=1"

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

</a>

</li>

<li>

<a href="https://github.com/python/python-docs-fa/blob/3.14/extending/extending.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="newtypes_tutorial.html" title="2. Defining Extension Types: Tutorial"

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

<a href="index.html" title="Extending and Embedding the Python Interpreter"

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="index.html" accesskey="U">Extending and Embedding the Python Interpreter</a> »</li>

<li class="nav-item nav-item-this"><a href="">1. Extending Python with C or C++</a></li>

</form>

</div>

</li>

Theme

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

</select>

</label> |</li>

</ul>

</div>

<h1>1. Extending Python with C or C++<a class="headerlink" href="#extending-python-with-c-or-c" title="Link to this heading">¶</a></h1>

It is quite easy to add new built-in modules to Python, if you know how to

program in C. Such extension modules can do two things that can't be

done directly in Python: they can implement new built-in object types, and they

can call C library functions and system calls.

To support extensions, the Python API (Application Programmers Interface)

defines a set of functions, macros and variables that provide access to most

aspects of the Python run-time system. The Python API is incorporated in a C

source file by including the header <code class="docutils literal notranslate">"Python.h"</code>.

The compilation of an extension module depends on its intended use as well as on

your system setup; details are given in later chapters.

توجه

The C extension interface is specific to CPython, and extension modules do

not work on other Python implementations. In many cases, it is possible to

avoid writing C extensions and preserve portability to other implementations.

For example, if your use case is calling C library functions or system calls,

you should consider using the <a class="reference internal" href="../library/ctypes.html#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> module or the <a class="reference external" href="https://cffi.readthedocs.io/">cffi</a> library rather than writing

custom C code.

These modules let you write Python code to interface with C code and are more

portable between implementations of Python than writing and compiling a C

extension module.

</div>

<h2>1.1. A Simple Example<a class="headerlink" href="#a-simple-example" title="Link to this heading">¶</a></h2>

Let's create an extension module called <code class="docutils literal notranslate">spam</code> (the favorite food of Monty

Python fans...) and let's say we want to create a Python interface to the C

library function <code class="xref c c-func docutils literal notranslate">system()</code> <a class="footnote-reference brackets" href="#id5" id="id1" role="doc-noteref">[1]</a>. This function takes a null-terminated

character string as argument and returns an integer. We want this function to

be callable from Python as follows:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> import spam

>>> status = spam.system("ls -l")

</pre></div>

</div>

Begin by creating a file <code class="file docutils literal notranslate">spammodule.c</code>. (Historically, if a module is

called <code class="docutils literal notranslate">spam</code>, the C file containing its implementation is called

<code class="file docutils literal notranslate">spammodule.c</code>; if the module name is very long, like <code class="docutils literal notranslate">spammify</code>, the

module name can be just <code class="file docutils literal notranslate">spammify.c</code>.)

The first two lines of our file can be:

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

#include <Python.h>

</pre></div>

</div>

which pulls in the Python API (you can add a comment describing the purpose of

the module and a copyright notice if you like).

توجه

Since Python may define some pre-processor definitions which affect the standard

headers on some systems, you must include <code class="file docutils literal notranslate">Python.h</code> before any standard

headers are included.

<code class="docutils literal notranslate">#define PY_SSIZE_T_CLEAN</code> was used to indicate that <code class="docutils literal notranslate">Py_ssize_t</code> should be

used in some APIs instead of <code class="docutils literal notranslate">int</code>.

It is not necessary since Python 3.13, but we keep it here for backward compatibility.

See <a class="reference internal" href="../c-api/arg.html#arg-parsing-string-and-buffers">Strings and buffers</a> for a description of this macro.

</div>

All user-visible symbols defined by <code class="file docutils literal notranslate">Python.h</code> have a prefix of <code class="docutils literal notranslate">Py</code> or

<code class="docutils literal notranslate">PY</code>, except those defined in standard header files.

نکته

For backward compatibility, <code class="file docutils literal notranslate">Python.h</code> includes several standard header files.

C extensions should include the standard headers that they use,

and should not rely on these implicit includes.

If using the limited C API version 3.13 or newer, the implicit includes are:

<li><code class="docutils literal notranslate"><intrin.h></code> (on Windows)</li>

<li><code class="docutils literal notranslate"><sys/types.h></code> (if present)</li>

</ul>

If <a class="reference internal" href="../c-api/stable.html#c.Py_LIMITED_API" title="Py_LIMITED_API"><code class="xref c c-macro docutils literal notranslate">Py_LIMITED_API</code></a> is not defined, or is set to version 3.12 or older,

the headers below are also included:

<li><code class="docutils literal notranslate"><unistd.h></code> (on POSIX)</li>

</ul>

the headers below are also included:

</ul>

</div>

The next thing we add to our module file is the C function that will be called

when the Python expression <code class="docutils literal notranslate">spam.system(string)</code> is evaluated (we'll see

shortly how it ends up being called):

spam_system(PyObject *self, PyObject *args)

{

int sts;

if (!PyArg_ParseTuple(args, "s", &command))

return NULL;

sts = system(command);

return PyLong_FromLong(sts);

}

</pre></div>

</div>

There is a straightforward translation from the argument list in Python (for

example, the single expression <code class="docutils literal notranslate">"ls -l"</code>) to the arguments passed to the C

function. The C function always has two arguments, conventionally named self

and args.

The self argument points to the module object for module-level functions;

for a method it would point to the object instance.

The args argument will be a pointer to a Python tuple object containing the

arguments. Each item of the tuple corresponds to an argument in the call's

argument list. The arguments are Python objects --- in order to do anything

with them in our C function we have to convert them to C values. The function

<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> in the Python API checks the argument types and

converts them to C values. It uses a template string to determine the required

types of the arguments as well as the types of the C variables into which to

store the converted values. More about this later.

<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> returns true (nonzero) if all arguments have the right

type and its components have been stored in the variables whose addresses are

passed. It returns false (zero) if an invalid argument list was passed. In the

latter case it also raises an appropriate exception so the calling function can

return <code class="docutils literal notranslate">NULL</code> immediately (as we saw in the example).

</section>

<h2>1.2. Intermezzo: Errors and Exceptions<a class="headerlink" href="#intermezzo-errors-and-exceptions" title="Link to this heading">¶</a></h2>

An important convention throughout the Python interpreter is the following: when

a function fails, it should set an exception condition and return an error value

(usually <code class="docutils literal notranslate">-1</code> or a <code class="docutils literal notranslate">NULL</code> pointer). Exception information is stored in

three members of the interpreter's thread state. These are <code class="docutils literal notranslate">NULL</code> if

there is no exception. Otherwise they are the C equivalents of the members

of the Python tuple returned by <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-meth docutils literal notranslate">sys.exc_info()</code></a>. These are the

exception type, exception instance, and a traceback object. It is important

to know about them to understand how errors are passed around.

The Python API defines a number of functions to set various types of exceptions.

The most common one is <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_SetString" title="PyErr_SetString"><code class="xref c c-func docutils literal notranslate">PyErr_SetString()</code></a>. Its arguments are an exception

object and a C string. The exception object is usually a predefined object like

<a class="reference internal" href="../c-api/exceptions.html#c.PyExc_ZeroDivisionError" title="PyExc_ZeroDivisionError"><code class="xref c c-data docutils literal notranslate">PyExc_ZeroDivisionError</code></a>. The C string indicates the cause of the error

and is converted to a Python string object and stored as the "associated value"

of the exception.

Another useful function is <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_SetFromErrno" title="PyErr_SetFromErrno"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromErrno()</code></a>, which only takes an

exception argument and constructs the associated value by inspection of the

global variable <code class="xref c c-data docutils literal notranslate">errno</code>. The most general function is

<a class="reference internal" href="../c-api/exceptions.html#c.PyErr_SetObject" title="PyErr_SetObject"><code class="xref c c-func docutils literal notranslate">PyErr_SetObject()</code></a>, which takes two object arguments, the exception and

its associated value. You don't need to <a class="reference internal" href="../c-api/refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate">Py_INCREF()</code></a> the objects passed

to any of these functions.

You can test non-destructively whether an exception has been set with

<a class="reference internal" href="../c-api/exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate">PyErr_Occurred()</code></a>. This returns the current exception object, or <code class="docutils literal notranslate">NULL</code>

if no exception has occurred. You normally don't need to call

<code class="xref c c-func docutils literal notranslate">PyErr_Occurred()</code> to see whether an error occurred in a function call,

since you should be able to tell from the return value.

When a function f that calls another function g detects that the latter

fails, f should itself return an error value (usually <code class="docutils literal notranslate">NULL</code> or <code class="docutils literal notranslate">-1</code>). It

should not call one of the <code class="docutils literal notranslate">PyErr_*</code> functions --- one has already

been called by g. f's caller is then supposed to also return an error

indication to its caller, again without calling <code class="docutils literal notranslate">PyErr_*</code>, and so on

--- the most detailed cause of the error was already reported by the function

that first detected it. Once the error reaches the Python interpreter's main

loop, this aborts the currently executing Python code and tries to find an

exception handler specified by the Python programmer.

(There are situations where a module can actually give a more detailed error

message by calling another <code class="docutils literal notranslate">PyErr_*</code> function, and in such cases it is

fine to do so. As a general rule, however, this is not necessary, and can cause

information about the cause of the error to be lost: most operations can fail

for a variety of reasons.)

To ignore an exception set by a function call that failed, the exception

condition must be cleared explicitly by calling <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_Clear" title="PyErr_Clear"><code class="xref c c-func docutils literal notranslate">PyErr_Clear()</code></a>. The only

time C code should call <code class="xref c c-func docutils literal notranslate">PyErr_Clear()</code> is if it doesn't want to pass the

error on to the interpreter but wants to handle it completely by itself

(possibly by trying something else, or pretending nothing went wrong).

Every failing <code class="xref c c-func docutils literal notranslate">malloc()</code> call must be turned into an exception --- the

direct caller of <code class="xref c c-func docutils literal notranslate">malloc()</code> (or <code class="xref c c-func docutils literal notranslate">realloc()</code>) must call

<a class="reference internal" href="../c-api/exceptions.html#c.PyErr_NoMemory" title="PyErr_NoMemory"><code class="xref c c-func docutils literal notranslate">PyErr_NoMemory()</code></a> and return a failure indicator itself. All the

object-creating functions (for example, <a class="reference internal" href="../c-api/long.html#c.PyLong_FromLong" title="PyLong_FromLong"><code class="xref c c-func docutils literal notranslate">PyLong_FromLong()</code></a>) already do

this, so this note is only relevant to those who call <code class="xref c c-func docutils literal notranslate">malloc()</code> directly.

Also note that, with the important exception of <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> and

friends, functions that return an integer status usually return a positive value

or zero for success and <code class="docutils literal notranslate">-1</code> for failure, like Unix system calls.

Finally, be careful to clean up garbage (by making <a class="reference internal" href="../c-api/refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate">Py_XDECREF()</code></a> or

<a class="reference internal" href="../c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> calls for objects you have already created) when you return

an error indicator!

The choice of which exception to raise is entirely yours. There are predeclared

C objects corresponding to all built-in Python exceptions, such as

should choose exceptions wisely --- don't use <a class="reference internal" href="../c-api/exceptions.html#c.PyExc_TypeError" title="PyExc_TypeError"><code class="xref c c-data docutils literal notranslate">PyExc_TypeError</code></a> to mean

that a file couldn't be opened (that should probably be <a class="reference internal" href="../c-api/exceptions.html#c.PyExc_OSError" title="PyExc_OSError"><code class="xref c c-data docutils literal notranslate">PyExc_OSError</code></a>).

If something's wrong with the argument list, the <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>

function usually raises <code class="xref c c-data docutils literal notranslate">PyExc_TypeError</code>. If you have an argument whose

value must be in a particular range or must satisfy other conditions,

<a class="reference internal" href="../c-api/exceptions.html#c.PyExc_ValueError" title="PyExc_ValueError"><code class="xref c c-data docutils literal notranslate">PyExc_ValueError</code></a> is appropriate.

You can also define a new exception that is unique to your module.

The simplest way to do this is to declare a static global object variable at

the beginning of the file:

<div class="highlight-c notranslate"><div class="highlight"><pre>static PyObject *SpamError = NULL;

</pre></div>

</div>

and initialize it by calling <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_NewException" title="PyErr_NewException"><code class="xref c c-func docutils literal notranslate">PyErr_NewException()</code></a> in the module's

<a class="reference internal" href="../c-api/module.html#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate">Py_mod_exec</code></a> function (<code class="xref c c-func docutils literal notranslate">spam_module_exec()</code>):

<div class="highlight-c notranslate"><div class="highlight"><pre>SpamError = PyErr_NewException("spam.error", NULL, NULL);

</pre></div>

</div>

Since <code class="xref c c-data docutils literal notranslate">SpamError</code> is a global variable, it will be overwritten every time

the module is reinitialized, when the <a class="reference internal" href="../c-api/module.html#c.Py_mod_exec" title="Py_mod_exec"><code class="xref c c-data docutils literal notranslate">Py_mod_exec</code></a> function is called.

For now, let's avoid the issue: we will block repeated initialization by raising an

<a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate">ImportError</code></a>:

static int

spam_module_exec(PyObject *m)

{

if (SpamError != NULL) {

PyErr_SetString(PyExc_ImportError,

"cannot initialize spam module more than once");

return -1;

}

SpamError = PyErr_NewException("spam.error", NULL, NULL);

if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {

return -1;

}

return 0;

}

static PyModuleDef_Slot spam_module_slots[] = {

{Py_mod_exec, spam_module_exec},

{0, NULL}

};

static struct PyModuleDef spam_module = {

.m_base = PyModuleDef_HEAD_INIT,

.m_name = "spam",

.m_size = 0, // non-negative

.m_slots = spam_module_slots,

};

PyMODINIT_FUNC

PyInit_spam(void)

{

return PyModuleDef_Init(&spam_module);

}

</pre></div>

</div>

Note that the Python name for the exception object is <code class="xref py py-exc docutils literal notranslate">spam.error</code>. The

<a class="reference internal" href="../c-api/exceptions.html#c.PyErr_NewException" title="PyErr_NewException"><code class="xref c c-func docutils literal notranslate">PyErr_NewException()</code></a> function may create a class with the base class

being <a class="reference internal" href="../library/exceptions.html#Exception" title="Exception"><code class="xref py py-exc docutils literal notranslate">Exception</code></a> (unless another class is passed in instead of <code class="docutils literal notranslate">NULL</code>),

described in <a class="reference internal" href="../library/exceptions.html#bltin-exceptions">Built-in Exceptions</a>.

Note also that the <code class="xref c c-data docutils literal notranslate">SpamError</code> variable retains a reference to the newly

created exception class; this is intentional! Since the exception could be

removed from the module by external code, an owned reference to the class is

needed to ensure that it will not be discarded, causing <code class="xref c c-data docutils literal notranslate">SpamError</code> to

become a dangling pointer. Should it become a dangling pointer, C code which

raises the exception could cause a core dump or other unintended side effects.

For now, the <a class="reference internal" href="../c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> call to remove this reference is missing.

Even when the Python interpreter shuts down, the global <code class="xref c c-data docutils literal notranslate">SpamError</code>

variable will not be garbage-collected. It will "leak".

We did, however, ensure that this will happen at most once per process.

We discuss the use of <a class="reference internal" href="../c-api/extension-modules.html#c.PyMODINIT_FUNC" title="PyMODINIT_FUNC"><code class="xref c c-macro docutils literal notranslate">PyMODINIT_FUNC</code></a> as a function return type later in this

sample.

The <code class="xref py py-exc docutils literal notranslate">spam.error</code> exception can be raised in your extension module using a

call to <a class="reference internal" href="../c-api/exceptions.html#c.PyErr_SetString" title="PyErr_SetString"><code class="xref c c-func docutils literal notranslate">PyErr_SetString()</code></a> as shown below:

{

int sts;

return NULL;

if (sts < 0) {

PyErr_SetString(SpamError, "System command failed");

return NULL;

}

return PyLong_FromLong(sts);

}

</pre></div>

</div>

</section>

<h2>1.3. Back to the Example<a class="headerlink" href="#back-to-the-example" title="Link to this heading">¶</a></h2>

Going back to our example function, you should now be able to understand this

statement:

<div class="highlight-c notranslate"><div class="highlight"><pre>if (!PyArg_ParseTuple(args, "s", &command))

return NULL;

</pre></div>

</div>

It returns <code class="docutils literal notranslate">NULL</code> (the error indicator for functions returning object pointers)

if an error is detected in the argument list, relying on the exception set by

copied to the local variable <code class="xref c c-data docutils literal notranslate">command</code>. This is a pointer assignment and

you are not supposed to modify the string to which it points (so in Standard C,

the variable <code class="xref c c-data docutils literal notranslate">command</code> should properly be declared as <code class="docutils literal notranslate">const char

*command</code>).

The next statement is a call to the Unix function <code class="xref c c-func docutils literal notranslate">system()</code>, passing it

the string we just got from <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>:

<div class="highlight-c notranslate"><div class="highlight"><pre>sts = system(command);

</pre></div>

</div>

Our <code class="xref py py-func docutils literal notranslate">spam.system()</code> function must return the value of <code class="xref c c-data docutils literal notranslate">sts</code> as a

Python object. This is done using the function <a class="reference internal" href="../c-api/long.html#c.PyLong_FromLong" title="PyLong_FromLong"><code class="xref c c-func docutils literal notranslate">PyLong_FromLong()</code></a>.

<div class="highlight-c notranslate"><div class="highlight"><pre>return PyLong_FromLong(sts);

</pre></div>

</div>

In this case, it will return an integer object. (Yes, even integers are objects

on the heap in Python!)

If you have a C function that returns no useful argument (a function returning

void), the corresponding Python function must return <code class="docutils literal notranslate">None</code>. You

need this idiom to do so (which is implemented by the <a class="reference internal" href="../c-api/none.html#c.Py_RETURN_NONE" title="Py_RETURN_NONE"><code class="xref c c-macro docutils literal notranslate">Py_RETURN_NONE</code></a>

macro):

<div class="highlight-c notranslate"><div class="highlight"><pre>Py_INCREF(Py_None);

return Py_None;

</pre></div>

</div>

<a class="reference internal" href="../c-api/none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate">Py_None</code></a> is the C name for the special Python object <code class="docutils literal notranslate">None</code>. It is a

genuine Python object rather than a <code class="docutils literal notranslate">NULL</code> pointer, which means "error" in most

contexts, as we have seen.

</section>

<h2>1.4. The Module's Method Table and Initialization Function<a class="headerlink" href="#the-module-s-method-table-and-initialization-function" title="Link to this heading">¶</a></h2>

I promised to show how <code class="xref c c-func docutils literal notranslate">spam_system()</code> is called from Python programs.

First, we need to list its name and address in a "method table":

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

...

{"system", spam_system, METH_VARARGS,

"Execute a shell command."},

...

{NULL, NULL, 0, NULL} /* Sentinel */

};

</pre></div>

</div>

Note the third entry (<code class="docutils literal notranslate">METH_VARARGS</code>). This is a flag telling the interpreter

the calling convention to be used for the C function. It should normally always

be <code class="docutils literal notranslate">METH_VARARGS</code> or <code class="docutils literal notranslate">METH_VARARGS | METH_KEYWORDS</code>; a value of <code class="docutils literal notranslate">0</code> means

that an obsolete variant of <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> is used.

When using only <code class="docutils literal notranslate">METH_VARARGS</code>, the function should expect the Python-level

parameters to be passed in as a tuple acceptable for parsing via

The <a class="reference internal" href="../c-api/structures.html#c.METH_KEYWORDS" title="METH_KEYWORDS"><code class="xref c c-macro docutils literal notranslate">METH_KEYWORDS</code></a> bit may be set in the third field if keyword

arguments should be passed to the function. In this case, the C function should

accept a third <code class="docutils literal notranslate">PyObject *</code> parameter which will be a dictionary of keywords.

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> to parse the arguments to such a

function.

The method table must be referenced in the module definition structure:

<div class="highlight-c notranslate"><div class="highlight"><pre>static struct PyModuleDef spam_module = {

...

.m_methods = spam_methods,

...

};

</pre></div>

</div>

This structure, in turn, must be passed to the interpreter in the module's

initialization function. The initialization function must be named

<code class="xref c c-func docutils literal notranslate">PyInit_name()</code>, where name is the name of the module, and should be the

only non-<code class="docutils literal notranslate">static</code> item defined in the module file:

<div class="highlight-c notranslate"><div class="highlight"><pre>PyMODINIT_FUNC

PyInit_spam(void)

{

}

</pre></div>

</div>

Note that <a class="reference internal" href="../c-api/extension-modules.html#c.PyMODINIT_FUNC" title="PyMODINIT_FUNC"><code class="xref c c-macro docutils literal notranslate">PyMODINIT_FUNC</code></a> declares the function as <code class="docutils literal notranslate">PyObject *</code> return type,

declares any special linkage declarations required by the platform, and for C++

declares the function as <code class="docutils literal notranslate">extern "C"</code>.

<code class="xref c c-func docutils literal notranslate">PyInit_spam()</code> is called when each interpreter imports its module

<code class="xref py py-mod docutils literal notranslate">spam</code> for the first time. (See below for comments about embedding Python.)

A pointer to the module definition must be returned via <a class="reference internal" href="../c-api/extension-modules.html#c.PyModuleDef_Init" title="PyModuleDef_Init"><code class="xref c c-func docutils literal notranslate">PyModuleDef_Init()</code></a>,

so that the import machinery can create the module and store it in <code class="docutils literal notranslate">sys.modules</code>.

When embedding Python, the <code class="xref c c-func docutils literal notranslate">PyInit_spam()</code> function is not called

automatically unless there's an entry in the <a class="reference internal" href="../c-api/import.html#c.PyImport_Inittab" title="PyImport_Inittab"><code class="xref c c-data docutils literal notranslate">PyImport_Inittab</code></a> table.

To add the module to the initialization table, use <a class="reference internal" href="../c-api/import.html#c.PyImport_AppendInittab" title="PyImport_AppendInittab"><code class="xref c c-func docutils literal notranslate">PyImport_AppendInittab()</code></a>,

optionally followed by an import of the module:

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

#include <Python.h>

int

main(int argc, char *argv[])

{

PyStatus status;

PyConfig config;

PyConfig_InitPythonConfig(&config);

/* Add a built-in module, before Py_Initialize */

if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {

fprintf(stderr, "Error: could not extend in-built modules table\n");

exit(1);

}

/* Pass argv[0] to the Python interpreter */

status = PyConfig_SetBytesString(&config, &config.program_name, argv[0]);

if (PyStatus_Exception(status)) {

goto exception;

}

/* Initialize the Python interpreter. Required.

If this step fails, it will be a fatal error. */

status = Py_InitializeFromConfig(&config);

goto exception;

}

PyConfig_Clear(&config);

/* Optionally import the module; alternatively,

import can be deferred until the embedded script

imports it. */

PyObject *pmodule = PyImport_ImportModule("spam");

if (!pmodule) {

PyErr_Print();

fprintf(stderr, "Error: could not import module 'spam'\n");

}

// ... use Python C API here ...

return 0;

exception:

PyConfig_Clear(&config);

Py_ExitStatusException(status);

}

</pre></div>

</div>

توجه

If you declare a global variable or a local static one, the module may

experience unintended side-effects on re-initialisation, for example when

removing entries from <code class="docutils literal notranslate">sys.modules</code> or importing compiled modules into

multiple interpreters within a process

(or following a <code class="xref c c-func docutils literal notranslate">fork()</code> without an intervening <code class="xref c c-func docutils literal notranslate">exec()</code>).

If module state is not yet fully <a class="reference internal" href="../howto/isolating-extensions.html#isolating-extensions-howto">isolated</a>,

authors should consider marking the module as having no support for subinterpreters

(via <a class="reference internal" href="../c-api/module.html#c.Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED" title="Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED"><code class="xref c c-macro docutils literal notranslate">Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED</code></a>).

</div>

A more substantial example module is included in the Python source distribution

as <code class="file docutils literal notranslate">Modules/xxlimited.c</code>. This file may be used as a template or simply

read as an example.

</section>

<h2>1.5. Compilation and Linkage<a class="headerlink" href="#compilation-and-linkage" title="Link to this heading">¶</a></h2>

There are two more things to do before you can use your new extension: compiling

and linking it with the Python system. If you use dynamic loading, the details

may depend on the style of dynamic loading your system uses; see the chapters

about building extension modules (chapter <a class="reference internal" href="building.html#building">Building C and C++ Extensions</a>) and additional

information that pertains only to building on Windows (chapter

<a class="reference internal" href="windows.html#building-on-windows">Building C and C++ Extensions on Windows</a>) for more information about this.

If you can't use dynamic loading, or if you want to make your module a permanent

part of the Python interpreter, you will have to change the configuration setup

and rebuild the interpreter. Luckily, this is very simple on Unix: just place

your file (<code class="file docutils literal notranslate">spammodule.c</code> for example) in the <code class="file docutils literal notranslate">Modules/</code> directory

of an unpacked source distribution, add a line to the file

<code class="file docutils literal notranslate">Modules/Setup.local</code> describing your file:

<div class="highlight-sh notranslate"><div class="highlight"><pre>spam spammodule.o

</pre></div>

</div>

and rebuild the interpreter by running make in the toplevel

directory. You can also run make in the <code class="file docutils literal notranslate">Modules/</code>

subdirectory, but then you must first rebuild <code class="file docutils literal notranslate">Makefile</code> there by running

'make Makefile'. (This is necessary each time you change the

<code class="file docutils literal notranslate">Setup</code> file.)

If your module requires additional libraries to link with, these can be listed

on the line in the configuration file as well, for instance:

<div class="highlight-sh notranslate"><div class="highlight"><pre>spam spammodule.o -lX11

</pre></div>

</div>

</section>

<h2>1.6. Calling Python Functions from C<a class="headerlink" href="#calling-python-functions-from-c" title="Link to this heading">¶</a></h2>

So far we have concentrated on making C functions callable from Python. The

reverse is also useful: calling Python functions from C. This is especially the

case for libraries that support so-called "callback" functions. If a C

interface makes use of callbacks, the equivalent Python often needs to provide a

callback mechanism to the Python programmer; the implementation will require

calling the Python callback functions from a C callback. Other uses are also

imaginable.

Fortunately, the Python interpreter is easily called recursively, and there is a

standard interface to call a Python function. (I won't dwell on how to call the

Python parser with a particular string as input --- if you're interested, have a

look at the implementation of the <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate">-c</code></a> command line option in

<code class="file docutils literal notranslate">Modules/main.c</code> from the Python source code.)

Calling a Python function is easy. First, the Python program must somehow pass

you the Python function object. You should provide a function (or some other

interface) to do this. When this function is called, save a pointer to the

Python function object (be careful to <a class="reference internal" href="../c-api/refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate">Py_INCREF()</code></a> it!) in a global

variable --- or wherever you see fit. For example, the following function might

be part of a module definition:

<div class="highlight-c notranslate"><div class="highlight"><pre>static PyObject *my_callback = NULL;

static PyObject *

my_set_callback(PyObject *dummy, PyObject *args)

{

PyObject *result = NULL;

PyObject *temp;

if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {

if (!PyCallable_Check(temp)) {

PyErr_SetString(PyExc_TypeError, "parameter must be callable");

return NULL;

}

Py_XINCREF(temp); /* Add a reference to new callback */

Py_XDECREF(my_callback); /* Dispose of previous callback */

my_callback = temp; /* Remember new callback */

/* Boilerplate to return "None" */

Py_INCREF(Py_None);

result = Py_None;

}

return result;

}

</pre></div>

</div>

This function must be registered with the interpreter using the

<a class="reference internal" href="../c-api/structures.html#c.METH_VARARGS" title="METH_VARARGS"><code class="xref c c-macro docutils literal notranslate">METH_VARARGS</code></a> flag; this is described in section <a class="reference internal" href="#methodtable">The Module's Method Table and Initialization Function</a>. The

<a class="reference internal" href="#parsetuple">Extracting Parameters in Extension Functions</a>.

The macros <a class="reference internal" href="../c-api/refcounting.html#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal notranslate">Py_XINCREF()</code></a> and <a class="reference internal" href="../c-api/refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate">Py_XDECREF()</code></a> increment/decrement the

reference count of an object and are safe in the presence of <code class="docutils literal notranslate">NULL</code> pointers

(but note that temp will not be <code class="docutils literal notranslate">NULL</code> in this context). More info on them

in section <a class="reference internal" href="#refcounts">Reference Counts</a>.

Later, when it is time to call the function, you call the C function

<a class="reference internal" href="../c-api/call.html#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a>. This function has two arguments, both pointers to

arbitrary Python objects: the Python function, and the argument list. The

argument list must always be a tuple object, whose length is the number of

arguments. To call the Python function with no arguments, pass in <code class="docutils literal notranslate">NULL</code>, or

an empty tuple; to call it with one argument, pass a singleton tuple.

<a class="reference internal" href="../c-api/arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> returns a tuple when its format string consists of zero

or more format codes between parentheses. For example:

<div class="highlight-c notranslate"><div class="highlight"><pre>int arg;

PyObject *arglist;

PyObject *result;

...

arg = 123;

...

/* Time to call the callback */

arglist = Py_BuildValue("(i)", arg);

result = PyObject_CallObject(my_callback, arglist);

Py_DECREF(arglist);

</pre></div>

</div>

<a class="reference internal" href="../c-api/call.html#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a> returns a Python object pointer: this is the return

value of the Python function. <code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code> is

"reference-count-neutral" with respect to its arguments. In the example a new

tuple was created to serve as the argument list, which is

<a class="reference internal" href="../c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a>-ed immediately after the <code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code>

call.

The return value of <a class="reference internal" href="../c-api/call.html#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a> is "new": either it is a brand

new object, or it is an existing object whose reference count has been

incremented. So, unless you want to save it in a global variable, you should

somehow <a class="reference internal" href="../c-api/refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> the result, even (especially!) if you are not

interested in its value.

Before you do this, however, it is important to check that the return value

isn't <code class="docutils literal notranslate">NULL</code>. If it is, the Python function terminated by raising an exception.

If the C code that called <a class="reference internal" href="../c-api/call.html#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a> is called from Python, it

should now return an error indication to its Python caller, so the interpreter

can print a stack trace, or the calling Python code can handle the exception.

If this is not possible or desirable, the exception should be cleared by calling

<a class="reference internal" href="../c-api/exceptions.html#c.PyErr_Clear" title="PyErr_Clear"><code class="xref c c-func docutils literal notranslate">PyErr_Clear()</code></a>. For example:

return NULL; /* Pass error back */

...use result...

Py_DECREF(result);

</pre></div>

</div>

Depending on the desired interface to the Python callback function, you may also

have to provide an argument list to <a class="reference internal" href="../c-api/call.html#c.PyObject_CallObject" title="PyObject_CallObject"><code class="xref c c-func docutils literal notranslate">PyObject_CallObject()</code></a>. In some cases

the argument list is also provided by the Python program, through the same

interface that specified the callback function. It can then be saved and used

in the same manner as the function object. In other cases, you may have to

construct a new tuple to pass as the argument list. The simplest way to do this

is to call <a class="reference internal" href="../c-api/arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a>. For example, if you want to pass an integral

event code, you might use the following code:

...

arglist = Py_BuildValue("(l)", eventcode);

Py_DECREF(arglist);

if (result == NULL)

return NULL; /* Pass error back */

/* Here maybe use the result */

Py_DECREF(result);

</pre></div>

</div>

Note the placement of <code class="docutils literal notranslate">Py_DECREF(arglist)</code> immediately after the call, before

the error check! Also note that strictly speaking this code is not complete:

<a class="reference internal" href="../c-api/arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> may run out of memory, and this should be checked.

You may also call a function with keyword arguments by using

<a class="reference internal" href="../c-api/call.html#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal notranslate">PyObject_Call()</code></a>, which supports arguments and keyword arguments. As in

the above example, we use <a class="reference internal" href="../c-api/arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> to construct the dictionary.

...

dict = Py_BuildValue("{s:i}", "name", val);

result = PyObject_Call(my_callback, NULL, dict);

Py_DECREF(dict);

return NULL; /* Pass error back */

/* Here maybe use the result */

Py_DECREF(result);

</pre></div>

</div>

</section>

<h2>1.7. Extracting Parameters in Extension Functions<a class="headerlink" href="#extracting-parameters-in-extension-functions" title="Link to this heading">¶</a></h2>

The <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> function is declared as follows:

<div class="highlight-c notranslate"><div class="highlight"><pre>int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

</pre></div>

</div>

The arg argument must be a tuple object containing an argument list passed

from Python to a C function. The format argument must be a format string,

whose syntax is explained in <a class="reference internal" href="../c-api/arg.html#arg-parsing">Parsing arguments and building values</a> in the Python/C API Reference

Manual. The remaining arguments must be addresses of variables whose type is

determined by the format string.

Note that while <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> checks that the Python arguments have

the required types, it cannot check the validity of the addresses of C variables

passed to the call: if you make mistakes there, your code will probably crash or

at least overwrite random bits in memory. So be careful!

Note that any Python object references which are provided to the caller are

borrowed references; do not decrement their reference count!

Some example calls:

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

#include <Python.h>

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>int ok;

int i, j;

long k, l;

const char *s;

Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* No arguments */

/* Python call: f() */

</pre></div>

</div>

/* Possible Python call: f('whoops!') */

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */

/* Possible Python call: f(1, 2, 'three') */

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);

/* A pair of ints and a string, whose size is also returned */

/* Possible Python call: f((1, 2), 'three') */

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>{

int bufsize = 0;

ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);

/* A string, and optionally another string and an integer */

/* Possible Python calls:

f('spam')

f('spam', 'w')

f('spam', 'wb', 100000) */

}

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>{

int left, top, right, bottom, h, v;

&left, &top, &right, &bottom, &h, &v);

/* A rectangle and a point */

/* Possible Python call:

f(((0, 0), (400, 300)), (10, 10)) */

}

</pre></div>

</div>

<div class="highlight-c notranslate"><div class="highlight"><pre>{

Py_complex c;

/* a complex, also providing a function name for errors */

/* Possible Python call: myfunction(1+2j) */

}

</pre></div>

</div>

</section>

<h2>1.8. Keyword Parameters for Extension Functions<a class="headerlink" href="#keyword-parameters-for-extension-functions" title="Link to this heading">¶</a></h2>

The <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> function is declared as follows:

<div class="highlight-c notranslate"><div class="highlight"><pre>int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,

const char *format, char * const *kwlist, ...);

</pre></div>

</div>

The arg and format parameters are identical to those of the

keywords received as the third parameter from the Python runtime. The kwlist

parameter is a <code class="docutils literal notranslate">NULL</code>-terminated list of strings which identify the parameters;

the names are matched with the type information from format from left to

right. On success, <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> returns true, otherwise

it returns false and raises an appropriate exception.

توجه

Nested tuples cannot be parsed when using keyword arguments! Keyword parameters

passed in which are not present in the kwlist will cause <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate">TypeError</code></a> to

be raised.

</div>

Here is an example module which uses keywords, based on an example by Geoff

Philbrick (<a class="reference external" href="mailto:philbrick%40hks.com">philbrick@hks.com</a>):

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

#include <Python.h>

static PyObject *

keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)

{

int voltage;

static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,

&voltage, &state, &action, &type))

return NULL;

printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",

action, voltage);

printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

Py_RETURN_NONE;

}

static PyMethodDef keywdarg_methods[] = {

/* The cast of the function is necessary since PyCFunction values

* only take two PyObject* parameters, and keywdarg_parrot() takes

* three.

*/

{"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,

"Print a lovely skit to standard output."},

};

static struct PyModuleDef keywdarg_module = {

.m_size = 0,

};

PyMODINIT_FUNC

PyInit_keywdarg(void)

{

}

</pre></div>

</div>

</section>

<h2>1.9. Building Arbitrary Values<a class="headerlink" href="#building-arbitrary-values" title="Link to this heading">¶</a></h2>

This function is the counterpart 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>. It is declared

as follows:

<div class="highlight-c notranslate"><div class="highlight"><pre>PyObject *Py_BuildValue(const char *format, ...);

</pre></div>

</div>

It recognizes a set of format units similar to the ones recognized by

not output) must not be pointers, just values. It returns a new Python object,

suitable for returning from a C function called from Python.

One difference with <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>: while the latter requires its

first argument to be a tuple (since Python argument lists are always represented

as tuples internally), <a class="reference internal" href="../c-api/arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate">Py_BuildValue()</code></a> does not always build a tuple. It

builds a tuple only if its format string contains two or more format units. If

the format string is empty, it returns <code class="docutils literal notranslate">None</code>; if it contains exactly one

format unit, it returns whatever object is described by that format unit. To

force it to return a tuple of size 0 or one, parenthesize the format string.

Examples (to the left the call, to the right the resulting Python value):

<div class="highlight-none notranslate"><div class="highlight"><pre>Py_BuildValue("") None

Py_BuildValue("i", 123) 123

View remainder of file in raw view

Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

extending.html

Latest commit

History

extending.html

File metadata and controls