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

History

1678 lines (1535 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>Descriptor Guide — مستندات 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="#">Descriptor Guide</a><ul>

<li><a class="reference internal" href="#primer">Primer</a><ul>

<li><a class="reference internal" href="#simple-example-a-descriptor-that-returns-a-constant">Simple example: A descriptor that returns a constant</a></li>

<li><a class="reference internal" href="#dynamic-lookups">Dynamic lookups</a></li>

<li><a class="reference internal" href="#managed-attributes">Managed attributes</a></li>

<li><a class="reference internal" href="#customized-names">Customized names</a></li>

<li><a class="reference internal" href="#closing-thoughts">Closing thoughts</a></li>

</ul>

</li>

<li><a class="reference internal" href="#complete-practical-example">Complete Practical Example</a><ul>

<li><a class="reference internal" href="#validator-class">Validator class</a></li>

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

<li><a class="reference internal" href="#practical-application">Practical application</a></li>

</ul>

</li>

<li><a class="reference internal" href="#technical-tutorial">Technical Tutorial</a><ul>

<li><a class="reference internal" href="#abstract">Abstract</a></li>

<li><a class="reference internal" href="#definition-and-introduction">Definition and introduction</a></li>

<li><a class="reference internal" href="#descriptor-protocol">Descriptor protocol</a></li>

<li><a class="reference internal" href="#overview-of-descriptor-invocation">Overview of descriptor invocation</a></li>

<li><a class="reference internal" href="#invocation-from-an-instance">Invocation from an instance</a></li>

<li><a class="reference internal" href="#invocation-from-a-class">Invocation from a class</a></li>

<li><a class="reference internal" href="#invocation-from-super">Invocation from super</a></li>

<li><a class="reference internal" href="#summary-of-invocation-logic">Summary of invocation logic</a></li>

<li><a class="reference internal" href="#automatic-name-notification">Automatic name notification</a></li>

<li><a class="reference internal" href="#orm-example">ORM example</a></li>

</ul>

</li>

<li><a class="reference internal" href="#pure-python-equivalents">Pure Python Equivalents</a><ul>

<li><a class="reference internal" href="#properties">Properties</a></li>

<li><a class="reference internal" href="#functions-and-methods">Functions and methods</a></li>

<li><a class="reference internal" href="#kinds-of-methods">Kinds of methods</a></li>

<li><a class="reference internal" href="#static-methods">Static methods</a></li>

<li><a class="reference internal" href="#class-methods">Class methods</a></li>

<li><a class="reference internal" href="#member-objects-and-slots">Member objects and __slots__</a></li>

</ul>

</li>

</ul>

</li>

</ul>

</div>

<div>

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

<a href="curses.html"

title="فصل قبلی">Curses Programming with Python</a>

</div>

<div>

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

<a href="gdb_helpers.html"

title="فصل بعدی">Debugging C API extensions and CPython Internals with GDB</a>

</div>

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

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

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

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

elements.forEach(element => {

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

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

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

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

element.href = url.toString();

});

</script>

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

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

<li>

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

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

</a>

</li>

<li>

<a href="https://github.com/python/python-docs-fa/blob/3.14/howto/descriptor.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="gdb_helpers.html" title="Debugging C API extensions and CPython Internals with GDB"

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

<a href="curses.html" title="Curses Programming with Python"

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 HOWTOs</a> »</li>

<li class="nav-item nav-item-this"><a href="">Descriptor Guide</a></li>

</form>

</div>

</li>

Theme

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

</select>

</label> |</li>

</ul>

</div>

<h1><a class="toc-backref" href="#id2" role="doc-backlink">Descriptor Guide</a><a class="headerlink" href="#descriptor-guide" title="Link to this heading">¶</a></h1>

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

<dd class="field-odd">Raymond Hettinger

</dd>

<dt class="field-even">Contact:</dt>

</dd>

</dl>

محتوا

<li><a class="reference internal" href="#descriptor-guide" id="id2">Descriptor Guide</a>

<ul>

<li><a class="reference internal" href="#primer" id="id3">Primer</a>

<ul>

<li><a class="reference internal" href="#simple-example-a-descriptor-that-returns-a-constant" id="id4">Simple example: A descriptor that returns a constant</a></li>

<li><a class="reference internal" href="#dynamic-lookups" id="id5">Dynamic lookups</a></li>

<li><a class="reference internal" href="#managed-attributes" id="id6">Managed attributes</a></li>

<li><a class="reference internal" href="#customized-names" id="id7">Customized names</a></li>

<li><a class="reference internal" href="#closing-thoughts" id="id8">Closing thoughts</a></li>

</ul>

</li>

<li><a class="reference internal" href="#complete-practical-example" id="id9">Complete Practical Example</a>

<ul>

<li><a class="reference internal" href="#validator-class" id="id10">Validator class</a></li>

<li><a class="reference internal" href="#custom-validators" id="id11">Custom validators</a></li>

<li><a class="reference internal" href="#practical-application" id="id12">Practical application</a></li>

</ul>

</li>

<li><a class="reference internal" href="#technical-tutorial" id="id13">Technical Tutorial</a>

<ul>

<li><a class="reference internal" href="#abstract" id="id14">Abstract</a></li>

<li><a class="reference internal" href="#definition-and-introduction" id="id15">Definition and introduction</a></li>

<li><a class="reference internal" href="#descriptor-protocol" id="id16">Descriptor protocol</a></li>

<li><a class="reference internal" href="#overview-of-descriptor-invocation" id="id17">Overview of descriptor invocation</a></li>

<li><a class="reference internal" href="#invocation-from-an-instance" id="id18">Invocation from an instance</a></li>

<li><a class="reference internal" href="#invocation-from-a-class" id="id19">Invocation from a class</a></li>

<li><a class="reference internal" href="#invocation-from-super" id="id20">Invocation from super</a></li>

<li><a class="reference internal" href="#summary-of-invocation-logic" id="id21">Summary of invocation logic</a></li>

<li><a class="reference internal" href="#automatic-name-notification" id="id22">Automatic name notification</a></li>

<li><a class="reference internal" href="#orm-example" id="id23">ORM example</a></li>

</ul>

</li>

<li><a class="reference internal" href="#pure-python-equivalents" id="id24">Pure Python Equivalents</a>

<ul>

<li><a class="reference internal" href="#properties" id="id25">Properties</a></li>

<li><a class="reference internal" href="#functions-and-methods" id="id26">Functions and methods</a></li>

<li><a class="reference internal" href="#kinds-of-methods" id="id27">Kinds of methods</a></li>

<li><a class="reference internal" href="#static-methods" id="id28">Static methods</a></li>

<li><a class="reference internal" href="#class-methods" id="id29">Class methods</a></li>

<li><a class="reference internal" href="#member-objects-and-slots" id="id30">Member objects and __slots__</a></li>

</ul>

</li>

</ul>

</li>

</ul>

</nav>

<a class="reference internal" href="../glossary.html#term-descriptor">Descriptors</a> let objects customize attribute lookup,

storage, and deletion.

This guide has four major sections:

<li>The "primer" gives a basic overview, moving gently from simple examples,

adding one feature at a time. Start here if you're new to descriptors.</li>

<li>The second section shows a complete, practical descriptor example. If you

already know the basics, start there.</li>

<li>The third section provides a more technical tutorial that goes into the

detailed mechanics of how descriptors work. Most people don't need this

level of detail.</li>

<li>The last section has pure Python equivalents for built-in descriptors that

are written in C. Read this if you're curious about how functions turn

into bound methods or about the implementation of common tools like

<a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate">classmethod()</code></a>, <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate">staticmethod()</code></a>, <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate">property()</code></a>, and

<a class="reference internal" href="../glossary.html#term-__slots__">__slots__</a>.</li>

</ol>

<h2><a class="toc-backref" href="#id3" role="doc-backlink">Primer</a><a class="headerlink" href="#primer" title="Link to this heading">¶</a></h2>

In this primer, we start with the most basic possible example and then we'll

add new capabilities one by one.

<h3><a class="toc-backref" href="#id4" role="doc-backlink">Simple example: A descriptor that returns a constant</a><a class="headerlink" href="#simple-example-a-descriptor-that-returns-a-constant" title="Link to this heading">¶</a></h3>

The <code class="xref py py-class docutils literal notranslate">Ten</code> class is a descriptor whose <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a> method always

returns the constant <code class="docutils literal notranslate">10</code>:

<div class="highlight-python notranslate"><div class="highlight"><pre>class Ten:

def __get__(self, obj, objtype=None):

return 10

</pre></div>

</div>

To use the descriptor, it must be stored as a class variable in another class:

<div class="highlight-python notranslate"><div class="highlight"><pre>class A:

x = 5 # Regular class attribute

y = Ten() # Descriptor instance

</pre></div>

</div>

An interactive session shows the difference between normal attribute lookup

and descriptor lookup:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> a = A() # Make an instance of class A

>>> a.x # Normal attribute lookup

5

>>> a.y # Descriptor lookup

10

</pre></div>

</div>

In the <code class="docutils literal notranslate">a.x</code> attribute lookup, the dot operator finds <code class="docutils literal notranslate">'x': 5</code>

in the class dictionary. In the <code class="docutils literal notranslate">a.y</code> lookup, the dot operator

finds a descriptor instance, recognized by its <code class="docutils literal notranslate">__get__</code> method.

Calling that method returns <code class="docutils literal notranslate">10</code>.

Note that the value <code class="docutils literal notranslate">10</code> is not stored in either the class dictionary or the

instance dictionary. Instead, the value <code class="docutils literal notranslate">10</code> is computed on demand.

This example shows how a simple descriptor works, but it isn't very useful.

For retrieving constants, normal attribute lookup would be better.

In the next section, we'll create something more useful, a dynamic lookup.

</section>

<h3><a class="toc-backref" href="#id5" role="doc-backlink">Dynamic lookups</a><a class="headerlink" href="#dynamic-lookups" title="Link to this heading">¶</a></h3>

Interesting descriptors typically run computations instead of returning

constants:

<div class="highlight-python notranslate"><div class="highlight"><pre>import os

class DirectorySize:

return len(os.listdir(obj.dirname))

class Directory:

size = DirectorySize() # Descriptor instance

self.dirname = dirname # Regular instance attribute

</pre></div>

</div>

An interactive session shows that the lookup is dynamic — it computes

different, updated answers each time:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> s = Directory('songs')

>>> g = Directory('games')

>>> s.size # The songs directory has twenty files

20

>>> g.size # The games directory has three files

3

>>> os.remove('games/chess') # Delete a game

>>> g.size # File count is automatically updated

2

</pre></div>

</div>

Besides showing how descriptors can run computations, this example also

reveals the purpose of the parameters to <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a>. The self

parameter is size, an instance of DirectorySize. The obj parameter is

either g or s, an instance of Directory. It is the obj parameter that

lets the <code class="xref py py-meth docutils literal notranslate">__get__()</code> method learn the target directory. The objtype

parameter is the class Directory.

</section>

<h3><a class="toc-backref" href="#id6" role="doc-backlink">Managed attributes</a><a class="headerlink" href="#managed-attributes" title="Link to this heading">¶</a></h3>

A popular use for descriptors is managing access to instance data. The

descriptor is assigned to a public attribute in the class dictionary while the

actual data is stored as a private attribute in the instance dictionary. The

descriptor's <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate">__set__()</code></a> methods are triggered when

the public attribute is accessed.

In the following example, age is the public attribute and _age is the

private attribute. When the public attribute is accessed, the descriptor logs

the lookup or update:

<div class="highlight-python notranslate"><div class="highlight"><pre>import logging

logging.basicConfig(level=logging.INFO)

class LoggedAgeAccess:

value = obj._age

logging.info('Accessing %r giving %r', 'age', value)

return value

def __set__(self, obj, value):

logging.info('Updating %r to %r', 'age', value)

obj._age = value

class Person:

age = LoggedAgeAccess() # Descriptor instance

self.name = name # Regular instance attribute

self.age = age # Calls __set__()

def birthday(self):

self.age += 1 # Calls both __get__() and __set__()

</pre></div>

</div>

An interactive session shows that all access to the managed attribute age is

logged, but that the regular attribute name is not logged:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> mary = Person('Mary M', 30) # The initial age update is logged

INFO:root:Updating 'age' to 30

>>> dave = Person('David D', 40)

INFO:root:Updating 'age' to 40

>>> vars(mary) # The actual data is in a private attribute

{'name': 'Mary M', '_age': 30}

>>> vars(dave)

{'name': 'David D', '_age': 40}

>>> mary.age # Access the data and log the lookup

INFO:root:Accessing 'age' giving 30

30

>>> mary.birthday() # Updates are logged as well

INFO:root:Accessing 'age' giving 30

INFO:root:Updating 'age' to 31

>>> dave.name # Regular attribute lookup isn't logged

'David D'

>>> dave.age # Only the managed attribute is logged

INFO:root:Accessing 'age' giving 40

40

</pre></div>

</div>

One major issue with this example is that the private name _age is hardwired in

the LoggedAgeAccess class. That means that each instance can only have one

logged attribute and that its name is unchangeable. In the next example,

we'll fix that problem.

</section>

<h3><a class="toc-backref" href="#id7" role="doc-backlink">Customized names</a><a class="headerlink" href="#customized-names" title="Link to this heading">¶</a></h3>

When a class uses descriptors, it can inform each descriptor about which

variable name was used.

In this example, the <code class="xref py py-class docutils literal notranslate">Person</code> class has two descriptor instances,

name and age. When the <code class="xref py py-class docutils literal notranslate">Person</code> class is defined, it makes a

callback to <a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate">__set_name__()</code></a> in LoggedAccess so that the field names can

be recorded, giving each descriptor its own public_name and private_name:

<div class="highlight-python notranslate"><div class="highlight"><pre>import logging

class LoggedAccess:

def __set_name__(self, owner, name):

self.public_name = name

self.private_name = '_' + name

value = getattr(obj, self.private_name)

logging.info('Accessing %r giving %r', self.public_name, value)

return value

logging.info('Updating %r to %r', self.public_name, value)

setattr(obj, self.private_name, value)

class Person:

name = LoggedAccess() # First descriptor instance

age = LoggedAccess() # Second descriptor instance

self.name = name # Calls the first descriptor

self.age = age # Calls the second descriptor

def birthday(self):

self.age += 1

</pre></div>

</div>

An interactive session shows that the <code class="xref py py-class docutils literal notranslate">Person</code> class has called

<a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate">__set_name__()</code></a> so that the field names would be recorded. Here

we call <a class="reference internal" href="../library/functions.html#vars" title="vars"><code class="xref py py-func docutils literal notranslate">vars()</code></a> to look up the descriptor without triggering it:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> vars(vars(Person)['name'])

{'public_name': 'name', 'private_name': '_name'}

>>> vars(vars(Person)['age'])

{'public_name': 'age', 'private_name': '_age'}

</pre></div>

</div>

The new class now logs access to both name and age:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> pete = Person('Peter P', 10)

INFO:root:Updating 'name' to 'Peter P'

INFO:root:Updating 'age' to 10

>>> kate = Person('Catherine C', 20)

INFO:root:Updating 'name' to 'Catherine C'

INFO:root:Updating 'age' to 20

</pre></div>

</div>

The two Person instances contain only the private names:

{'_name': 'Peter P', '_age': 10}

>>> vars(kate)

{'_name': 'Catherine C', '_age': 20}

</pre></div>

</div>

</section>

<h3><a class="toc-backref" href="#id8" role="doc-backlink">Closing thoughts</a><a class="headerlink" href="#closing-thoughts" title="Link to this heading">¶</a></h3>

A <a class="reference internal" href="../glossary.html#term-descriptor">descriptor</a> is what we call any object that defines <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a>,

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

Optionally, descriptors can have a <a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate">__set_name__()</code></a> method. This is only

used in cases where a descriptor needs to know either the class where it was

created or the name of class variable it was assigned to. (This method, if

present, is called even if the class is not a descriptor.)

Descriptors get invoked by the dot operator during attribute lookup. If a

descriptor is accessed indirectly with <code class="docutils literal notranslate">vars(some_class)[descriptor_name]</code>,

the descriptor instance is returned without invoking it.

Descriptors only work when used as class variables. When put in instances,

they have no effect.

The main motivation for descriptors is to provide a hook allowing objects

stored in class variables to control what happens during attribute lookup.

Traditionally, the calling class controls what happens during lookup.

Descriptors invert that relationship and allow the data being looked-up to

have a say in the matter.

Descriptors are used throughout the language. It is how functions turn into

bound methods. Common tools like <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate">classmethod()</code></a>, <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate">staticmethod()</code></a>,

<a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate">property()</code></a>, and <a class="reference internal" href="../library/functools.html#functools.cached_property" title="functools.cached_property"><code class="xref py py-func docutils literal notranslate">functools.cached_property()</code></a> are all implemented as

descriptors.

</section>

<h2><a class="toc-backref" href="#id9" role="doc-backlink">Complete Practical Example</a><a class="headerlink" href="#complete-practical-example" title="Link to this heading">¶</a></h2>

In this example, we create a practical and powerful tool for locating

notoriously hard to find data corruption bugs.

<h3><a class="toc-backref" href="#id10" role="doc-backlink">Validator class</a><a class="headerlink" href="#validator-class" title="Link to this heading">¶</a></h3>

A validator is a descriptor for managed attribute access. Prior to storing

any data, it verifies that the new value meets various type and range

restrictions. If those restrictions aren't met, it raises an exception to

prevent data corruption at its source.

This <code class="xref py py-class docutils literal notranslate">Validator</code> class is both an <a class="reference internal" href="../glossary.html#term-abstract-base-class">abstract base class</a> and a

managed attribute descriptor:

<div class="highlight-python notranslate"><div class="highlight"><pre>from abc import ABC, abstractmethod

class Validator(ABC):

self.private_name = '_' + name

return getattr(obj, self.private_name)

self.validate(value)

@abstractmethod

def validate(self, value):

pass

</pre></div>

</div>

Custom validators need to inherit from <code class="xref py py-class docutils literal notranslate">Validator</code> and must supply a

<code class="xref py py-meth docutils literal notranslate">validate()</code> method to test various restrictions as needed.

</section>

<h3><a class="toc-backref" href="#id11" role="doc-backlink">Custom validators</a><a class="headerlink" href="#custom-validators" title="Link to this heading">¶</a></h3>

Here are three practical data validation utilities:

<li><code class="xref py py-class docutils literal notranslate">OneOf</code> verifies that a value is one of a restricted set of options.</li>

<li><code class="xref py py-class docutils literal notranslate">Number</code> verifies that a value is either an <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate">int</code></a> or

<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate">float</code></a>. Optionally, it verifies that a value is between a given

minimum or maximum.</li>

<li><code class="xref py py-class docutils literal notranslate">String</code> verifies that a value is a <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate">str</code></a>. Optionally, it

validates a given minimum or maximum length. It can validate a

user-defined <a class="reference external" href="https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)">predicate</a> as well.</li>

</ol>

<div class="highlight-python notranslate"><div class="highlight"><pre>class OneOf(Validator):

self.options = set(options)

if value not in self.options:

raise ValueError(

f'Expected {value!r} to be one of {self.options!r}'

)

class Number(Validator):

self.minvalue = minvalue

self.maxvalue = maxvalue

if not isinstance(value, (int, float)):

raise TypeError(f'Expected {value!r} to be an int or float')

if self.minvalue is not None and value < self.minvalue:

raise ValueError(

f'Expected {value!r} to be at least {self.minvalue!r}'

)

if self.maxvalue is not None and value > self.maxvalue:

raise ValueError(

f'Expected {value!r} to be no more than {self.maxvalue!r}'

)

class String(Validator):

def __init__(self, minsize=None, maxsize=None, predicate=None):

self.minsize = minsize

self.maxsize = maxsize

self.predicate = predicate

if self.minsize is not None and len(value) < self.minsize:

raise ValueError(

f'Expected {value!r} to be no smaller than {self.minsize!r}'

)

if self.maxsize is not None and len(value) > self.maxsize:

raise ValueError(

f'Expected {value!r} to be no bigger than {self.maxsize!r}'

)

if self.predicate is not None and not self.predicate(value):

raise ValueError(

f'Expected {self.predicate} to be true for {value!r}'

)

</pre></div>

</div>

</section>

<h3><a class="toc-backref" href="#id12" role="doc-backlink">Practical application</a><a class="headerlink" href="#practical-application" title="Link to this heading">¶</a></h3>

Here's how the data validators can be used in a real class:

<div class="highlight-python notranslate"><div class="highlight"><pre>class Component:

name = String(minsize=3, maxsize=10, predicate=str.isupper)

kind = OneOf('wood', 'metal', 'plastic')

quantity = Number(minvalue=0)

self.name = name

self.kind = kind

self.quantity = quantity

</pre></div>

</div>

The descriptors prevent invalid instances from being created:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> Component('Widget', 'metal', 5) # Blocked: 'Widget' is not all uppercase

Traceback (most recent call last):

...

ValueError: Expected <method 'isupper' of 'str' objects> to be true for 'Widget'

>>> Component('WIDGET', 'metle', 5) # Blocked: 'metle' is misspelled

Traceback (most recent call last):

...

ValueError: Expected 'metle' to be one of {'metal', 'plastic', 'wood'}

>>> Component('WIDGET', 'metal', -5) # Blocked: -5 is negative

Traceback (most recent call last):

...

ValueError: Expected -5 to be at least 0

>>> Component('WIDGET', 'metal', 'V') # Blocked: 'V' isn't a number

Traceback (most recent call last):

...

TypeError: Expected 'V' to be an int or float

>>> c = Component('WIDGET', 'metal', 5) # Allowed: The inputs are valid

</pre></div>

</div>

</section>

<h2><a class="toc-backref" href="#id13" role="doc-backlink">Technical Tutorial</a><a class="headerlink" href="#technical-tutorial" title="Link to this heading">¶</a></h2>

What follows is a more technical tutorial for the mechanics and details of how

descriptors work.

<h3><a class="toc-backref" href="#id14" role="doc-backlink">Abstract</a><a class="headerlink" href="#abstract" title="Link to this heading">¶</a></h3>

Defines descriptors, summarizes the protocol, and shows how descriptors are

called. Provides an example showing how object relational mappings work.

Learning about descriptors not only provides access to a larger toolset, it

creates a deeper understanding of how Python works.

</section>

<h3><a class="toc-backref" href="#id15" role="doc-backlink">Definition and introduction</a><a class="headerlink" href="#definition-and-introduction" title="Link to this heading">¶</a></h3>

In general, a descriptor is an attribute value that has one of the methods in

the descriptor protocol. Those methods are <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a>, <a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate">__set__()</code></a>,

and <a class="reference internal" href="../reference/datamodel.html#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate">__delete__()</code></a>. If any of those methods are defined for an

attribute, it is said to be a <a class="reference internal" href="../glossary.html#term-descriptor">descriptor</a>.

The default behavior for attribute access is to get, set, or delete the

attribute from an object's dictionary. For instance, <code class="docutils literal notranslate">a.x</code> has a lookup chain

starting with <code class="docutils literal notranslate">a.__dict__['x']</code>, then <code class="docutils literal notranslate">type(a).__dict__['x']</code>, and

continuing through the method resolution order of <code class="docutils literal notranslate">type(a)</code>. If the

looked-up value is an object defining one of the descriptor methods, then Python

may override the default behavior and invoke the descriptor method instead.

Where this occurs in the precedence chain depends on which descriptor methods

were defined.

Descriptors are a powerful, general purpose protocol. They are the mechanism

behind properties, methods, static methods, class methods, and

<a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate">super()</code></a>. They are used throughout Python itself. Descriptors

simplify the underlying C code and offer a flexible set of new tools for

everyday Python programs.

</section>

<h3><a class="toc-backref" href="#id16" role="doc-backlink">Descriptor protocol</a><a class="headerlink" href="#descriptor-protocol" title="Link to this heading">¶</a></h3>

<code class="docutils literal notranslate">descr.__get__(self, obj, type=None)</code>

<code class="docutils literal notranslate">descr.__set__(self, obj, value)</code>

<code class="docutils literal notranslate">descr.__delete__(self, obj)</code>

That is all there is to it. Define any of these methods and an object is

considered a descriptor and can override default behavior upon being looked up

as an attribute.

If an object defines <a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate">__set__()</code></a> or <a class="reference internal" href="../reference/datamodel.html#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal notranslate">__delete__()</code></a>, it is considered

a data descriptor. Descriptors that only define <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a> are called

non-data descriptors (they are often used for methods but other uses are

possible).

Data and non-data descriptors differ in how overrides are calculated with

respect to entries in an instance's dictionary. If an instance's dictionary

has an entry with the same name as a data descriptor, the data descriptor

takes precedence. If an instance's dictionary has an entry with the same

name as a non-data descriptor, the dictionary entry takes precedence.

To make a read-only data descriptor, define both <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a> and

<a class="reference internal" href="../reference/datamodel.html#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal notranslate">__set__()</code></a> with the <code class="xref py py-meth docutils literal notranslate">__set__()</code> raising an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate">AttributeError</code></a> when

called. Defining the <code class="xref py py-meth docutils literal notranslate">__set__()</code> method with an exception raising

placeholder is enough to make it a data descriptor.

</section>

<h3><a class="toc-backref" href="#id17" role="doc-backlink">Overview of descriptor invocation</a><a class="headerlink" href="#overview-of-descriptor-invocation" title="Link to this heading">¶</a></h3>

A descriptor can be called directly with <code class="docutils literal notranslate">desc.__get__(obj)</code> or

<code class="docutils literal notranslate">desc.__get__(None, cls)</code>.

But it is more common for a descriptor to be invoked automatically from

attribute access.

The expression <code class="docutils literal notranslate">obj.x</code> looks up the attribute <code class="docutils literal notranslate">x</code> in the chain of

namespaces for <code class="docutils literal notranslate">obj</code>. If the search finds a descriptor outside of the

instance <a class="reference internal" href="../reference/datamodel.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate">__dict__</code></a>, its <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a> method is

invoked according to the precedence rules listed below.

The details of invocation depend on whether <code class="docutils literal notranslate">obj</code> is an object, class, or

instance of super.

</section>

<h3><a class="toc-backref" href="#id18" role="doc-backlink">Invocation from an instance</a><a class="headerlink" href="#invocation-from-an-instance" title="Link to this heading">¶</a></h3>

Instance lookup scans through a chain of namespaces giving data descriptors

the highest priority, followed by instance variables, then non-data

descriptors, then class variables, and lastly <a class="reference internal" href="../reference/datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate">__getattr__()</code></a> if it is

provided.

If a descriptor is found for <code class="docutils literal notranslate">a.x</code>, then it is invoked with:

<code class="docutils literal notranslate">desc.__get__(a, type(a))</code>.

The logic for a dotted lookup is in <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">object.__getattribute__()</code></a>. Here is

a pure Python equivalent:

<div class="highlight-python notranslate"><div class="highlight"><pre>def find_name_in_mro(cls, name, default):

"Emulate _PyType_Lookup() in Objects/typeobject.c"

for base in cls.__mro__:

if name in vars(base):

return vars(base)[name]

return default

def object_getattribute(obj, name):

"Emulate PyObject_GenericGetAttr() in Objects/object.c"

null = object()

objtype = type(obj)

cls_var = find_name_in_mro(objtype, name, null)

descr_get = getattr(type(cls_var), '__get__', null)

if descr_get is not null:

if (hasattr(type(cls_var), '__set__')

or hasattr(type(cls_var), '__delete__')):

return descr_get(cls_var, obj, objtype) # data descriptor

if hasattr(obj, '__dict__') and name in vars(obj):

return vars(obj)[name] # instance variable

if descr_get is not null:

if cls_var is not null:

return cls_var # class variable

raise AttributeError(name)

</pre></div>

</div>

Note, there is no <a class="reference internal" href="../reference/datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate">__getattr__()</code></a> hook in the <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a>

code. That is why calling <code class="xref py py-meth docutils literal notranslate">__getattribute__()</code> directly or with

<code class="docutils literal notranslate">super().__getattribute__</code> will bypass <code class="xref py py-meth docutils literal notranslate">__getattr__()</code> entirely.

Instead, it is the dot operator and the <a class="reference internal" href="../library/functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal notranslate">getattr()</code></a> function that are

responsible for invoking <a class="reference internal" href="../reference/datamodel.html#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal notranslate">__getattr__()</code></a> whenever <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a>

raises an <a class="reference internal" href="../library/exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate">AttributeError</code></a>. Their logic is encapsulated in a helper

function:

<div class="highlight-python notranslate"><div class="highlight"><pre>def getattr_hook(obj, name):

"Emulate slot_tp_getattr_hook() in Objects/typeobject.c"

try:

return obj.__getattribute__(name)

except AttributeError:

if not hasattr(type(obj), '__getattr__'):

raise

return type(obj).__getattr__(obj, name) # __getattr__

</pre></div>

</div>

</section>

<h3><a class="toc-backref" href="#id19" role="doc-backlink">Invocation from a class</a><a class="headerlink" href="#invocation-from-a-class" title="Link to this heading">¶</a></h3>

The logic for a dotted lookup such as <code class="docutils literal notranslate">A.x</code> is in

<code class="xref py py-meth docutils literal notranslate">type.__getattribute__()</code>. The steps are similar to those for

<code class="xref py py-meth docutils literal notranslate">object.__getattribute__()</code> but the instance dictionary lookup is replaced

by a search through the class's <a class="reference internal" href="../glossary.html#term-method-resolution-order">method resolution order</a>.

If a descriptor is found, it is invoked with <code class="docutils literal notranslate">desc.__get__(None, A)</code>.

The full C implementation can be found in <code class="xref c c-func docutils literal notranslate">type_getattro()</code> and

<code class="xref c c-func docutils literal notranslate">_PyType_Lookup()</code> in <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Objects/typeobject.c">Objects/typeobject.c</a>.

</section>

<h3><a class="toc-backref" href="#id20" role="doc-backlink">Invocation from super</a><a class="headerlink" href="#invocation-from-super" title="Link to this heading">¶</a></h3>

The logic for super's dotted lookup is in the <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a> method for

object returned by <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate">super()</code></a>.

A dotted lookup such as <code class="docutils literal notranslate">super(A, obj).m</code> searches <code class="docutils literal notranslate">obj.__class__.__mro__</code>

for the base class <code class="docutils literal notranslate">B</code> immediately following <code class="docutils literal notranslate">A</code> and then returns

<code class="docutils literal notranslate">B.__dict__['m'].__get__(obj, A)</code>. If not a descriptor, <code class="docutils literal notranslate">m</code> is returned

unchanged.

The full C implementation can be found in <code class="xref c c-func docutils literal notranslate">super_getattro()</code> in

<a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Objects/typeobject.c">Objects/typeobject.c</a>. A pure Python equivalent can be found in

<a class="reference external" href="https://www.python.org/download/releases/2.2.3/descrintro/#cooperation">Guido's Tutorial</a>.

</section>

<h3><a class="toc-backref" href="#id21" role="doc-backlink">Summary of invocation logic</a><a class="headerlink" href="#summary-of-invocation-logic" title="Link to this heading">¶</a></h3>

The mechanism for descriptors is embedded in the <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a>

methods for <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate">object</code></a>, <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate">type</code></a>, and <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate">super()</code></a>.

The important points to remember are:

<li>Descriptors are invoked by the <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a> method.</li>

<li>Classes inherit this machinery from <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate">object</code></a>, <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate">type</code></a>, or

<a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-func docutils literal notranslate">super()</code></a>.</li>

<li>Overriding <a class="reference internal" href="../reference/datamodel.html#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal notranslate">__getattribute__()</code></a> prevents automatic descriptor calls

because all the descriptor logic is in that method.</li>

<li><code class="xref py py-meth docutils literal notranslate">object.__getattribute__()</code> and <code class="xref py py-meth docutils literal notranslate">type.__getattribute__()</code> make

different calls to <a class="reference internal" href="../reference/datamodel.html#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal notranslate">__get__()</code></a>. The first includes the instance and may

include the class. The second puts in <code class="docutils literal notranslate">None</code> for the instance and always

includes the class.</li>

<li>Data descriptors always override instance dictionaries.</li>

<li>Non-data descriptors may be overridden by instance dictionaries.</li>

</ul>

</section>

<h3><a class="toc-backref" href="#id22" role="doc-backlink">Automatic name notification</a><a class="headerlink" href="#automatic-name-notification" title="Link to this heading">¶</a></h3>

Sometimes it is desirable for a descriptor to know what class variable name it

was assigned to. When a new class is created, the <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal notranslate">type</code></a> metaclass

scans the dictionary of the new class. If any of the entries are descriptors

and if they define <a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate">__set_name__()</code></a>, that method is called with two

arguments. The owner is the class where the descriptor is used, and the

name is the class variable the descriptor was assigned to.

The implementation details are in <code class="xref c c-func docutils literal notranslate">type_new()</code> and

<code class="xref c c-func docutils literal notranslate">set_names()</code> in <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.14/Objects/typeobject.c">Objects/typeobject.c</a>.

Since the update logic is in <code class="xref py py-meth docutils literal notranslate">type.__new__()</code>, notifications only take

place at the time of class creation. If descriptors are added to the class

afterwards, <a class="reference internal" href="../reference/datamodel.html#object.__set_name__" title="object.__set_name__"><code class="xref py py-meth docutils literal notranslate">__set_name__()</code></a> will need to be called manually.

</section>

<h3><a class="toc-backref" href="#id23" role="doc-backlink">ORM example</a><a class="headerlink" href="#orm-example" title="Link to this heading">¶</a></h3>

The following code is a simplified skeleton showing how data descriptors could

be used to implement an <a class="reference external" href="https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping">object relational mapping</a>.

The essential idea is that the data is stored in an external database. The

Python instances only hold keys to the database's tables. Descriptors take

care of lookups or updates:

<div class="highlight-python notranslate"><div class="highlight"><pre>class Field:

self.fetch = f'SELECT {name} FROM {owner.table} WHERE {owner.key}=?;'

self.store = f'UPDATE {owner.table} SET {name}=? WHERE {owner.key}=?;'

return conn.execute(self.fetch, [obj.key]).fetchone()[0]

conn.execute(self.store, [value, obj.key])

conn.commit()

</pre></div>

</div>

We can use the <code class="xref py py-class docutils literal notranslate">Field</code> class to define <a class="reference external" href="https://en.wikipedia.org/wiki/Database_model">models</a> that describe the schema for

each table in a database:

<div class="highlight-python notranslate"><div class="highlight"><pre>class Movie:

table = 'Movies' # Table name

key = 'title' # Primary key

director = Field()

year = Field()

self.key = key

class Song:

table = 'Music'

key = 'title'

artist = Field()

year = Field()

genre = Field()

self.key = key

</pre></div>

</div>

To use the models, first connect to the database:

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

>>> conn = sqlite3.connect('entertainment.db')

</pre></div>

</div>

An interactive session shows how data is retrieved from the database and how

it can be updated:

<div class="highlight-pycon notranslate"><div class="highlight"><pre>>>> Movie('Star Wars').director

'George Lucas'

>>> jaws = Movie('Jaws')

>>> f'Released in {jaws.year} by {jaws.director}'

'Released in 1975 by Steven Spielberg'

>>> Song('Country Roads').artist

'John Denver'

>>> Movie('Star Wars').director = 'J.J. Abrams'

>>> Movie('Star Wars').director

'J.J. Abrams'

</pre></div>

</div>

</section>

<h2><a class="toc-backref" href="#id24" role="doc-backlink">Pure Python Equivalents</a><a class="headerlink" href="#pure-python-equivalents" title="Link to this heading">¶</a></h2>

The descriptor protocol is simple and offers exciting possibilities. Several

use cases are so common that they have been prepackaged into built-in tools.

Properties, bound methods, static methods, class methods, and __slots__ are

all based on the descriptor protocol.

<h3><a class="toc-backref" href="#id25" role="doc-backlink">Properties</a><a class="headerlink" href="#properties" title="Link to this heading">¶</a></h3>

Calling <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate">property()</code></a> is a succinct way of building a data descriptor that

triggers a function call upon access to an attribute. Its signature is:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>property(fget=None, fset=None, fdel=None, doc=None) -> property

</pre></div>

</div>

The documentation shows a typical use to define a managed attribute <code class="docutils literal notranslate">x</code>:

<div class="highlight-python notranslate"><div class="highlight"><pre>class C:

def getx(self): return self.__x

def setx(self, value): self.__x = value

def delx(self): del self.__x

x = property(getx, setx, delx, "I'm the 'x' property.")

</pre></div>

</div>

To see how <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal notranslate">property()</code></a> is implemented in terms of the descriptor protocol,

here is a pure Python equivalent that implements most of the core functionality:

<div class="highlight-python notranslate"><div class="highlight"><pre>class Property:

"Emulate PyProperty_Type() in Objects/descrobject.c"

def __init__(self, fget=None, fset=None, fdel=None, doc=None):

self.fget = fget

self.fset = fset

self.fdel = fdel

if doc is None and fget is not None:

doc = fget.__doc__

self.__doc__ = doc

self.__name__ = name

if obj is None:

return self

if self.fget is None:

raise AttributeError

return self.fget(obj)

if self.fset is None:

raise AttributeError

self.fset(obj, value)

def __delete__(self, obj):

if self.fdel is None:

raise AttributeError

self.fdel(obj)

def getter(self, fget):

return type(self)(fget, self.fset, self.fdel, self.__doc__)

View remainder of file in raw view

Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

descriptor.html

Latest commit

History

descriptor.html

File metadata and controls