python-docs-fa/c-api/exceptions.html at gh-pages · python/python-docs-fa

History

2232 lines (2023 loc) · 276 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>Exception Handling — مستندات 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="#">Exception Handling</a><ul>

<li><a class="reference internal" href="#printing-and-clearing">Printing and clearing</a></li>

<li><a class="reference internal" href="#raising-exceptions">Raising exceptions</a></li>

<li><a class="reference internal" href="#issuing-warnings">Issuing warnings</a></li>

<li><a class="reference internal" href="#querying-the-error-indicator">Querying the error indicator</a></li>

<li><a class="reference internal" href="#signal-handling">Signal Handling</a></li>

<li><a class="reference internal" href="#exception-classes">Exception Classes</a></li>

<li><a class="reference internal" href="#exception-objects">Exception Objects</a></li>

<li><a class="reference internal" href="#unicode-exception-objects">Unicode Exception Objects</a></li>

<li><a class="reference internal" href="#recursion-control">Recursion Control</a></li>

<li><a class="reference internal" href="#exception-and-warning-types">Exception and warning types</a><ul>

<li><a class="reference internal" href="#exception-types">Exception types</a></li>

<li><a class="reference internal" href="#oserror-aliases">OSError aliases</a></li>

<li><a class="reference internal" href="#warning-types">Warning types</a></li>

</ul>

</li>

<li><a class="reference internal" href="#tracebacks">Tracebacks</a></li>

</ul>

</li>

</ul>

</div>

<div>

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

<a href="refcounting.html"

title="فصل قبلی">Reference Counting</a>

</div>

<div>

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

<a href="extension-modules.html"

title="فصل بعدی">Defining extension modules</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', "c-api/exceptions.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/c-api/exceptions.rst?plain=1"

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

</a>

</li>

<li>

<a href="https://github.com/python/python-docs-fa/blob/3.14/c-api/exceptions.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="extension-modules.html" title="Defining extension modules"

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

<a href="refcounting.html" title="Reference Counting"

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">Python/C API reference manual</a> »</li>

<li class="nav-item nav-item-this"><a href="">Exception Handling</a></li>

</form>

</div>

</li>

Theme

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

</select>

</label> |</li>

</ul>

</div>

<h1>Exception Handling<a class="headerlink" href="#exception-handling" title="Link to this heading">¶</a></h1>

The functions described in this chapter will let you handle and raise Python

exceptions. It is important to understand some of the basics of Python

exception handling. It works somewhat like the POSIX <code class="xref c c-data docutils literal notranslate">errno</code> variable:

there is a global indicator (per thread) of the last error that occurred. Most

C API functions don't clear this on success, but will set it to indicate the

cause of the error on failure. Most C API functions also return an error

indicator, usually <code class="docutils literal notranslate">NULL</code> if they are supposed to return a pointer, or <code class="docutils literal notranslate">-1</code>

if they return an integer (exception: the <code class="docutils literal notranslate">PyArg_*</code> functions

return <code class="docutils literal notranslate">1</code> for success and <code class="docutils literal notranslate">0</code> for failure).

Concretely, the error indicator consists of three object pointers: the

exception's type, the exception's value, and the traceback object. Any

of those pointers can be <code class="docutils literal notranslate">NULL</code> if non-set (although some combinations are

forbidden, for example you can't have a non-<code class="docutils literal notranslate">NULL</code> traceback if the exception

type is <code class="docutils literal notranslate">NULL</code>).

When a function must fail because some function it called failed, it generally

doesn't set the error indicator; the function it called already set it. It is

responsible for either handling the error and clearing the exception or

returning after cleaning up any resources it holds (such as object references or

memory allocations); it should not continue normally if it is not prepared to

handle the error. If returning due to an error, it is important to indicate to

the caller that an error has been set. If the error is not handled or carefully

propagated, additional calls into the Python/C API may not behave as intended

and may fail in mysterious ways.

توجه

The error indicator is not the result of <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate">sys.exc_info()</code></a>.

The former corresponds to an exception that is not yet caught (and is

therefore still propagating), while the latter returns an exception after

it is caught (and has therefore stopped propagating).

</div>

<h2>Printing and clearing<a class="headerlink" href="#printing-and-clearing" title="Link to this heading">¶</a></h2>

void PyErr_Clear()<a class="headerlink" href="#c.PyErr_Clear" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Clear the error indicator. If the error indicator is not set, there is no

effect.

</dd></dl>

void PyErr_PrintEx(int set_sys_last_vars)<a class="headerlink" href="#c.PyErr_PrintEx" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Print a standard traceback to <code class="docutils literal notranslate">sys.stderr</code> and clear the error indicator.

Unless the error is a <code class="docutils literal notranslate">SystemExit</code>, in that case no traceback is

printed and the Python process will exit with the error code specified by

the <code class="docutils literal notranslate">SystemExit</code> instance.

Call this function only when the error indicator is set. Otherwise it

will cause a fatal error!

If set_sys_last_vars is nonzero, the variable <a class="reference internal" href="../library/sys.html#sys.last_exc" title="sys.last_exc"><code class="xref py py-data docutils literal notranslate">sys.last_exc</code></a> is

set to the printed exception. For backwards compatibility, the

deprecated variables <a class="reference internal" href="../library/sys.html#sys.last_type" title="sys.last_type"><code class="xref py py-data docutils literal notranslate">sys.last_type</code></a>, <a class="reference internal" href="../library/sys.html#sys.last_value" title="sys.last_value"><code class="xref py py-data docutils literal notranslate">sys.last_value</code></a> and

<a class="reference internal" href="../library/sys.html#sys.last_traceback" title="sys.last_traceback"><code class="xref py py-data docutils literal notranslate">sys.last_traceback</code></a> are also set to the type, value and traceback

of this exception, respectively.

تغییر داده شده در نسخه 3.12: The setting of <a class="reference internal" href="../library/sys.html#sys.last_exc" title="sys.last_exc"><code class="xref py py-data docutils literal notranslate">sys.last_exc</code></a> was added.

</div>

</dd></dl>

void PyErr_Print()<a class="headerlink" href="#c.PyErr_Print" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Alias for <code class="docutils literal notranslate">PyErr_PrintEx(1)</code>.

</dd></dl>

void PyErr_WriteUnraisable(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *obj)<a class="headerlink" href="#c.PyErr_WriteUnraisable" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Call <a class="reference internal" href="../library/sys.html#sys.unraisablehook" title="sys.unraisablehook"><code class="xref py py-func docutils literal notranslate">sys.unraisablehook()</code></a> using the current exception and obj

argument.

This utility function prints a warning message to <code class="docutils literal notranslate">sys.stderr</code> when an

exception has been set but it is impossible for the interpreter to actually

raise the exception. It is used, for example, when an exception occurs in an

<a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate">__del__()</code></a> method.

The function is called with a single argument obj that identifies the context

in which the unraisable exception occurred. If possible,

the repr of obj will be printed in the warning message.

If obj is <code class="docutils literal notranslate">NULL</code>, only the traceback is printed.

An exception must be set when calling this function.

تغییر داده شده در نسخه 3.4: Print a traceback. Print only traceback if obj is <code class="docutils literal notranslate">NULL</code>.

</div>

تغییر داده شده در نسخه 3.8: Use <a class="reference internal" href="../library/sys.html#sys.unraisablehook" title="sys.unraisablehook"><code class="xref py py-func docutils literal notranslate">sys.unraisablehook()</code></a>.

</div>

</dd></dl>

void PyErr_FormatUnraisable(const char *format, ...)<a class="headerlink" href="#c.PyErr_FormatUnraisable" title="Link to this definition">¶</a> </dt>

<dd>Similar to <a class="reference internal" href="#c.PyErr_WriteUnraisable" title="PyErr_WriteUnraisable"><code class="xref c c-func docutils literal notranslate">PyErr_WriteUnraisable()</code></a>, but the format and subsequent

parameters help format the warning message; they have the same meaning and

values as in <a class="reference internal" href="unicode.html#c.PyUnicode_FromFormat" title="PyUnicode_FromFormat"><code class="xref c c-func docutils literal notranslate">PyUnicode_FromFormat()</code></a>.

<code class="docutils literal notranslate">PyErr_WriteUnraisable(obj)</code> is roughly equivalent to

<code class="docutils literal notranslate">PyErr_FormatUnraisable("Exception ignored in: %R", obj)</code>.

If format is <code class="docutils literal notranslate">NULL</code>, only the traceback is printed.

Added in version 3.13.

</div>

</dd></dl>

void PyErr_DisplayException(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyErr_DisplayException" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.12.Print the standard traceback display of <code class="docutils literal notranslate">exc</code> to <code class="docutils literal notranslate">sys.stderr</code>, including

chained exceptions and notes.

Added in version 3.12.

</div>

</dd></dl>

</section>

<h2>Raising exceptions<a class="headerlink" href="#raising-exceptions" title="Link to this heading">¶</a></h2>

These functions help you set the current thread's error indicator.

For convenience, some of these functions will always return a

<code class="docutils literal notranslate">NULL</code> pointer for use in a <code class="docutils literal notranslate">return</code> statement.

void PyErr_SetString(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, const char *message)<a class="headerlink" href="#c.PyErr_SetString" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is the most common way to set the error indicator. The first argument

specifies the exception type; it is normally one of the standard exceptions,

e.g. <a class="reference internal" href="#c.PyExc_RuntimeError" title="PyExc_RuntimeError"><code class="xref c c-data docutils literal notranslate">PyExc_RuntimeError</code></a>. You need not create a new

<a class="reference internal" href="../glossary.html#term-strong-reference">strong reference</a> to it (e.g. with <a class="reference internal" href="refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate">Py_INCREF()</code></a>).

The second argument is an error message; it is decoded from <code class="docutils literal notranslate">'utf-8'</code>.

</dd></dl>

void PyErr_SetObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value)<a class="headerlink" href="#c.PyErr_SetObject" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This function is similar to <a class="reference internal" href="#c.PyErr_SetString" title="PyErr_SetString"><code class="xref c c-func docutils literal notranslate">PyErr_SetString()</code></a> but lets you specify an

arbitrary Python object for the "value" of the exception.

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This function sets the error indicator and returns <code class="docutils literal notranslate">NULL</code>. exception

should be a Python exception class. The format and subsequent

parameters help format the error message; they have the same meaning and

string.

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_FormatV(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exception, const char *format, va_list vargs)<a class="headerlink" href="#c.PyErr_FormatV" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.5.Same as <a class="reference internal" href="#c.PyErr_Format" title="PyErr_Format"><code class="xref c c-func docutils literal notranslate">PyErr_Format()</code></a>, but taking a <code class="xref c c-type docutils literal notranslate">va_list</code> argument rather

than a variable number of arguments.

Added in version 3.5.

</div>

</dd></dl>

void PyErr_SetNone(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type)<a class="headerlink" href="#c.PyErr_SetNone" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is a shorthand for <code class="docutils literal notranslate">PyErr_SetObject(type, Py_None)</code>.

</dd></dl>

int PyErr_BadArgument()<a class="headerlink" href="#c.PyErr_BadArgument" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is a shorthand for <code class="docutils literal notranslate">PyErr_SetString(PyExc_TypeError, message)</code>, where

message indicates that a built-in operation was invoked with an illegal

argument. It is mostly for internal use.

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is a shorthand for <code class="docutils literal notranslate">PyErr_SetNone(PyExc_MemoryError)</code>; it returns <code class="docutils literal notranslate">NULL</code>

so an object allocation function can write <code class="docutils literal notranslate">return PyErr_NoMemory();</code> when it

runs out of memory.

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is a convenience function to raise an exception when a C library function

has returned an error and set the C variable <code class="xref c c-data docutils literal notranslate">errno</code>. It constructs a

tuple object whose first item is the integer <code class="xref c c-data docutils literal notranslate">errno</code> value and whose

second item is the corresponding error message (gotten from <code class="xref c c-func docutils literal notranslate">strerror()</code>),

and then calls <code class="docutils literal notranslate">PyErr_SetObject(type, object)</code>. On Unix, when the

<code class="xref c c-data docutils literal notranslate">errno</code> value is <code class="xref c c-macro docutils literal notranslate">EINTR</code>, indicating an interrupted system call,

this calls <a class="reference internal" href="#c.PyErr_CheckSignals" title="PyErr_CheckSignals"><code class="xref c c-func docutils literal notranslate">PyErr_CheckSignals()</code></a>, and if that set the error indicator,

leaves it set to that. The function always returns <code class="docutils literal notranslate">NULL</code>, so a wrapper

function around a system call can write <code class="docutils literal notranslate">return PyErr_SetFromErrno(type);</code>

when the system call returns an error.

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Similar to <a class="reference internal" href="#c.PyErr_SetFromErrno" title="PyErr_SetFromErrno"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromErrno()</code></a>, with the additional behavior that if

filenameObject is not <code class="docutils literal notranslate">NULL</code>, it is passed to the constructor of type as

a third parameter. In the case of <a class="reference internal" href="../library/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> exception,

this is used to define the <code class="xref py py-attr docutils literal notranslate">filename</code> attribute of the

exception instance.

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetFromErrnoWithFilenameObjects(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filenameObject, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filenameObject2)<a class="headerlink" href="#c.PyErr_SetFromErrnoWithFilenameObjects" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetFromErrnoWithFilenameObject" title="PyErr_SetFromErrnoWithFilenameObject"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromErrnoWithFilenameObject()</code></a>, but takes a second

filename object, for raising errors when a function that takes two filenames

fails.

Added in version 3.4.

</div>

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Similar to <a class="reference internal" href="#c.PyErr_SetFromErrnoWithFilenameObject" title="PyErr_SetFromErrnoWithFilenameObject"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromErrnoWithFilenameObject()</code></a>, but the filename

is given as a C string. filename is decoded from the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler">filesystem

encoding and error handler</a>.

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.This is a convenience function to raise <a class="reference internal" href="../library/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a>. If called with

ierr of <code class="docutils literal notranslate">0</code>, the error code returned by a call to <code class="xref c c-func docutils literal notranslate">GetLastError()</code>

is used instead. It calls the Win32 function <code class="xref c c-func docutils literal notranslate">FormatMessage()</code> to retrieve

the Windows description of error code given by ierr or <code class="xref c c-func docutils literal notranslate">GetLastError()</code>,

then it constructs a <code class="xref py py-exc docutils literal notranslate">OSError</code> object with the <a class="reference internal" href="../library/exceptions.html#OSError.winerror" title="OSError.winerror"><code class="xref py py-attr docutils literal notranslate">winerror</code></a>

attribute set to the error code, the <a class="reference internal" href="../library/exceptions.html#OSError.strerror" title="OSError.strerror"><code class="xref py py-attr docutils literal notranslate">strerror</code></a> attribute

set to the corresponding error message (gotten from

<code class="xref c c-func docutils literal notranslate">FormatMessage()</code>), and then calls <code class="docutils literal notranslate">PyErr_SetObject(PyExc_OSError,

object)</code>. This function always returns <code class="docutils literal notranslate">NULL</code>.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErr" title="PyErr_SetFromWindowsErr"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromWindowsErr()</code></a>, with an additional parameter

specifying the exception type to be raised.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

</dd></dl>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErr" title="PyErr_SetFromWindowsErr"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromWindowsErr()</code></a>, with the additional behavior

that if filename is not <code class="docutils literal notranslate">NULL</code>, it is decoded from the filesystem

encoding (<a class="reference internal" href="../library/os.html#os.fsdecode" title="os.fsdecode"><code class="xref py py-func docutils literal notranslate">os.fsdecode()</code></a>) and passed to the constructor of

<a class="reference internal" href="../library/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a> as a third parameter to be used to define the

<code class="xref py py-attr docutils literal notranslate">filename</code> attribute of the exception instance.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetExcFromWindowsErrWithFilenameObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, int ierr, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename)<a class="headerlink" href="#c.PyErr_SetExcFromWindowsErrWithFilenameObject" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetExcFromWindowsErr" title="PyErr_SetExcFromWindowsErr"><code class="xref c c-func docutils literal notranslate">PyErr_SetExcFromWindowsErr()</code></a>, with the additional behavior

that if filename is not <code class="docutils literal notranslate">NULL</code>, it is passed to the constructor of

<code class="xref py py-attr docutils literal notranslate">filename</code> attribute of the exception instance.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetExcFromWindowsErrWithFilenameObjects(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, int ierr, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename2)<a class="headerlink" href="#c.PyErr_SetExcFromWindowsErrWithFilenameObjects" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetExcFromWindowsErrWithFilenameObject" title="PyErr_SetExcFromWindowsErrWithFilenameObject"><code class="xref c c-func docutils literal notranslate">PyErr_SetExcFromWindowsErrWithFilenameObject()</code></a>,

but accepts a second filename object.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

Added in version 3.4.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetExcFromWindowsErrWithFilename(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, int ierr, const char *filename)<a class="headerlink" href="#c.PyErr_SetExcFromWindowsErrWithFilename" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> on Windows از نسخه‌ی 3.7.Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErrWithFilename" title="PyErr_SetFromWindowsErrWithFilename"><code class="xref c c-func docutils literal notranslate">PyErr_SetFromWindowsErrWithFilename()</code></a>, with an additional

parameter specifying the exception type to be raised.

<a class="reference internal" href="../library/intro.html#availability">در دسترس بودن</a>: Windows.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetImportError(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *msg, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *path)<a class="headerlink" href="#c.PyErr_SetImportError" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.7.This is a convenience function to raise <a class="reference internal" href="../library/exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal notranslate">ImportError</code></a>. msg will be

set as the exception's message string. name and path, both of which can

be <code class="docutils literal notranslate">NULL</code>, will be set as the <code class="xref py py-exc docutils literal notranslate">ImportError</code>'s respective <code class="docutils literal notranslate">name</code>

and <code class="docutils literal notranslate">path</code> attributes.

Added in version 3.3.

</div>

</dd></dl>

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *PyErr_SetImportErrorSubclass(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exception, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *msg, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *name, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *path)<a class="headerlink" href="#c.PyErr_SetImportErrorSubclass" title="Link to this definition">¶</a> </dt>

<dd>مقدار بازگشتی: همیشه NULL. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.6.Much like <a class="reference internal" href="#c.PyErr_SetImportError" title="PyErr_SetImportError"><code class="xref c c-func docutils literal notranslate">PyErr_SetImportError()</code></a> but this function allows for

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

Added in version 3.6.

</div>

</dd></dl>

void PyErr_SyntaxLocationObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename, int lineno, int col_offset)<a class="headerlink" href="#c.PyErr_SyntaxLocationObject" title="Link to this definition">¶</a> </dt>

<dd>Set file, line, and offset information for the current exception. If the

current exception is not a <a class="reference internal" href="../library/exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate">SyntaxError</code></a>, then it sets additional

attributes, which make the exception printing subsystem think the exception

is a <code class="xref py py-exc docutils literal notranslate">SyntaxError</code>.

Added in version 3.4.

</div>

</dd></dl>

void PyErr_RangedSyntaxLocationObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)<a class="headerlink" href="#c.PyErr_RangedSyntaxLocationObject" title="Link to this definition">¶</a> </dt>

<dd>Similar to <a class="reference internal" href="#c.PyErr_SyntaxLocationObject" title="PyErr_SyntaxLocationObject"><code class="xref c c-func docutils literal notranslate">PyErr_SyntaxLocationObject()</code></a>, but also sets the

end_lineno and end_col_offset information for the current exception.

Added in version 3.10.

</div>

</dd></dl>

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)<a class="headerlink" href="#c.PyErr_SyntaxLocationEx" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.7.Like <a class="reference internal" href="#c.PyErr_SyntaxLocationObject" title="PyErr_SyntaxLocationObject"><code class="xref c c-func docutils literal notranslate">PyErr_SyntaxLocationObject()</code></a>, but filename is a byte string

decoded from the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler">filesystem encoding and error handler</a>.

Added in version 3.2.

</div>

</dd></dl>

void PyErr_SyntaxLocation(const char *filename, int lineno)<a class="headerlink" href="#c.PyErr_SyntaxLocation" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Like <a class="reference internal" href="#c.PyErr_SyntaxLocationEx" title="PyErr_SyntaxLocationEx"><code class="xref c c-func docutils literal notranslate">PyErr_SyntaxLocationEx()</code></a>, but the col_offset parameter is

omitted.

</dd></dl>

void PyErr_BadInternalCall()<a class="headerlink" href="#c.PyErr_BadInternalCall" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.This is a shorthand for <code class="docutils literal notranslate">PyErr_SetString(PyExc_SystemError, message)</code>,

where message indicates that an internal operation (e.g. a Python/C API

function) was invoked with an illegal argument. It is mostly for internal

use.

</dd></dl>

<dd>Get the source line in filename at line lineno. filename should be a

Python <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate">str</code></a> object.

On success, this function returns a Python string object with the found line.

On failure, this function returns <code class="docutils literal notranslate">NULL</code> without an exception set.

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Similar to <a class="reference internal" href="#c.PyErr_ProgramTextObject" title="PyErr_ProgramTextObject"><code class="xref c c-func docutils literal notranslate">PyErr_ProgramTextObject()</code></a>, but filename is a

const char*, which is decoded with the

<a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler">filesystem encoding and error handler</a>, instead of a

Python object reference.

</dd></dl>

</section>

<h2>Issuing warnings<a class="headerlink" href="#issuing-warnings" title="Link to this heading">¶</a></h2>

Use these functions to issue warnings from C code. They mirror similar

functions exported by the Python <a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate">warnings</code></a> module. They normally

print a warning message to sys.stderr; however, it is

also possible that the user has specified that warnings are to be turned into

errors, and in that case they will raise an exception. It is also possible that

the functions raise an exception because of a problem with the warning machinery.

The return value is <code class="docutils literal notranslate">0</code> if no exception is raised, or <code class="docutils literal notranslate">-1</code> if an exception

is raised. (It is not possible to determine whether a warning message is

actually printed, nor what the reason is for the exception; this is

intentional.) If an exception is raised, the caller should do its normal

exception handling (for example, <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a> owned references and return

an error value).

int PyErr_WarnEx(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *category, const char *message, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t">Py_ssize_t</a> stack_level)<a class="headerlink" href="#c.PyErr_WarnEx" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Issue a warning message. The category argument is a warning category (see

below) or <code class="docutils literal notranslate">NULL</code>; the message argument is a UTF-8 encoded string. stack_level is a

positive number giving a number of stack frames; the warning will be issued from

the currently executing line of code in that stack frame. A stack_level of 1

is the function calling <a class="reference internal" href="#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate">PyErr_WarnEx()</code></a>, 2 is the function above that,

and so forth.

Warning categories must be subclasses of <a class="reference internal" href="#c.PyExc_Warning" title="PyExc_Warning"><code class="xref c c-data docutils literal notranslate">PyExc_Warning</code></a>;

<code class="xref c c-data docutils literal notranslate">PyExc_Warning</code> is a subclass of <a class="reference internal" href="#c.PyExc_Exception" title="PyExc_Exception"><code class="xref c c-data docutils literal notranslate">PyExc_Exception</code></a>;

the default warning category is <a class="reference internal" href="#c.PyExc_RuntimeWarning" title="PyExc_RuntimeWarning"><code class="xref c c-data docutils literal notranslate">PyExc_RuntimeWarning</code></a>. The standard

Python warning categories are available as global variables whose names are

enumerated at <a class="reference internal" href="#standardwarningcategories">Warning types</a>.

For information about warning control, see the documentation for the

<a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate">warnings</code></a> module and the <a class="reference internal" href="../using/cmdline.html#cmdoption-W"><code class="xref std std-option docutils literal notranslate">-W</code></a> option in the command line

documentation. There is no C API for warning control.

</dd></dl>

int PyErr_WarnExplicitObject(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *category, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *message, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *filename, int lineno, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *module, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *registry)<a class="headerlink" href="#c.PyErr_WarnExplicitObject" title="Link to this definition">¶</a> </dt>

<dd>Issue a warning message with explicit control over all warning attributes. This

is a straightforward wrapper around the Python function

<a class="reference internal" href="../library/warnings.html#warnings.warn_explicit" title="warnings.warn_explicit"><code class="xref py py-func docutils literal notranslate">warnings.warn_explicit()</code></a>; see there for more information. The module

and registry arguments may be set to <code class="docutils literal notranslate">NULL</code> to get the default effect

described there.

Added in version 3.4.

</div>

</dd></dl>

int PyErr_WarnExplicit(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *category, const char *message, const char *filename, int lineno, const char *module, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *registry)<a class="headerlink" href="#c.PyErr_WarnExplicit" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Similar to <a class="reference internal" href="#c.PyErr_WarnExplicitObject" title="PyErr_WarnExplicitObject"><code class="xref c c-func docutils literal notranslate">PyErr_WarnExplicitObject()</code></a> except that message and

module are UTF-8 encoded strings, and filename is decoded from the

<a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler">filesystem encoding and error handler</a>.

</dd></dl>

int PyErr_WarnFormat(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *category, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t">Py_ssize_t</a> stack_level, const char *format, ...)<a class="headerlink" href="#c.PyErr_WarnFormat" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Function similar to <a class="reference internal" href="#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate">PyErr_WarnEx()</code></a>, but uses

<a class="reference internal" href="unicode.html#c.PyUnicode_FromFormat" title="PyUnicode_FromFormat"><code class="xref c c-func docutils literal notranslate">PyUnicode_FromFormat()</code></a> to format the warning message. format is

an ASCII-encoded string.

Added in version 3.2.

</div>

</dd></dl>

int PyErr_WarnExplicitFormat(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *category, const char *filename, int lineno, const char *module, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *registry, const char *format, ...)<a class="headerlink" href="#c.PyErr_WarnExplicitFormat" title="Link to this definition">¶</a> </dt>

<dd>Similar to <a class="reference internal" href="#c.PyErr_WarnExplicit" title="PyErr_WarnExplicit"><code class="xref c c-func docutils literal notranslate">PyErr_WarnExplicit()</code></a>, but uses

an ASCII-encoded string.

Added in version 3.2.

</div>

</dd></dl>

int PyErr_ResourceWarning(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *source, <a class="reference internal" href="intro.html#c.Py_ssize_t" title="Py_ssize_t">Py_ssize_t</a> stack_level, const char *format, ...)<a class="headerlink" href="#c.PyErr_ResourceWarning" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.6.Function similar to <a class="reference internal" href="#c.PyErr_WarnFormat" title="PyErr_WarnFormat"><code class="xref c c-func docutils literal notranslate">PyErr_WarnFormat()</code></a>, but category is

<a class="reference internal" href="../library/exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate">ResourceWarning</code></a> and it passes source to <code class="xref py py-class docutils literal notranslate">warnings.WarningMessage</code>.

Added in version 3.6.

</div>

</dd></dl>

</section>

<h2>Querying the error indicator<a class="headerlink" href="#querying-the-error-indicator" title="Link to this heading">¶</a></h2>

<dd>مقدار بازگشتی: مرجع قرضی. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Test whether the error indicator is set. If set, return the exception type

(the first argument to the last call to one of the <code class="docutils literal notranslate">PyErr_Set*</code>

functions or to <a class="reference internal" href="#c.PyErr_Restore" title="PyErr_Restore"><code class="xref c c-func docutils literal notranslate">PyErr_Restore()</code></a>). If not set, return <code class="docutils literal notranslate">NULL</code>. You do not

own a reference to the return value, so you do not need to <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate">Py_DECREF()</code></a>

it.

The caller must have an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a>.

توجه

Do not compare the return value to a specific exception; use

<a class="reference internal" href="#c.PyErr_ExceptionMatches" title="PyErr_ExceptionMatches"><code class="xref c c-func docutils literal notranslate">PyErr_ExceptionMatches()</code></a> instead, shown below. (The comparison could

easily fail since the exception may be an instance instead of a class, in the

case of a class exception, or it may be a subclass of the expected exception.)

</div>

</dd></dl>

int PyErr_ExceptionMatches(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyErr_ExceptionMatches" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Equivalent to <code class="docutils literal notranslate">PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)</code>. This

should only be called when an exception is actually set; a memory access

violation will occur if no exception has been raised.

</dd></dl>

int PyErr_GivenExceptionMatches(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *given, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyErr_GivenExceptionMatches" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Return true if the given exception matches the exception type in exc. If

exc is a class object, this also returns true when given is an instance

of a subclass. If exc is a tuple, all exception types in the tuple (and

recursively in subtuples) are searched for a match.

</dd></dl>

<dd>مقدار بازگشتی: مرجع جدید. قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.12.Return the exception currently being raised, clearing the error indicator at

the same time. Return <code class="docutils literal notranslate">NULL</code> if the error indicator is not set.

This function is used by code that needs to catch exceptions,

or code that needs to save and restore the error indicator temporarily.

For example:

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

PyObject *exc = PyErr_GetRaisedException();

/* ... code that might produce other errors ... */

PyErr_SetRaisedException(exc);

}

</pre></div>

</div>

همچنین ملاحظه نمائید

<a class="reference internal" href="#c.PyErr_GetHandledException" title="PyErr_GetHandledException"><code class="xref c c-func docutils literal notranslate">PyErr_GetHandledException()</code></a>,

to save the exception currently being handled.

</div>

Added in version 3.12.

</div>

</dd></dl>

void PyErr_SetRaisedException(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyErr_SetRaisedException" title="Link to this definition">¶</a> </dt>

clearing the existing exception if one is set.

هشدار

This call steals a reference to exc, which must be a valid exception.

</div>

Added in version 3.12.

</div>

</dd></dl>

void PyErr_Fetch(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **ptype, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **pvalue, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **ptraceback)<a class="headerlink" href="#c.PyErr_Fetch" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.<div class="deprecated">

منسوخ شده از نسخه 3.12: Use <a class="reference internal" href="#c.PyErr_GetRaisedException" title="PyErr_GetRaisedException"><code class="xref c c-func docutils literal notranslate">PyErr_GetRaisedException()</code></a> instead.

</div>

Retrieve the error indicator into three variables whose addresses are passed.

If the error indicator is not set, set all three variables to <code class="docutils literal notranslate">NULL</code>. If it is

set, it will be cleared and you own a reference to each object retrieved. The

value and traceback object may be <code class="docutils literal notranslate">NULL</code> even when the type object is not.

توجه

This function is normally only used by legacy code that needs to catch

exceptions or save and restore the error indicator temporarily.

For example:

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

PyObject *type, *value, *traceback;

PyErr_Fetch(&type, &value, &traceback);

/* ... code that might produce other errors ... */

PyErr_Restore(type, value, traceback);

}

</pre></div>

</div>

</dd></dl>

void PyErr_Restore(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *traceback)<a class="headerlink" href="#c.PyErr_Restore" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.<div class="deprecated">

منسوخ شده از نسخه 3.12: Use <a class="reference internal" href="#c.PyErr_SetRaisedException" title="PyErr_SetRaisedException"><code class="xref c c-func docutils literal notranslate">PyErr_SetRaisedException()</code></a> instead.

</div>

Set the error indicator from the three objects,

type, value, and traceback,

clearing the existing exception if one is set.

If the objects are <code class="docutils literal notranslate">NULL</code>, the error

indicator is cleared. Do not pass a <code class="docutils literal notranslate">NULL</code> type and non-<code class="docutils literal notranslate">NULL</code> value or

traceback. The exception type should be a class. Do not pass an invalid

exception type or value. (Violating these rules will cause subtle problems

later.) This call takes away a reference to each object: you must own a

reference to each object before the call and after the call you no longer own

these references. (If you don't understand this, don't use this function. I

warned you.)

توجه

This function is normally only used by legacy code that needs to

save and restore the error indicator temporarily.

Use <a class="reference internal" href="#c.PyErr_Fetch" title="PyErr_Fetch"><code class="xref c c-func docutils literal notranslate">PyErr_Fetch()</code></a> to save the current error indicator.

</div>

</dd></dl>

void PyErr_NormalizeException(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **exc, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **val, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **tb)<a class="headerlink" href="#c.PyErr_NormalizeException" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.<div class="deprecated">

to avoid any possible de-normalization.

</div>

Under certain circumstances, the values returned by <a class="reference internal" href="#c.PyErr_Fetch" title="PyErr_Fetch"><code class="xref c c-func docutils literal notranslate">PyErr_Fetch()</code></a> below

can be "unnormalized", meaning that <code class="docutils literal notranslate">*exc</code> is a class object but <code class="docutils literal notranslate">*val</code> is

not an instance of the same class. This function can be used to instantiate

the class in that case. If the values are already normalized, nothing happens.

The delayed normalization is implemented to improve performance.

توجه

This function does not implicitly set the

<a class="reference internal" href="../library/exceptions.html#BaseException.__traceback__" title="BaseException.__traceback__"><code class="xref py py-attr docutils literal notranslate">__traceback__</code></a>

attribute on the exception value. If setting the traceback

appropriately is desired, the following additional snippet is needed:

<div class="highlight-c notranslate"><div class="highlight"><pre>if (tb != NULL) {

PyException_SetTraceback(val, tb);

}

</pre></div>

</div>

</dd></dl>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.11.Retrieve the active exception instance, as would be returned by <a class="reference internal" href="../library/sys.html#sys.exception" title="sys.exception"><code class="xref py py-func docutils literal notranslate">sys.exception()</code></a>.

This refers to an exception that was already caught, not to an exception that was

freshly raised. Returns a new reference to the exception or <code class="docutils literal notranslate">NULL</code>.

Does not modify the interpreter's exception state.

توجه

This function is not normally used by code that wants to handle exceptions.

Rather, it can be used when code needs to save and restore the exception

state temporarily. Use <a class="reference internal" href="#c.PyErr_SetHandledException" title="PyErr_SetHandledException"><code class="xref c c-func docutils literal notranslate">PyErr_SetHandledException()</code></a> to restore or

clear the exception state.

</div>

Added in version 3.11.

</div>

</dd></dl>

void PyErr_SetHandledException(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *exc)<a class="headerlink" href="#c.PyErr_SetHandledException" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.11.Set the active exception, as known from <code class="docutils literal notranslate">sys.exception()</code>. This refers

to an exception that was already caught, not to an exception that was

freshly raised.

To clear the exception state, pass <code class="docutils literal notranslate">NULL</code>.

توجه

This function is not normally used by code that wants to handle exceptions.

Rather, it can be used when code needs to save and restore the exception

state temporarily. Use <a class="reference internal" href="#c.PyErr_GetHandledException" title="PyErr_GetHandledException"><code class="xref c c-func docutils literal notranslate">PyErr_GetHandledException()</code></a> to get the exception

state.

</div>

Added in version 3.11.

</div>

</dd></dl>

void PyErr_GetExcInfo(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **ptype, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **pvalue, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> **ptraceback)<a class="headerlink" href="#c.PyErr_GetExcInfo" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.7.Retrieve the old-style representation of the exception info, as known from

<a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate">sys.exc_info()</code></a>. This refers to an exception that was already caught,

not to an exception that was freshly raised. Returns new references for the

three objects, any of which may be <code class="docutils literal notranslate">NULL</code>. Does not modify the exception

info state. This function is kept for backwards compatibility. Prefer using

<a class="reference internal" href="#c.PyErr_GetHandledException" title="PyErr_GetHandledException"><code class="xref c c-func docutils literal notranslate">PyErr_GetHandledException()</code></a>.

توجه

This function is not normally used by code that wants to handle exceptions.

Rather, it can be used when code needs to save and restore the exception

state temporarily. Use <a class="reference internal" href="#c.PyErr_SetExcInfo" title="PyErr_SetExcInfo"><code class="xref c c-func docutils literal notranslate">PyErr_SetExcInfo()</code></a> to restore or clear the

exception state.

</div>

Added in version 3.3.

</div>

</dd></dl>

void PyErr_SetExcInfo(<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *type, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *value, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *traceback)<a class="headerlink" href="#c.PyErr_SetExcInfo" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a> از نسخه‌ی 3.7.Set the exception info, as known from <code class="docutils literal notranslate">sys.exc_info()</code>. This refers

to an exception that was already caught, not to an exception that was

freshly raised. This function steals the references of the arguments.

To clear the exception state, pass <code class="docutils literal notranslate">NULL</code> for all three arguments.

This function is kept for backwards compatibility. Prefer using

<a class="reference internal" href="#c.PyErr_SetHandledException" title="PyErr_SetHandledException"><code class="xref c c-func docutils literal notranslate">PyErr_SetHandledException()</code></a>.

توجه

This function is not normally used by code that wants to handle exceptions.

Rather, it can be used when code needs to save and restore the exception

state temporarily. Use <a class="reference internal" href="#c.PyErr_GetExcInfo" title="PyErr_GetExcInfo"><code class="xref c c-func docutils literal notranslate">PyErr_GetExcInfo()</code></a> to read the exception

state.

</div>

Added in version 3.3.

</div>

تغییر داده شده در نسخه 3.11: The <code class="docutils literal notranslate">type</code> and <code class="docutils literal notranslate">traceback</code> arguments are no longer used and

can be NULL. The interpreter now derives them from the exception

instance (the <code class="docutils literal notranslate">value</code> argument). The function still steals

references of all three arguments.

</div>

</dd></dl>

</section>

<h2>Signal Handling<a class="headerlink" href="#signal-handling" title="Link to this heading">¶</a></h2>

int PyErr_CheckSignals()<a class="headerlink" href="#c.PyErr_CheckSignals" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Handle external interruptions, such as signals or activating a debugger,

whose processing has been delayed until it is safe

to run Python code and/or raise exceptions.

For example, pressing <kbd class="kbd docutils literal notranslate">Ctrl</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd> causes a terminal to send the

<a class="reference internal" href="../library/signal.html#signal.SIGINT" title="signal.SIGINT"><code class="xref py py-data docutils literal notranslate">signal.SIGINT</code></a> signal.

This function executes the corresponding Python signal handler, which,

by default, raises the <a class="reference internal" href="../library/exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate">KeyboardInterrupt</code></a> exception.

<code class="xref c c-func docutils literal notranslate">PyErr_CheckSignals()</code> should be called by long-running C code

frequently enough so that the response appears immediate to humans.

Handlers invoked by this function currently include:

<ul>

<li>Signal handlers, including Python functions registered using

the <a class="reference internal" href="../library/signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate">signal</code></a> module.

Signal handlers are only run in the main thread of the main interpreter.

(This is where the function got the name: originally, signals

were the only way to interrupt the interpreter.)

</li>

<li>Running the garbage collector, if necessary.</li>

<li>Executing a pending <a class="reference internal" href="../howto/remote_debugging.html#remote-debugging">remote debugger</a> script.</li>

</ul>

If any handler raises an exception, immediately return <code class="docutils literal notranslate">-1</code> with that

exception set.

Any remaining interruptions are left to be processed on the next

<a class="reference internal" href="#c.PyErr_CheckSignals" title="PyErr_CheckSignals"><code class="xref c c-func docutils literal notranslate">PyErr_CheckSignals()</code></a> invocation, if appropriate.

If all handlers finish successfully, or there are no handlers to run,

return <code class="docutils literal notranslate">0</code>.

تغییر داده شده در نسخه 3.12: This function may now invoke the garbage collector.

</div>

تغییر داده شده در نسخه 3.14: This function may now execute a remote debugger script, if remote

debugging is enabled.

</div>

</dd></dl>

void PyErr_SetInterrupt()<a class="headerlink" href="#c.PyErr_SetInterrupt" title="Link to this definition">¶</a> </dt>

<dd> قسمتی از <a class="reference internal" href="stable.html#stable">ABI پایدار</a>.Simulate the effect of a <code class="xref c c-macro docutils literal notranslate">SIGINT</code> signal arriving.

This is equivalent to <code class="docutils literal notranslate">PyErr_SetInterruptEx(SIGINT)</code>.

توجه

This function is async-signal-safe. It can be called without

an <a class="reference internal" href="../glossary.html#term-attached-thread-state">attached thread state</a> and from a C signal handler.

</div>

</dd></dl>

View remainder of file in raw view

Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

exceptions.html

Latest commit

History

exceptions.html

File metadata and controls