~dkuhlman/python-training-materials/Materials

memory. The ‘<a class="reference internal" href="expressions.html#is"><code class="xref std std-keyword docutils literal">is</code></a>‘ operator compares the identity of two objects; the

<a class="reference internal" href="../library/functions.html#id" title="id"><code class="xref py py-func docutils literal">id()</code></a> function returns an integer representing its identity (currently

implemented as its address). An object’s type is also unchangeable. <a class="footnote-reference" href="#id5" id="id1">[1]</a>

An object’s type determines the operations that the object supports (e.g., “does

it have a length?”) and also defines the possible values for objects of that

type. The <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal">type()</code></a> function returns an object’s type (which is an object

itself). The value of some objects can change. Objects whose value can

change are said to be mutable; objects whose value is unchangeable once they

are created are called immutable. (The value of an immutable container object

that contains a reference to a mutable object can change when the latter’s value

is changed; however the container is still considered immutable, because the

collection of objects it contains cannot be changed. So, immutability is not

strictly the same as having an unchangeable value, it is more subtle.) An

object’s mutability is determined by its type; for instance, numbers, strings

100

and tuples are immutable, while dictionaries and lists are mutable.

101

Objects are never explicitly destroyed; however, when they become unreachable

102

they may be garbage-collected. An implementation is allowed to postpone garbage

103

collection or omit it altogether — it is a matter of implementation quality

104

how garbage collection is implemented, as long as no objects are collected that

105

are still reachable.

106

107

CPython implementation detail: CPython currently uses a reference-counting scheme with (optional) delayed

108

detection of cyclically linked garbage, which collects most objects as soon

109

as they become unreachable, but is not guaranteed to collect garbage

110

containing circular references. See the documentation of the <a class="reference internal" href="../library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal">gc</code></a>

111

module for information on controlling the collection of cyclic garbage.

112

Other implementations act differently and CPython may change.

113

Do not depend on immediate finalization of objects when they become

114

unreachable (ex: always close files).

115

</div>

116

Note that the use of the implementation’s tracing or debugging facilities may

117

keep objects alive that would normally be collectable. Also note that catching

118

an exception with a ‘<a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a>...<a class="reference internal" href="compound_stmts.html#except"><code class="xref std std-keyword docutils literal">except</code></a>‘ statement may keep

119

objects alive.

120

Some objects contain references to “external” resources such as open files or

121

windows. It is understood that these resources are freed when the object is

122

garbage-collected, but since garbage collection is not guaranteed to happen,

123

such objects also provide an explicit way to release the external resource,

124

usually a <code class="xref py py-meth docutils literal">close()</code> method. Programs are strongly recommended to explicitly

125

close such objects. The ‘<a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a>...<a class="reference internal" href="compound_stmts.html#finally"><code class="xref std std-keyword docutils literal">finally</code></a>‘ statement

126

provides a convenient way to do this.

127

Some objects contain references to other objects; these are called containers.

128

Examples of containers are tuples, lists and dictionaries. The references are

129

part of a container’s value. In most cases, when we talk about the value of a

130

container, we imply the values, not the identities of the contained objects;

131

however, when we talk about the mutability of a container, only the identities

132

of the immediately contained objects are implied. So, if an immutable container

133

(like a tuple) contains a reference to a mutable object, its value changes if

134

that mutable object is changed.

135

Types affect almost all aspects of object behavior. Even the importance of

136

object identity is affected in some sense: for immutable types, operations that

137

compute new values may actually return a reference to any existing object with

138

the same type and value, while for mutable objects this is not allowed. E.g.,

139

after <code class="docutils literal">a = 1; b = 1</code>, <code class="docutils literal">a</code> and <code class="docutils literal">b</code> may or may not refer to the same object

140

with the value one, depending on the implementation, but after <code class="docutils literal">c = []; d =

141

[]</code>, <code class="docutils literal">c</code> and <code class="docutils literal">d</code> are guaranteed to refer to two different, unique, newly

142

created empty lists. (Note that <code class="docutils literal">c = d = []</code> assigns the same object to both

143

<code class="docutils literal">c</code> and <code class="docutils literal">d</code>.)

144

</div>

145

146

<h2>3.2. The standard type hierarchy<a class="headerlink" href="#the-standard-type-hierarchy" title="Permalink to this headline">¶</a></h2>

147

Below is a list of the types that are built into Python. Extension modules

148

(written in C, Java, or other languages, depending on the implementation) can

149

define additional types. Future versions of Python may add types to the type

150

hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).

151

Some of the type descriptions below contain a paragraph listing ‘special

152

attributes.’ These are attributes that provide access to the implementation and

153

are not intended for general use. Their definition may change in the future.

154

155

156

<dd>This type has a single value. There is a single object with this value. This

157

object is accessed through the built-in name <code class="docutils literal">None</code>. It is used to signify the

158

absence of a value in many situations, e.g., it is returned from functions that

159

don’t explicitly return anything. Its truth value is false.

160

</dd>

161

<dt>NotImplemented</dt>

162

<dd>This type has a single value. There is a single object with this value. This

163

object is accessed through the built-in name <code class="docutils literal">NotImplemented</code>. Numeric methods

164

and rich comparison methods may return this value if they do not implement the

165

operation for the operands provided. (The interpreter will then try the

166

reflected operation, or some other fallback, depending on the operator.) Its

167

truth value is true.

168

</dd>

169

<dt>Ellipsis</dt>

170

<dd>This type has a single value. There is a single object with this value. This

171

object is accessed through the built-in name <code class="docutils literal">Ellipsis</code>. It is used to

172

indicate the presence of the <code class="docutils literal">...</code> syntax in a slice. Its truth value is

173

true.

174

</dd>

175

<dt><a class="reference internal" href="../library/numbers.html#numbers.Number" title="numbers.Number"><code class="xref py py-class docutils literal">numbers.Number</code></a></dt>

176

<dd>These are created by numeric literals and returned as results by arithmetic

177

operators and arithmetic built-in functions. Numeric objects are immutable;

178

once created their value never changes. Python numbers are of course strongly

179

related to mathematical numbers, but subject to the limitations of numerical

180

representation in computers.

181

Python distinguishes between integers, floating point numbers, and complex

182

numbers:

183

184

<dt><a class="reference internal" href="../library/numbers.html#numbers.Integral" title="numbers.Integral"><code class="xref py py-class docutils literal">numbers.Integral</code></a></dt>

185

<dd>These represent elements from the mathematical set of integers (positive and

186

negative).

187

There are three types of integers:

188

189

<dt>Plain integers</dt>

190

<dd>These represent numbers in the range -2147483648 through 2147483647.

191

(The range may be larger on machines with a larger natural word size,

192

but not smaller.) When the result of an operation would fall outside

193

this range, the result is normally returned as a long integer (in some

194

cases, the exception <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal">OverflowError</code></a> is raised instead). For the

195

purpose of shift and mask operations, integers are assumed to have a

196

binary, 2’s complement notation using 32 or more bits, and hiding no

197

bits from the user (i.e., all 4294967296 different bit patterns

198

correspond to different values).

199

</dd>

200

<dt>Long integers</dt>

201

<dd>These represent numbers in an unlimited range, subject to available

202

(virtual) memory only. For the purpose of shift and mask operations, a

203

binary representation is assumed, and negative numbers are represented

204

in a variant of 2’s complement which gives the illusion of an infinite

205

string of sign bits extending to the left.

206

</dd>

207

<dt>Booleans</dt>

208

<dd>These represent the truth values False and True. The two objects

209

representing the values <code class="docutils literal">False</code> and <code class="docutils literal">True</code> are the only Boolean objects.

210

The Boolean type is a subtype of plain integers, and Boolean values

211

behave like the values 0 and 1, respectively, in almost all contexts,

212

the exception being that when converted to a string, the strings

213

<code class="docutils literal">"False"</code> or <code class="docutils literal">"True"</code> are returned, respectively.

214

</dd>

215

</dl>

216

The rules for integer representation are intended to give the most

217

meaningful interpretation of shift and mask operations involving negative

218

integers and the least surprises when switching between the plain and long

219

integer domains. Any operation, if it yields a result in the plain

220

integer domain, will yield the same result in the long integer domain or

221

when using mixed operands. The switch between domains is transparent to

222

the programmer.

223

</dd>

224

<dt><a class="reference internal" href="../library/numbers.html#numbers.Real" title="numbers.Real"><code class="xref py py-class docutils literal">numbers.Real</code></a> (<a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>)</dt>

225

<dd>These represent machine-level double precision floating point numbers. You are

226

at the mercy of the underlying machine architecture (and C or Java

227

implementation) for the accepted range and handling of overflow. Python does not

228

support single-precision floating point numbers; the savings in processor and

229

memory usage that are usually the reason for using these are dwarfed by the

230

overhead of using objects in Python, so there is no reason to complicate the

231

language with two kinds of floating point numbers.

232

</dd>

233

<dt><a class="reference internal" href="../library/numbers.html#numbers.Complex" title="numbers.Complex"><code class="xref py py-class docutils literal">numbers.Complex</code></a></dt>

234

<dd>These represent complex numbers as a pair of machine-level double precision

235

floating point numbers. The same caveats apply as for floating point numbers.

236

The real and imaginary parts of a complex number <code class="docutils literal">z</code> can be retrieved through

237

the read-only attributes <code class="docutils literal">z.real</code> and <code class="docutils literal">z.imag</code>.

238

</dd>

239

</dl>

240

</dd>

241

<dt>Sequences</dt>

242

<dd>These represent finite ordered sets indexed by non-negative numbers. The

243

built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal">len()</code></a> returns the number of items of a sequence. When

244

the length of a sequence is n, the index set contains the numbers 0, 1,

245

..., n-1. Item i of sequence a is selected by <code class="docutils literal">a[i]</code>.

246

Sequences also support slicing: <code class="docutils literal">a[i:j]</code> selects all items with index k such

247

that i <code class="docutils literal"><=</code> k <code class="docutils literal"><</code> j. When used as an expression, a slice is a

248

sequence of the same type. This implies that the index set is renumbered so

249

that it starts at 0.

250

Some sequences also support “extended slicing” with a third “step” parameter:

251

<code class="docutils literal">a[i:j:k]</code> selects all items of a with index x where <code class="docutils literal">x = i + n*k</code>, n

252

<code class="docutils literal">>=</code> <code class="docutils literal">0</code> and i <code class="docutils literal"><=</code> x <code class="docutils literal"><</code> j.

253

Sequences are distinguished according to their mutability:

254

255

<dt>Immutable sequences</dt>

256

<dd>An object of an immutable sequence type cannot change once it is created. (If

257

the object contains references to other objects, these other objects may be

258

mutable and may be changed; however, the collection of objects directly

259

referenced by an immutable object cannot change.)

260

The following types are immutable sequences:

261

262

<dt>Strings</dt>

263

<dd>The items of a string are characters. There is no separate character type; a

264

character is represented by a string of one item. Characters represent (at

265

least) 8-bit bytes. The built-in functions <a class="reference internal" href="../library/functions.html#chr" title="chr"><code class="xref py py-func docutils literal">chr()</code></a> and <a class="reference internal" href="../library/functions.html#ord" title="ord"><code class="xref py py-func docutils literal">ord()</code></a> convert

266

between characters and nonnegative integers representing the byte values. Bytes

267

with the values 0–127 usually represent the corresponding ASCII values, but the

268

interpretation of values is up to the program. The string data type is also

269

used to represent arrays of bytes, e.g., to hold data read from a file.

270

(On systems whose native character set is not ASCII, strings may use EBCDIC in

271

their internal representation, provided the functions <a class="reference internal" href="../library/functions.html#chr" title="chr"><code class="xref py py-func docutils literal">chr()</code></a> and

272

<a class="reference internal" href="../library/functions.html#ord" title="ord"><code class="xref py py-func docutils literal">ord()</code></a> implement a mapping between ASCII and EBCDIC, and string comparison

273

preserves the ASCII order. Or perhaps someone can propose a better rule?)

274

</dd>

275

<dt>Unicode</dt>

276

<dd>The items of a Unicode object are Unicode code units. A Unicode code unit is

277

represented by a Unicode object of one item and can hold either a 16-bit or

278

32-bit value representing a Unicode ordinal (the maximum value for the ordinal

279

is given in <code class="docutils literal">sys.maxunicode</code>, and depends on how Python is configured at

280

compile time). Surrogate pairs may be present in the Unicode object, and will

281

be reported as two separate items. The built-in functions <a class="reference internal" href="../library/functions.html#unichr" title="unichr"><code class="xref py py-func docutils literal">unichr()</code></a> and

282

<a class="reference internal" href="../library/functions.html#ord" title="ord"><code class="xref py py-func docutils literal">ord()</code></a> convert between code units and nonnegative integers representing the

283

Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to

284

other encodings are possible through the Unicode method <code class="xref py py-meth docutils literal">encode()</code> and the

285

built-in function <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal">unicode()</code></a>.

286

</dd>

287

<dt>Tuples</dt>

288

<dd>The items of a tuple are arbitrary Python objects. Tuples of two or more items

289

are formed by comma-separated lists of expressions. A tuple of one item (a

290

‘singleton’) can be formed by affixing a comma to an expression (an expression

291

by itself does not create a tuple, since parentheses must be usable for grouping

292

of expressions). An empty tuple can be formed by an empty pair of parentheses.

293

</dd>

294

</dl>

295

</dd>

296

<dt>Mutable sequences</dt>

297

<dd>Mutable sequences can be changed after they are created. The subscription and

298

slicing notations can be used as the target of assignment and <a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal">del</code></a>

299

(delete) statements.

300

There are currently two intrinsic mutable sequence types:

301

302

<dt>Lists</dt>

303

<dd>The items of a list are arbitrary Python objects. Lists are formed by placing a

304

comma-separated list of expressions in square brackets. (Note that there are no

305

special cases needed to form lists of length 0 or 1.)

306

</dd>

307

<dt>Byte Arrays</dt>

308

<dd>A bytearray object is a mutable array. They are created by the built-in

309

<a class="reference internal" href="../library/functions.html#bytearray" title="bytearray"><code class="xref py py-func docutils literal">bytearray()</code></a> constructor. Aside from being mutable (and hence

310

unhashable), byte arrays otherwise provide the same interface and

311

functionality as immutable bytes objects.

312

</dd>

313

</dl>

314

The extension module <a class="reference internal" href="../library/array.html#module-array" title="array: Space efficient arrays of uniformly typed numeric values."><code class="xref py py-mod docutils literal">array</code></a> provides an additional example of a mutable

315

sequence type.

316

</dd>

317

</dl>

318

</dd>

319

<dt>Set types</dt>

320

<dd>These represent unordered, finite sets of unique, immutable objects. As such,

321

they cannot be indexed by any subscript. However, they can be iterated over, and

322

the built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal">len()</code></a> returns the number of items in a set. Common

323

uses for sets are fast membership testing, removing duplicates from a sequence,

324

and computing mathematical operations such as intersection, union, difference,

325

and symmetric difference.

326

For set elements, the same immutability rules apply as for dictionary keys. Note

327

that numeric types obey the normal rules for numeric comparison: if two numbers

328

compare equal (e.g., <code class="docutils literal">1</code> and <code class="docutils literal">1.0</code>), only one of them can be contained in a

329

set.

330

There are currently two intrinsic set types:

331

332

333

<dd>These represent a mutable set. They are created by the built-in <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-func docutils literal">set()</code></a>

334

constructor and can be modified afterwards by several methods, such as

335

<a class="reference internal" href="../library/stdtypes.html#set.add" title="set.add"><code class="xref py py-meth docutils literal">add()</code></a>.

336

</dd>

337

<dt>Frozen sets</dt>

338

<dd>These represent an immutable set. They are created by the built-in

339

<a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-func docutils literal">frozenset()</code></a> constructor. As a frozenset is immutable and

340

<a class="reference internal" href="../glossary.html#term-hashable">hashable</a>, it can be used again as an element of another set, or as

341

a dictionary key.

342

</dd>

343

</dl>

344

</dd>

345

<dt>Mappings</dt>

346

<dd>These represent finite sets of objects indexed by arbitrary index sets. The

347

subscript notation <code class="docutils literal">a[k]</code> selects the item indexed by <code class="docutils literal">k</code> from the mapping

348

<code class="docutils literal">a</code>; this can be used in expressions and as the target of assignments or

349

<a class="reference internal" href="simple_stmts.html#del"><code class="xref std std-keyword docutils literal">del</code></a> statements. The built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal">len()</code></a> returns the number

350

of items in a mapping.

351

There is currently a single intrinsic mapping type:

352

353

<dt>Dictionaries</dt>

354

<dd>These represent finite sets of objects indexed by nearly arbitrary values. The

355

only types of values not acceptable as keys are values containing lists or

356

dictionaries or other mutable types that are compared by value rather than by

357

object identity, the reason being that the efficient implementation of

358

dictionaries requires a key’s hash value to remain constant. Numeric types used

359

for keys obey the normal rules for numeric comparison: if two numbers compare

360

equal (e.g., <code class="docutils literal">1</code> and <code class="docutils literal">1.0</code>) then they can be used interchangeably to index

361

the same dictionary entry.

362

Dictionaries are mutable; they can be created by the <code class="docutils literal">{...}</code> notation (see

363

section <a class="reference internal" href="expressions.html#dict">Dictionary displays</a>).

364

The extension modules <a class="reference internal" href="../library/dbm.html#module-dbm" title="dbm: The standard "database" interface, based on ndbm. (Unix)"><code class="xref py py-mod docutils literal">dbm</code></a>, <a class="reference internal" href="../library/gdbm.html#module-gdbm" title="gdbm: GNU's reinterpretation of dbm. (Unix)"><code class="xref py py-mod docutils literal">gdbm</code></a>, and <a class="reference internal" href="../library/bsddb.html#module-bsddb" title="bsddb: Interface to Berkeley DB database library"><code class="xref py py-mod docutils literal">bsddb</code></a> provide

365

additional examples of mapping types.

366

</dd>

367

</dl>

368

</dd>

369

<dt>Callable types</dt>

370

<dd>These are the types to which the function call operation (see section

371

<a class="reference internal" href="expressions.html#calls">Calls</a>) can be applied:

372

373

<dt>User-defined functions</dt>

374

<dd>A user-defined function object is created by a function definition (see

375

section <a class="reference internal" href="compound_stmts.html#function">Function definitions</a>). It should be called with an argument list

376

containing the same number of items as the function’s formal parameter

377

list.

378

Special attributes:

379

380

381

382

383

384

</colgroup>

385

386

<tr class="row-odd"><th class="head">Attribute</th>

387

<th class="head">Meaning</th>

388

389

</tr>

390

</thead>

391

392

393

394

<td>The function’s documentation

395

string, or <code class="docutils literal">None</code> if

396

unavailable.</td>

397

<td>Writable</td>

398

</tr>

399

400

401

<td>The function’s name</td>

402

<td>Writable</td>

403

</tr>

404

<tr class="row-even"><td><code class="xref py py-attr docutils literal">__module__</code></td>

405

<td>The name of the module the

406

function was defined in, or

407

<code class="docutils literal">None</code> if unavailable.</td>

408

<td>Writable</td>

409

</tr>

410

<tr class="row-odd"><td><code class="xref py py-attr docutils literal">__defaults__</code>

411

<code class="xref py py-attr docutils literal">func_defaults</code></td>

412

<td>A tuple containing default

413

argument values for those

414

arguments that have defaults,

415

or <code class="docutils literal">None</code> if no arguments

416

have a default value.</td>

417

<td>Writable</td>

418

</tr>

419

420

421

<td>The code object representing

422

the compiled function body.</td>

423

<td>Writable</td>

424

</tr>

425

<tr class="row-odd"><td><code class="xref py py-attr docutils literal">__globals__</code>

426

<code class="xref py py-attr docutils literal">func_globals</code></td>

427

<td>A reference to the dictionary

428

that holds the function’s

429

global variables — the

430

global namespace of the

431

module in which the function

432

was defined.</td>

433

434

</tr>

435

436

437

<td>The namespace supporting

438

arbitrary function

439

attributes.</td>

440

<td>Writable</td>

441

</tr>

442

<tr class="row-odd"><td><code class="xref py py-attr docutils literal">__closure__</code>

443

<code class="xref py py-attr docutils literal">func_closure</code></td>

444

<td><code class="docutils literal">None</code> or a tuple of cells

445

that contain bindings for the

446

function’s free variables.</td>

447

448

</tr>

449

</tbody>

450

</table>

451

Most of the attributes labelled “Writable” check the type of the assigned value.

452

453

Changed in version 2.4: <code class="docutils literal">func_name</code> is now writable.

454

</div>

455

456

Changed in version 2.6: The double-underscore attributes <code class="docutils literal">__closure__</code>, <code class="docutils literal">__code__</code>,

457

<code class="docutils literal">__defaults__</code>, and <code class="docutils literal">__globals__</code> were introduced as aliases for

458

the corresponding <code class="docutils literal">func_*</code> attributes for forwards compatibility

459

with Python 3.

460

</div>

461

Function objects also support getting and setting arbitrary attributes, which

462

can be used, for example, to attach metadata to functions. Regular attribute

463

dot-notation is used to get and set such attributes. Note that the current

464

implementation only supports function attributes on user-defined functions.

465

Function attributes on built-in functions may be supported in the future.

466

Additional information about a function’s definition can be retrieved from its

467

code object; see the description of internal types below.

468

</dd>

469

<dt>User-defined methods</dt>

470

<dd>A user-defined method object combines a class, a class instance (or <code class="docutils literal">None</code>)

471

and any callable object (normally a user-defined function).

472

Special read-only attributes: <code class="xref py py-attr docutils literal">im_self</code> is the class instance object,

473

<code class="xref py py-attr docutils literal">im_func</code> is the function object; <code class="xref py py-attr docutils literal">im_class</code> is the class of

474

<code class="xref py py-attr docutils literal">im_self</code> for bound methods or the class that asked for the method for

475

unbound methods; <code class="xref py py-attr docutils literal">__doc__</code> is the method’s documentation (same as

476

<code class="docutils literal">im_func.__doc__</code>); <a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal">__name__</code></a> is the method name (same as

477

<code class="docutils literal">im_func.__name__</code>); <code class="xref py py-attr docutils literal">__module__</code> is the name of the module the method

478

was defined in, or <code class="docutils literal">None</code> if unavailable.

479

480

Changed in version 2.2: <code class="xref py py-attr docutils literal">im_self</code> used to refer to the class that defined the method.

481

</div>

482

483

Changed in version 2.6: For Python 3 forward-compatibility, <code class="xref py py-attr docutils literal">im_func</code> is also available as

484

<code class="xref py py-attr docutils literal">__func__</code>, and <code class="xref py py-attr docutils literal">im_self</code> as <code class="xref py py-attr docutils literal">__self__</code>.

485

</div>

486

Methods also support accessing (but not setting) the arbitrary function

487

attributes on the underlying function object.

488

User-defined method objects may be created when getting an attribute of a class

489

(perhaps via an instance of that class), if that attribute is a user-defined

490

function object, an unbound user-defined method object, or a class method

491

object. When the attribute is a user-defined method object, a new method object

492

is only created if the class from which it is being retrieved is the same as, or

493

a derived class of, the class stored in the original method object; otherwise,

494

the original method object is used as it is.

495

When a user-defined method object is created by retrieving a user-defined

496

function object from a class, its <code class="xref py py-attr docutils literal">im_self</code> attribute is <code class="docutils literal">None</code>

497

and the method object is said to be unbound. When one is created by

498

retrieving a user-defined function object from a class via one of its

499

instances, its <code class="xref py py-attr docutils literal">im_self</code> attribute is the instance, and the method

500

object is said to be bound. In either case, the new method’s

501

<code class="xref py py-attr docutils literal">im_class</code> attribute is the class from which the retrieval takes

502

place, and its <code class="xref py py-attr docutils literal">im_func</code> attribute is the original function object.

503

When a user-defined method object is created by retrieving another method object

504

from a class or instance, the behaviour is the same as for a function object,

505

except that the <code class="xref py py-attr docutils literal">im_func</code> attribute of the new instance is not the

506

original method object but its <code class="xref py py-attr docutils literal">im_func</code> attribute.

507

When a user-defined method object is created by retrieving a class method object

508

from a class or instance, its <code class="xref py py-attr docutils literal">im_self</code> attribute is the class itself, and

509

its <code class="xref py py-attr docutils literal">im_func</code> attribute is the function object underlying the class method.

510

When an unbound user-defined method object is called, the underlying function

511

(<code class="xref py py-attr docutils literal">im_func</code>) is called, with the restriction that the first argument must

512

be an instance of the proper class (<code class="xref py py-attr docutils literal">im_class</code>) or of a derived class

513

thereof.

514

When a bound user-defined method object is called, the underlying function

515

(<code class="xref py py-attr docutils literal">im_func</code>) is called, inserting the class instance (<code class="xref py py-attr docutils literal">im_self</code>) in

516

front of the argument list. For instance, when <code class="xref py py-class docutils literal">C</code> is a class which

517

contains a definition for a function <code class="xref py py-meth docutils literal">f()</code>, and <code class="docutils literal">x</code> is an instance of

518

<code class="xref py py-class docutils literal">C</code>, calling <code class="docutils literal">x.f(1)</code> is equivalent to calling <code class="docutils literal">C.f(x, 1)</code>.

519

When a user-defined method object is derived from a class method object, the

520

“class instance” stored in <code class="xref py py-attr docutils literal">im_self</code> will actually be the class itself, so

521

that calling either <code class="docutils literal">x.f(1)</code> or <code class="docutils literal">C.f(1)</code> is equivalent to calling <code class="docutils literal">f(C,1)</code>

522

where <code class="docutils literal">f</code> is the underlying function.

523

Note that the transformation from function object to (unbound or bound) method

524

object happens each time the attribute is retrieved from the class or instance.

525

In some cases, a fruitful optimization is to assign the attribute to a local

526

variable and call that local variable. Also notice that this transformation only

527

happens for user-defined functions; other callable objects (and all non-callable

528

objects) are retrieved without transformation. It is also important to note

529

that user-defined functions which are attributes of a class instance are not

530

converted to bound methods; this only happens when the function is an

531

attribute of the class.

532

</dd>

533

<dt>Generator functions</dt>

534

<dd>A function or method which uses the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal">yield</code></a> statement (see section

535

<a class="reference internal" href="simple_stmts.html#yield">The yield statement</a>) is called a generator

536

function. Such a function, when called, always returns an iterator object

537

which can be used to execute the body of the function: calling the iterator’s

538

<a class="reference internal" href="../library/stdtypes.html#iterator.next" title="iterator.next"><code class="xref py py-meth docutils literal">next()</code></a> method will cause the function to execute until

539

it provides a value

540

using the <a class="reference internal" href="simple_stmts.html#yield"><code class="xref std std-keyword docutils literal">yield</code></a> statement. When the function executes a

541

<a class="reference internal" href="simple_stmts.html#return"><code class="xref std std-keyword docutils literal">return</code></a> statement or falls off the end, a <a class="reference internal" href="../library/exceptions.html#exceptions.StopIteration" title="exceptions.StopIteration"><code class="xref py py-exc docutils literal">StopIteration</code></a>

542

exception is raised and the iterator will have reached the end of the set of

543

values to be returned.

544

</dd>

545

<dt>Built-in functions</dt>

546

<dd>A built-in function object is a wrapper around a C function. Examples of

547

built-in functions are <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal">len()</code></a> and <a class="reference internal" href="../library/math.html#math.sin" title="math.sin"><code class="xref py py-func docutils literal">math.sin()</code></a> (<a class="reference internal" href="../library/math.html#module-math" title="math: Mathematical functions (sin() etc.)."><code class="xref py py-mod docutils literal">math</code></a> is a

548

standard built-in module). The number and type of the arguments are

549

determined by the C function. Special read-only attributes:

550

<code class="xref py py-attr docutils literal">__doc__</code> is the function’s documentation string, or <code class="docutils literal">None</code> if

551

unavailable; <a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal">__name__</code></a> is the function’s name; <code class="xref py py-attr docutils literal">__self__</code> is

552

set to <code class="docutils literal">None</code> (but see the next item); <code class="xref py py-attr docutils literal">__module__</code> is the name of

553

the module the function was defined in or <code class="docutils literal">None</code> if unavailable.

554

</dd>

555

<dt>Built-in methods</dt>

556

<dd>This is really a different disguise of a built-in function, this time containing

557

an object passed to the C function as an implicit extra argument. An example of

558

a built-in method is <code class="docutils literal">alist.append()</code>, assuming alist is a list object. In

559

this case, the special read-only attribute <code class="xref py py-attr docutils literal">__self__</code> is set to the object

560

denoted by alist.

561

</dd>

562

<dt>Class Types</dt>

563

<dd>Class types, or “new-style classes,” are callable. These objects normally act

564

as factories for new instances of themselves, but variations are possible for

565

class types that override <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a>. The arguments of the call are passed

566

to <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> and, in the typical case, to <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> to initialize

567

the new instance.</dd>

568

<dt>Classic Classes</dt>

569

<dd>Class objects are described below. When a class object is called, a new class

570

instance (also described below) is created and returned. This implies a call to

571

the class’s <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method if it has one. Any arguments are passed on

572

to the <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method. If there is no <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method, the

573

class must be called without arguments.

574

</dd>

575

<dt>Class instances</dt>

576

<dd>Class instances are described below. Class instances are callable only when the

577

class has a <a class="reference internal" href="#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal">__call__()</code></a> method; <code class="docutils literal">x(arguments)</code> is a shorthand for

578

<code class="docutils literal">x.__call__(arguments)</code>.</dd>

579

</dl>

580

</dd>

581

<dt>Modules</dt>

582

<dd>Modules are imported by the <a class="reference internal" href="simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> statement (see section

583

<a class="reference internal" href="simple_stmts.html#import">The import statement</a>). A module object has a

584

namespace implemented by a dictionary object (this is the dictionary referenced

585

by the func_globals attribute of functions defined in the module). Attribute

586

references are translated to lookups in this dictionary, e.g., <code class="docutils literal">m.x</code> is

587

equivalent to <code class="docutils literal">m.__dict__["x"]</code>. A module object does not contain the code

588

object used to initialize the module (since it isn’t needed once the

589

initialization is done).

590

Attribute assignment updates the module’s namespace dictionary, e.g., <code class="docutils literal">m.x =

591

1</code> is equivalent to <code class="docutils literal">m.__dict__["x"] = 1</code>.

592

Special read-only attribute: <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> is the module’s namespace as a

593

dictionary object.

594

595

CPython implementation detail: Because of the way CPython clears module dictionaries, the module

596

dictionary will be cleared when the module falls out of scope even if the

597

dictionary still has live references. To avoid this, copy the dictionary

598

or keep the module around while using its dictionary directly.

599

</div>

600

Predefined (writable) attributes: <code class="xref py py-attr docutils literal">__name__</code> is the module’s name;

601

<code class="xref py py-attr docutils literal">__doc__</code> is the module’s documentation string, or <code class="docutils literal">None</code> if

602

unavailable; <code class="xref py py-attr docutils literal">__file__</code> is the pathname of the file from which the module

603

was loaded, if it was loaded from a file. The <code class="xref py py-attr docutils literal">__file__</code> attribute is not

604

present for C modules that are statically linked into the interpreter; for

605

extension modules loaded dynamically from a shared library, it is the pathname

606

of the shared library file.

607

</dd>

608

<dt>Classes</dt>

609

<dd>Both class types (new-style classes) and class objects (old-style/classic

610

classes) are typically created by class definitions (see section

611

<a class="reference internal" href="compound_stmts.html#class">Class definitions</a>). A class has a namespace implemented by a dictionary object.

612

Class attribute references are translated to lookups in this dictionary, e.g.,

613

<code class="docutils literal">C.x</code> is translated to <code class="docutils literal">C.__dict__["x"]</code> (although for new-style classes

614

in particular there are a number of hooks which allow for other means of

615

locating attributes). When the attribute name is not found there, the

616

attribute search continues in the base classes. For old-style classes, the

617

search is depth-first, left-to-right in the order of occurrence in the base

618

class list. New-style classes use the more complex C3 method resolution

619

order which behaves correctly even in the presence of ‘diamond’

620

inheritance structures where there are multiple inheritance paths

621

leading back to a common ancestor. Additional details on the C3 MRO used by

622

new-style classes can be found in the documentation accompanying the

623

2.3 release at <a class="reference external" href="https://www.python.org/download/releases/2.3/mro/">https://www.python.org/download/releases/2.3/mro/</a>.

624

When a class attribute reference (for class <code class="xref py py-class docutils literal">C</code>, say) would yield a

625

user-defined function object or an unbound user-defined method object whose

626

associated class is either <code class="xref py py-class docutils literal">C</code> or one of its base classes, it is

627

transformed into an unbound user-defined method object whose <code class="xref py py-attr docutils literal">im_class</code>

628

attribute is <code class="xref py py-class docutils literal">C</code>. When it would yield a class method object, it is

629

transformed into a bound user-defined method object whose

630

<code class="xref py py-attr docutils literal">im_self</code> attribute is <code class="xref py py-class docutils literal">C</code>. When it would yield a

631

static method object, it is transformed into the object wrapped by the static

632

method object. See section <a class="reference internal" href="#descriptors">Implementing Descriptors</a> for another way in which

633

attributes retrieved from a class may differ from those actually contained in

634

its <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> (note that only new-style classes support descriptors).

635

Class attribute assignments update the class’s dictionary, never the dictionary

636

of a base class.

637

A class object can be called (see above) to yield a class instance (see below).

638

Special attributes: <a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal">__name__</code></a> is the class name; <code class="xref py py-attr docutils literal">__module__</code> is

639

the module name in which the class was defined; <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> is the

640

dictionary containing the class’s namespace; <a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal">__bases__</code></a> is a

641

tuple (possibly empty or a singleton) containing the base classes, in the

642

order of their occurrence in the base class list; <code class="xref py py-attr docutils literal">__doc__</code> is the

643

class’s documentation string, or <code class="docutils literal">None</code> if undefined.

644

</dd>

645

<dt>Class instances</dt>

646

<dd>A class instance is created by calling a class object (see above). A class

647

instance has a namespace implemented as a dictionary which is the first place in

648

which attribute references are searched. When an attribute is not found there,

649

and the instance’s class has an attribute by that name, the search continues

650

with the class attributes. If a class attribute is found that is a user-defined

651

function object or an unbound user-defined method object whose associated class

652

is the class (call it <code class="xref py py-class docutils literal">C</code>) of the instance for which the attribute

653

reference was initiated or one of its bases, it is transformed into a bound

654

user-defined method object whose <code class="xref py py-attr docutils literal">im_class</code> attribute is <code class="xref py py-class docutils literal">C</code> and

655

whose <code class="xref py py-attr docutils literal">im_self</code> attribute is the instance. Static method and class method

656

objects are also transformed, as if they had been retrieved from class

657

<code class="xref py py-class docutils literal">C</code>; see above under “Classes”. See section <a class="reference internal" href="#descriptors">Implementing Descriptors</a> for

658

another way in which attributes of a class retrieved via its instances may

659

differ from the objects actually stored in the class’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a>. If no

660

class attribute is found, and the object’s class has a <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal">__getattr__()</code></a>

661

method, that is called to satisfy the lookup.

662

Attribute assignments and deletions update the instance’s dictionary, never a

663

class’s dictionary. If the class has a <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal">__setattr__()</code></a> or

664

<a class="reference internal" href="#object.__delattr__" title="object.__delattr__"><code class="xref py py-meth docutils literal">__delattr__()</code></a> method, this is called instead of updating the instance

665

dictionary directly.

666

Class instances can pretend to be numbers, sequences, or mappings if they have

667

methods with certain special names. See section <a class="reference internal" href="#specialnames">Special method names</a>.

668

Special attributes: <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> is the attribute dictionary;

669

<a class="reference internal" href="../library/stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal">__class__</code></a> is the instance’s class.

670

</dd>

671

<dt>Files</dt>

672

<dd>A file object represents an open file. File objects are created by the

673

<a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> built-in function, and also by <a class="reference internal" href="../library/os.html#os.popen" title="os.popen"><code class="xref py py-func docutils literal">os.popen()</code></a>,

674

<a class="reference internal" href="../library/os.html#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal">os.fdopen()</code></a>, and the <code class="xref py py-meth docutils literal">makefile()</code> method of socket objects (and

675

perhaps by other functions or methods provided by extension modules). The

676

objects <code class="docutils literal">sys.stdin</code>, <code class="docutils literal">sys.stdout</code> and <code class="docutils literal">sys.stderr</code> are initialized to

677

file objects corresponding to the interpreter’s standard input, output and

678

error streams. See <a class="reference internal" href="../library/stdtypes.html#bltin-file-objects">File Objects</a> for complete documentation of

679

file objects.

680

</dd>

681

<dt>Internal types</dt>

682

<dd>A few types used internally by the interpreter are exposed to the user. Their

683

definitions may change with future versions of the interpreter, but they are

684

mentioned here for completeness.

685

686

<dt>Code objects</dt>

687

<dd>Code objects represent byte-compiled executable Python code, or <a class="reference internal" href="../glossary.html#term-bytecode">bytecode</a>.

688

The difference between a code object and a function object is that the function

689

object contains an explicit reference to the function’s globals (the module in

690

which it was defined), while a code object contains no context; also the default

691

argument values are stored in the function object, not in the code object

692

(because they represent values calculated at run-time). Unlike function

693

objects, code objects are immutable and contain no references (directly or

694

indirectly) to mutable objects.

695

Special read-only attributes: <code class="xref py py-attr docutils literal">co_name</code> gives the function name;

696

<code class="xref py py-attr docutils literal">co_argcount</code> is the number of positional arguments (including arguments

697

with default values); <code class="xref py py-attr docutils literal">co_nlocals</code> is the number of local variables used

698

by the function (including arguments); <code class="xref py py-attr docutils literal">co_varnames</code> is a tuple containing

699

the names of the local variables (starting with the argument names);

700

<code class="xref py py-attr docutils literal">co_cellvars</code> is a tuple containing the names of local variables that are

701

referenced by nested functions; <code class="xref py py-attr docutils literal">co_freevars</code> is a tuple containing the

702

names of free variables; <code class="xref py py-attr docutils literal">co_code</code> is a string representing the sequence

703

of bytecode instructions; <code class="xref py py-attr docutils literal">co_consts</code> is a tuple containing the literals

704

used by the bytecode; <code class="xref py py-attr docutils literal">co_names</code> is a tuple containing the names used by

705

the bytecode; <code class="xref py py-attr docutils literal">co_filename</code> is the filename from which the code was

706

compiled; <code class="xref py py-attr docutils literal">co_firstlineno</code> is the first line number of the function;

707

<code class="xref py py-attr docutils literal">co_lnotab</code> is a string encoding the mapping from bytecode offsets to

708

line numbers (for details see the source code of the interpreter);

709

<code class="xref py py-attr docutils literal">co_stacksize</code> is the required stack size (including local variables);

710

<code class="xref py py-attr docutils literal">co_flags</code> is an integer encoding a number of flags for the interpreter.

711

The following flag bits are defined for <code class="xref py py-attr docutils literal">co_flags</code>: bit <code class="docutils literal">0x04</code> is set if

712

the function uses the <code class="docutils literal">*arguments</code> syntax to accept an arbitrary number of

713

positional arguments; bit <code class="docutils literal">0x08</code> is set if the function uses the

714

<code class="docutils literal">**keywords</code> syntax to accept arbitrary keyword arguments; bit <code class="docutils literal">0x20</code> is set

715

if the function is a generator.

716

Future feature declarations (<code class="docutils literal">from __future__ import division</code>) also use bits

717

in <code class="xref py py-attr docutils literal">co_flags</code> to indicate whether a code object was compiled with a

718

particular feature enabled: bit <code class="docutils literal">0x2000</code> is set if the function was compiled

719

with future division enabled; bits <code class="docutils literal">0x10</code> and <code class="docutils literal">0x1000</code> were used in earlier

720

versions of Python.

721

Other bits in <code class="xref py py-attr docutils literal">co_flags</code> are reserved for internal use.

722

If a code object represents a function, the first item in <code class="xref py py-attr docutils literal">co_consts</code> is

723

the documentation string of the function, or <code class="docutils literal">None</code> if undefined.

724

</dd>

725

</dl>

726

727

<dt>Frame objects</dt>

728

<dd>Frame objects represent execution frames. They may occur in traceback objects

729

(see below).

730

Special read-only attributes: <code class="xref py py-attr docutils literal">f_back</code> is to the previous stack frame

731

(towards the caller), or <code class="docutils literal">None</code> if this is the bottom stack frame;

732

<code class="xref py py-attr docutils literal">f_code</code> is the code object being executed in this frame; <code class="xref py py-attr docutils literal">f_locals</code>

733

is the dictionary used to look up local variables; <code class="xref py py-attr docutils literal">f_globals</code> is used for

734

global variables; <code class="xref py py-attr docutils literal">f_builtins</code> is used for built-in (intrinsic) names;

735

<code class="xref py py-attr docutils literal">f_restricted</code> is a flag indicating whether the function is executing in

736

restricted execution mode; <code class="xref py py-attr docutils literal">f_lasti</code> gives the precise instruction (this

737

is an index into the bytecode string of the code object).

738

Special writable attributes: <code class="xref py py-attr docutils literal">f_trace</code>, if not <code class="docutils literal">None</code>, is a function

739

called at the start of each source code line (this is used by the debugger);

740

<code class="xref py py-attr docutils literal">f_exc_type</code>, <code class="xref py py-attr docutils literal">f_exc_value</code>, <code class="xref py py-attr docutils literal">f_exc_traceback</code> represent the

741

last exception raised in the parent frame provided another exception was ever

742

raised in the current frame (in all other cases they are <code class="docutils literal">None</code>); <code class="xref py py-attr docutils literal">f_lineno</code>

743

is the current line number of the frame — writing to this from within a trace

744

function jumps to the given line (only for the bottom-most frame). A debugger

745

can implement a Jump command (aka Set Next Statement) by writing to f_lineno.

746

</dd>

747

<dt>Traceback objects</dt>

748

<dd>Traceback objects represent a stack trace of an exception. A traceback object

749

is created when an exception occurs. When the search for an exception handler

750

unwinds the execution stack, at each unwound level a traceback object is

751

inserted in front of the current traceback. When an exception handler is

752

entered, the stack trace is made available to the program. (See section

753

<a class="reference internal" href="compound_stmts.html#try">The try statement</a>.) It is accessible as <code class="docutils literal">sys.exc_traceback</code>,

754

and also as the third item of the tuple returned by <code class="docutils literal">sys.exc_info()</code>. The

755

latter is the preferred interface, since it works correctly when the program is

756

using multiple threads. When the program contains no suitable handler, the stack

757

trace is written (nicely formatted) to the standard error stream; if the

758

interpreter is interactive, it is also made available to the user as

759

<code class="docutils literal">sys.last_traceback</code>.

760

Special read-only attributes: <code class="xref py py-attr docutils literal">tb_next</code> is the next level in the stack

761

trace (towards the frame where the exception occurred), or <code class="docutils literal">None</code> if there is

762

no next level; <code class="xref py py-attr docutils literal">tb_frame</code> points to the execution frame of the current

763

level; <code class="xref py py-attr docutils literal">tb_lineno</code> gives the line number where the exception occurred;

764

<code class="xref py py-attr docutils literal">tb_lasti</code> indicates the precise instruction. The line number and last

765

instruction in the traceback may differ from the line number of its frame object

766

if the exception occurred in a <a class="reference internal" href="compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a> statement with no matching except

767

clause or with a finally clause.

768

</dd>

769

<dt>Slice objects</dt>

770

<dd>Slice objects are used to represent slices when extended slice syntax is used.

771

This is a slice using two colons, or multiple slices or ellipses separated by

772

commas, e.g., <code class="docutils literal">a[i:j:step]</code>, <code class="docutils literal">a[i:j, k:l]</code>, or <code class="docutils literal">a[..., i:j]</code>. They are

773

also created by the built-in <a class="reference internal" href="../library/functions.html#slice" title="slice"><code class="xref py py-func docutils literal">slice()</code></a> function.

774

Special read-only attributes: <code class="xref py py-attr docutils literal">start</code> is the lower bound;

775

<code class="xref py py-attr docutils literal">stop</code> is the upper bound; <code class="xref py py-attr docutils literal">step</code> is the step

776

value; each is <code class="docutils literal">None</code> if omitted. These attributes can have any type.

777

Slice objects support one method:

778

779

780

<code class="descclassname">slice.</code><code class="descname">indices</code>(self, length)<a class="headerlink" href="#slice.indices" title="Permalink to this definition">¶</a></dt>

781

<dd>This method takes a single integer argument length and computes information

782

about the extended slice that the slice object would describe if applied to a

783

sequence of length items. It returns a tuple of three integers; respectively

784

these are the start and stop indices and the step or stride length of the

785

slice. Missing or out-of-bounds indices are handled in a manner consistent with

786

regular slices.

787

788

New in version 2.3.

789

</div>

790

</dd></dl>

791

792

</dd>

793

<dt>Static method objects</dt>

794

<dd>Static method objects provide a way of defeating the transformation of function

795

objects to method objects described above. A static method object is a wrapper

796

around any other object, usually a user-defined method object. When a static

797

method object is retrieved from a class or a class instance, the object actually

798

returned is the wrapped object, which is not subject to any further

799

transformation. Static method objects are not themselves callable, although the

800

objects they wrap usually are. Static method objects are created by the built-in

801

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

802

<dt>Class method objects</dt>

803

<dd>A class method object, like a static method object, is a wrapper around another

804

object that alters the way in which that object is retrieved from classes and

805

class instances. The behaviour of class method objects upon such retrieval is

806

described above, under “User-defined methods”. Class method objects are created

807

by the built-in <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal">classmethod()</code></a> constructor.</dd>

808

</dl>

809

</dd>

810

</dl>

811

</div>

812

813

<h2>3.3. New-style and classic classes<a class="headerlink" href="#new-style-and-classic-classes" title="Permalink to this headline">¶</a></h2>

814

Classes and instances come in two flavors: old-style (or classic) and new-style.

815

Up to Python 2.1 the concept of <code class="docutils literal">class</code> was unrelated to the concept of

816

<code class="docutils literal">type</code>, and old-style classes were the only flavor available. For an

817

old-style class, the statement <code class="docutils literal">x.__class__</code> provides the class of x, but

818

<code class="docutils literal">type(x)</code> is always <code class="docutils literal"><type 'instance'></code>. This reflects the fact that all

819

old-style instances, independent of their class, are implemented with a single

820

built-in type, called <code class="docutils literal">instance</code>.

821

New-style classes were introduced in Python 2.2 to unify the concepts of

822

<code class="docutils literal">class</code> and <code class="docutils literal">type</code>. A new-style class is simply a user-defined type,

823

no more, no less. If x is an instance of a new-style class, then <code class="docutils literal">type(x)</code>

824

is typically the same as <code class="docutils literal">x.__class__</code> (although this is not guaranteed – a

825

new-style class instance is permitted to override the value returned for

826

<code class="docutils literal">x.__class__</code>).

827

The major motivation for introducing new-style classes is to provide a unified

828

object model with a full meta-model. It also has a number of practical

829

benefits, like the ability to subclass most built-in types, or the introduction

830

of “descriptors”, which enable computed properties.

831

For compatibility reasons, classes are still old-style by default. New-style

832

classes are created by specifying another new-style class (i.e. a type) as a

833

parent class, or the “top-level type” <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a> if no other parent is

834

needed. The behaviour of new-style classes differs from that of old-style

835

classes in a number of important details in addition to what <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal">type()</code></a>

836

returns. Some of these changes are fundamental to the new object model, like

837

the way special methods are invoked. Others are “fixes” that could not be

838

implemented before for compatibility concerns, like the method resolution order

839

in case of multiple inheritance.

840

While this manual aims to provide comprehensive coverage of Python’s class

841

mechanics, it may still be lacking in some areas when it comes to its coverage

842

of new-style classes. Please see <a class="reference external" href="https://www.python.org/doc/newstyle/">https://www.python.org/doc/newstyle/</a> for

843

sources of additional information.

844

Old-style classes are removed in Python 3, leaving only new-style classes.

845

</div>

846

847

<h2>3.4. Special method names<a class="headerlink" href="#special-method-names" title="Permalink to this headline">¶</a></h2>

848

A class can implement certain operations that are invoked by special syntax

849

(such as arithmetic operations or subscripting and slicing) by defining methods

850

with special names. This is Python’s approach to operator overloading,

851

allowing classes to define their own behavior with respect to language

852

operators. For instance, if a class defines a method named <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>,

853

and <code class="docutils literal">x</code> is an instance of this class, then <code class="docutils literal">x[i]</code> is roughly equivalent

854

to <code class="docutils literal">x.__getitem__(i)</code> for old-style classes and <code class="docutils literal">type(x).__getitem__(x, i)</code>

855

for new-style classes. Except where mentioned, attempts to execute an

856

operation raise an exception when no appropriate method is defined (typically

857

<a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a> or <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a>).

858

When implementing a class that emulates any built-in type, it is important that

859

the emulation only be implemented to the degree that it makes sense for the

860

object being modelled. For example, some sequences may work well with retrieval

861

of individual elements, but extracting a slice may not make sense. (One example

862

of this is the <code class="xref py py-class docutils literal">NodeList</code> interface in the W3C’s Document

863

Object Model.)

864

865

<h3>3.4.1. Basic customization<a class="headerlink" href="#basic-customization" title="Permalink to this headline">¶</a></h3>

866

867

868

<code class="descclassname">object.</code><code class="descname">__new__</code>(cls[, ...])<a class="headerlink" href="#object.__new__" title="Permalink to this definition">¶</a></dt>

869

<dd>Called to create a new instance of class cls. <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> is a static

870

method (special-cased so you need not declare it as such) that takes the class

871

of which an instance was requested as its first argument. The remaining

872

arguments are those passed to the object constructor expression (the call to the

873

class). The return value of <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> should be the new object instance

874

(usually an instance of cls).

875

Typical implementations create a new instance of the class by invoking the

876

superclass’s <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> method using <code class="docutils literal">super(currentclass,

877

cls).__new__(cls[, ...])</code> with appropriate arguments and then modifying the

878

newly-created instance as necessary before returning it.

879

If <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> returns an instance of cls, then the new instance’s

880

<a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method will be invoked like <code class="docutils literal">__init__(self[, ...])</code>, where

881

self is the new instance and the remaining arguments are the same as were

882

passed to <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a>.

883

If <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> does not return an instance of cls, then the new instance’s

884

885

<a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> is intended mainly to allow subclasses of immutable types (like

886

int, str, or tuple) to customize instance creation. It is also commonly

887

overridden in custom metaclasses in order to customize class creation.

888

</dd></dl>

889

890

891

892

<code class="descclassname">object.</code><code class="descname">__init__</code>(self[, ...])<a class="headerlink" href="#object.__init__" title="Permalink to this definition">¶</a></dt>

893

<dd>Called after the instance has been created (by <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a>), but before

894

it is returned to the caller. The arguments are those passed to the

895

class constructor expression. If a base class has an <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method,

896

the derived class’s <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method, if any, must explicitly call it to

897

ensure proper initialization of the base class part of the instance; for

898

example: <code class="docutils literal">BaseClass.__init__(self, [args...])</code>.

899

Because <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> and <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> work together in constructing

900

objects (<a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> to create it, and <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> to customise it),

901

no non-<code class="docutils literal">None</code> value may be returned by <a class="reference internal" href="#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a>; doing so will

902

cause a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> to be raised at runtime.

903

</dd></dl>

904

905

906

907

<code class="descclassname">object.</code><code class="descname">__del__</code>(self)<a class="headerlink" href="#object.__del__" title="Permalink to this definition">¶</a></dt>

908

<dd>Called when the instance is about to be destroyed. This is also called a

909

destructor. If a base class has a <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> method, the derived class’s

910

<a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> method, if any, must explicitly call it to ensure proper

911

deletion of the base class part of the instance. Note that it is possible

912

(though not recommended!) for the <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> method to postpone destruction

913

of the instance by creating a new reference to it. It may then be called at a

914

later time when this new reference is deleted. It is not guaranteed that

915

916

interpreter exits.

917

918

Note

919

<code class="docutils literal">del x</code> doesn’t directly call <code class="docutils literal">x.__del__()</code> — the former decrements

920

the reference count for <code class="docutils literal">x</code> by one, and the latter is only called when

921

<code class="docutils literal">x</code>‘s reference count reaches zero. Some common situations that may

922

prevent the reference count of an object from going to zero include:

923

circular references between objects (e.g., a doubly-linked list or a tree

924

data structure with parent and child pointers); a reference to the object

925

on the stack frame of a function that caught an exception (the traceback

926

stored in <code class="docutils literal">sys.exc_traceback</code> keeps the stack frame alive); or a

927

reference to the object on the stack frame that raised an unhandled

928

exception in interactive mode (the traceback stored in

929

<code class="docutils literal">sys.last_traceback</code> keeps the stack frame alive). The first situation

930

can only be remedied by explicitly breaking the cycles; the latter two

931

situations can be resolved by storing <code class="docutils literal">None</code> in <code class="docutils literal">sys.exc_traceback</code> or

932

<code class="docutils literal">sys.last_traceback</code>. Circular references which are garbage are

933

detected when the option cycle detector is enabled (it’s on by default),

934

but can only be cleaned up if there are no Python-level <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a>

935

methods involved. Refer to the documentation for the <a class="reference internal" href="../library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal">gc</code></a> module for

936

more information about how <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> methods are handled by the

937

cycle detector, particularly the description of the <code class="docutils literal">garbage</code> value.

938

</div>

939

940

Warning

941

Due to the precarious circumstances under which <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> methods are

942

invoked, exceptions that occur during their execution are ignored, and a warning

943

is printed to <code class="docutils literal">sys.stderr</code> instead. Also, when <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> is invoked in

944

response to a module being deleted (e.g., when execution of the program is

945

done), other globals referenced by the <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> method may already have

946

been deleted or in the process of being torn down (e.g. the import

947

machinery shutting down). For this reason, <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> methods

948

should do the absolute

949

minimum needed to maintain external invariants. Starting with version 1.5,

950

Python guarantees that globals whose name begins with a single underscore are

951

deleted from their module before other globals are deleted; if no other

952

references to such globals exist, this may help in assuring that imported

953

modules are still available at the time when the <a class="reference internal" href="#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal">__del__()</code></a> method is

954

called.

955

</div>

956

See also the <a class="reference internal" href="../using/cmdline.html#cmdoption-R"><code class="xref std std-option docutils literal">-R</code></a> command-line option.

957

</dd></dl>

958

959

960

961

<code class="descclassname">object.</code><code class="descname">__repr__</code>(self)<a class="headerlink" href="#object.__repr__" title="Permalink to this definition">¶</a></dt>

962

<dd>Called by the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal">repr()</code></a> built-in function and by string conversions (reverse

963

quotes) to compute the “official” string representation of an object. If at all

964

possible, this should look like a valid Python expression that could be used to

965

recreate an object with the same value (given an appropriate environment). If

966

this is not possible, a string of the form <code class="docutils literal"><...some useful description...></code>

967

should be returned. The return value must be a string object. If a class

968

defines <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal">__repr__()</code></a> but not <a class="reference internal" href="#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal">__str__()</code></a>, then <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal">__repr__()</code></a> is also

969

used when an “informal” string representation of instances of that class is

970

required.

971

This is typically used for debugging, so it is important that the representation

972

is information-rich and unambiguous.

973

</dd></dl>

974

975

976

977

<code class="descclassname">object.</code><code class="descname">__str__</code>(self)<a class="headerlink" href="#object.__str__" title="Permalink to this definition">¶</a></dt>

978

<dd>Called by the <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal">str()</code></a> built-in function and by the <a class="reference internal" href="simple_stmts.html#print"><code class="xref std std-keyword docutils literal">print</code></a>

979

statement to compute the “informal” string representation of an object. This

980

differs from <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal">__repr__()</code></a> in that it does not have to be a valid Python

981

expression: a more convenient or concise representation may be used instead.

982

The return value must be a string object.

983

</dd></dl>

984

985

986

987

<code class="descclassname">object.</code><code class="descname">__lt__</code>(self, other)<a class="headerlink" href="#object.__lt__" title="Permalink to this definition">¶</a></dt>

988

989

<code class="descclassname">object.</code><code class="descname">__le__</code>(self, other)<a class="headerlink" href="#object.__le__" title="Permalink to this definition">¶</a></dt>

990

991

<code class="descclassname">object.</code><code class="descname">__eq__</code>(self, other)<a class="headerlink" href="#object.__eq__" title="Permalink to this definition">¶</a></dt>

992

993

<code class="descclassname">object.</code><code class="descname">__ne__</code>(self, other)<a class="headerlink" href="#object.__ne__" title="Permalink to this definition">¶</a></dt>

994

995

<code class="descclassname">object.</code><code class="descname">__gt__</code>(self, other)<a class="headerlink" href="#object.__gt__" title="Permalink to this definition">¶</a></dt>

996

997

<code class="descclassname">object.</code><code class="descname">__ge__</code>(self, other)<a class="headerlink" href="#object.__ge__" title="Permalink to this definition">¶</a></dt>

998

999

New in version 2.1.

1000

</div>

1001

These are the so-called “rich comparison” methods, and are called for comparison

1002

operators in preference to <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> below. The correspondence between

1003

operator symbols and method names is as follows: <code class="docutils literal">x<y</code> calls <code class="docutils literal">x.__lt__(y)</code>,

1004

<code class="docutils literal">x<=y</code> calls <code class="docutils literal">x.__le__(y)</code>, <code class="docutils literal">x==y</code> calls <code class="docutils literal">x.__eq__(y)</code>, <code class="docutils literal">x!=y</code> and

1005

<code class="docutils literal">x<>y</code> call <code class="docutils literal">x.__ne__(y)</code>, <code class="docutils literal">x>y</code> calls <code class="docutils literal">x.__gt__(y)</code>, and <code class="docutils literal">x>=y</code> calls

1006

<code class="docutils literal">x.__ge__(y)</code>.

1007

A rich comparison method may return the singleton <code class="docutils literal">NotImplemented</code> if it does

1008

not implement the operation for a given pair of arguments. By convention,

1009

<code class="docutils literal">False</code> and <code class="docutils literal">True</code> are returned for a successful comparison. However, these

1010

methods can return any value, so if the comparison operator is used in a Boolean

1011

context (e.g., in the condition of an <code class="docutils literal">if</code> statement), Python will call

1012

<a class="reference internal" href="../library/functions.html#bool" title="bool"><code class="xref py py-func docutils literal">bool()</code></a> on the value to determine if the result is true or false.

1013

There are no implied relationships among the comparison operators. The truth

1014

of <code class="docutils literal">x==y</code> does not imply that <code class="docutils literal">x!=y</code> is false. Accordingly, when

1015

defining <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a>, one should also define <a class="reference internal" href="#object.__ne__" title="object.__ne__"><code class="xref py py-meth docutils literal">__ne__()</code></a> so that the

1016

operators will behave as expected. See the paragraph on <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> for

1017

some important notes on creating <a class="reference internal" href="../glossary.html#term-hashable">hashable</a> objects which support

1018

custom comparison operations and are usable as dictionary keys.

1019

There are no swapped-argument versions of these methods (to be used when the

1020

left argument does not support the operation but the right argument does);

1021

rather, <a class="reference internal" href="#object.__lt__" title="object.__lt__"><code class="xref py py-meth docutils literal">__lt__()</code></a> and <a class="reference internal" href="#object.__gt__" title="object.__gt__"><code class="xref py py-meth docutils literal">__gt__()</code></a> are each other’s reflection,

1022

<a class="reference internal" href="#object.__le__" title="object.__le__"><code class="xref py py-meth docutils literal">__le__()</code></a> and <a class="reference internal" href="#object.__ge__" title="object.__ge__"><code class="xref py py-meth docutils literal">__ge__()</code></a> are each other’s reflection, and

1023

<a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> and <a class="reference internal" href="#object.__ne__" title="object.__ne__"><code class="xref py py-meth docutils literal">__ne__()</code></a> are their own reflection.

1024

Arguments to rich comparison methods are never coerced.

1025

To automatically generate ordering operations from a single root operation,

1026

see <a class="reference internal" href="../library/functools.html#functools.total_ordering" title="functools.total_ordering"><code class="xref py py-func docutils literal">functools.total_ordering()</code></a>.

1027

</dd></dl>

1028

1029

1030

1031

<code class="descclassname">object.</code><code class="descname">__cmp__</code>(self, other)<a class="headerlink" href="#object.__cmp__" title="Permalink to this definition">¶</a></dt>

1032

<dd>Called by comparison operations if rich comparison (see above) is not

1033

defined. Should return a negative integer if <code class="docutils literal">self < other</code>, zero if

1034

<code class="docutils literal">self == other</code>, a positive integer if <code class="docutils literal">self > other</code>. If no

1035

<a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a>, <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> or <a class="reference internal" href="#object.__ne__" title="object.__ne__"><code class="xref py py-meth docutils literal">__ne__()</code></a> operation is defined, class

1036

instances are compared by object identity (“address”). See also the

1037

description of <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> for some important notes on creating

1038

<a class="reference internal" href="../glossary.html#term-hashable">hashable</a> objects which support custom comparison operations and are

1039

usable as dictionary keys. (Note: the restriction that exceptions are not

1040

propagated by <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> has been removed since Python 1.5.)

1041

</dd></dl>

1042

1043

1044

1045

<code class="descclassname">object.</code><code class="descname">__rcmp__</code>(self, other)<a class="headerlink" href="#object.__rcmp__" title="Permalink to this definition">¶</a></dt>

1046

1047

Changed in version 2.1: No longer supported.

1048

</div>

1049

</dd></dl>

1050

1051

1052

1053

<code class="descclassname">object.</code><code class="descname">__hash__</code>(self)<a class="headerlink" href="#object.__hash__" title="Permalink to this definition">¶</a></dt>

1054

<dd>Called by built-in function <a class="reference internal" href="../library/functions.html#hash" title="hash"><code class="xref py py-func docutils literal">hash()</code></a> and for operations on members of

1055

hashed collections including <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal">set</code></a>, <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal">frozenset</code></a>, and

1056

<a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal">dict</code></a>. <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> should return an integer. The only required

1057

property is that objects which compare equal have the same hash value; it is

1058

advised to somehow mix together (e.g. using exclusive or) the hash values for

1059

the components of the object that also play a part in comparison of objects.

1060

If a class does not define a <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> or <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> method it

1061

should not define a <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> operation either; if it defines

1062

<a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> or <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> but not <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a>, its instances

1063

will not be usable in hashed collections. If a class defines mutable objects

1064

and implements a <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> or <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> method, it should not

1065

implement <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a>, since hashable collection implementations require

1066

that an object’s hash value is immutable (if the object’s hash value changes,

1067

it will be in the wrong hash bucket).

1068

User-defined classes have <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> and <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> methods

1069

by default; with them, all objects compare unequal (except with themselves)

1070

and <code class="docutils literal">x.__hash__()</code> returns a result derived from <code class="docutils literal">id(x)</code>.

1071

Classes which inherit a <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> method from a parent class but

1072

change the meaning of <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a> or <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> such that the hash

1073

value returned is no longer appropriate (e.g. by switching to a value-based

1074

concept of equality instead of the default identity based equality) can

1075

explicitly flag themselves as being unhashable by setting <code class="docutils literal">__hash__ = None</code>

1076

in the class definition. Doing so means that not only will instances of the

1077

class raise an appropriate <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> when a program attempts to

1078

retrieve their hash value, but they will also be correctly identified as

1079

unhashable when checking <code class="docutils literal">isinstance(obj, collections.Hashable)</code> (unlike

1080

classes which define their own <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> to explicitly raise

1081

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

1082

1083

Changed in version 2.5: <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> may now also return a long integer object; the 32-bit

1084

integer is then derived from the hash of that object.

1085

</div>

1086

1087

Changed in version 2.6: <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-attr docutils literal">__hash__</code></a> may now be set to <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> to explicitly flag

1088

instances of a class as unhashable.

1089

</div>

1090

</dd></dl>

1091

1092

1093

1094

<code class="descclassname">object.</code><code class="descname">__nonzero__</code>(self)<a class="headerlink" href="#object.__nonzero__" title="Permalink to this definition">¶</a></dt>

1095

<dd>Called to implement truth value testing and the built-in operation <code class="docutils literal">bool()</code>;

1096

should return <code class="docutils literal">False</code> or <code class="docutils literal">True</code>, or their integer equivalents <code class="docutils literal">0</code> or

1097

<code class="docutils literal">1</code>. When this method is not defined, <a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> is called, if it is

1098

defined, and the object is considered true if its result is nonzero.

1099

If a class defines neither <a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> nor <a class="reference internal" href="#object.__nonzero__" title="object.__nonzero__"><code class="xref py py-meth docutils literal">__nonzero__()</code></a>, all its

1100

instances are considered true.

1101

</dd></dl>

1102

1103

1104

1105

<code class="descclassname">object.</code><code class="descname">__unicode__</code>(self)<a class="headerlink" href="#object.__unicode__" title="Permalink to this definition">¶</a></dt>

1106

<dd>Called to implement <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal">unicode()</code></a> built-in; should return a Unicode object.

1107

When this method is not defined, string conversion is attempted, and the result

1108

of string conversion is converted to Unicode using the system default encoding.

1109

</dd></dl>

1110

1111

</div>

1112

1113

<h3>3.4.2. Customizing attribute access<a class="headerlink" href="#customizing-attribute-access" title="Permalink to this headline">¶</a></h3>

1114

The following methods can be defined to customize the meaning of attribute

1115

access (use of, assignment to, or deletion of <code class="docutils literal">x.name</code>) for class instances.

1116

1117

1118

<code class="descclassname">object.</code><code class="descname">__getattr__</code>(self, name)<a class="headerlink" href="#object.__getattr__" title="Permalink to this definition">¶</a></dt>

1119

<dd>Called when an attribute lookup has not found the attribute in the usual places

1120

(i.e. it is not an instance attribute nor is it found in the class tree for

1121

<code class="docutils literal">self</code>). <code class="docutils literal">name</code> is the attribute name. This method should return the

1122

(computed) attribute value or raise an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a> exception.

1123

Note that if the attribute is found through the normal mechanism,

1124

1125

<a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal">__getattr__()</code></a> and <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal">__setattr__()</code></a>.) This is done both for efficiency

1126

reasons and because otherwise <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal">__getattr__()</code></a> would have no way to access

1127

other attributes of the instance. Note that at least for instance variables,

1128

you can fake total control by not inserting any values in the instance attribute

1129

dictionary (but instead inserting them in another object). See the

1130

<a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal">__getattribute__()</code></a> method below for a way to actually get total control in

1131

new-style classes.

1132

</dd></dl>

1133

1134

1135

1136

<code class="descclassname">object.</code><code class="descname">__setattr__</code>(self, name, value)<a class="headerlink" href="#object.__setattr__" title="Permalink to this definition">¶</a></dt>

1137

<dd>Called when an attribute assignment is attempted. This is called instead of the

1138

normal mechanism (i.e. store the value in the instance dictionary). name is

1139

the attribute name, value is the value to be assigned to it.

1140

If <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal">__setattr__()</code></a> wants to assign to an instance attribute, it should not

1141

simply execute <code class="docutils literal">self.name = value</code> — this would cause a recursive call to

1142

itself. Instead, it should insert the value in the dictionary of instance

1143

attributes, e.g., <code class="docutils literal">self.__dict__[name] = value</code>. For new-style classes,

1144

rather than accessing the instance dictionary, it should call the base class

1145

method with the same name, for example, <code class="docutils literal">object.__setattr__(self, name,

1146

value)</code>.

1147

</dd></dl>

1148

1149

1150

1151

<code class="descclassname">object.</code><code class="descname">__delattr__</code>(self, name)<a class="headerlink" href="#object.__delattr__" title="Permalink to this definition">¶</a></dt>

1152

<dd>Like <a class="reference internal" href="#object.__setattr__" title="object.__setattr__"><code class="xref py py-meth docutils literal">__setattr__()</code></a> but for attribute deletion instead of assignment. This

1153

should only be implemented if <code class="docutils literal">del obj.name</code> is meaningful for the object.

1154

</dd></dl>

1155

1156

1157

<h4>3.4.2.1. More attribute access for new-style classes<a class="headerlink" href="#more-attribute-access-for-new-style-classes" title="Permalink to this headline">¶</a></h4>

1158

The following methods only apply to new-style classes.

1159

1160

1161

<code class="descclassname">object.</code><code class="descname">__getattribute__</code>(self, name)<a class="headerlink" href="#object.__getattribute__" title="Permalink to this definition">¶</a></dt>

1162

<dd>Called unconditionally to implement attribute accesses for instances of the

1163

class. If the class also defines <a class="reference internal" href="#object.__getattr__" title="object.__getattr__"><code class="xref py py-meth docutils literal">__getattr__()</code></a>, the latter will not be

1164

called unless <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal">__getattribute__()</code></a> either calls it explicitly or raises an

1165

1166

or raise an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a> exception. In order to avoid infinite

1167

recursion in this method, its implementation should always call the base class

1168

method with the same name to access any attributes it needs, for example,

1169

<code class="docutils literal">object.__getattribute__(self, name)</code>.

1170

1171

Note

1172

This method may still be bypassed when looking up special methods as the

1173

result of implicit invocation via language syntax or built-in functions.

1174

See <a class="reference internal" href="#new-style-special-lookup">Special method lookup for new-style classes</a>.

1175

</div>

1176

</dd></dl>

1177

1178

</div>

1179

1180

<h4>3.4.2.2. Implementing Descriptors<a class="headerlink" href="#implementing-descriptors" title="Permalink to this headline">¶</a></h4>

1181

The following methods only apply when an instance of the class containing the

1182

method (a so-called descriptor class) appears in an owner class (the

1183

descriptor must be in either the owner’s class dictionary or in the class

1184

dictionary for one of its parents). In the examples below, “the attribute”

1185

refers to the attribute whose name is the key of the property in the owner

1186

class’ <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a>.

1187

1188

1189

<code class="descclassname">object.</code><code class="descname">__get__</code>(self, instance, owner)<a class="headerlink" href="#object.__get__" title="Permalink to this definition">¶</a></dt>

1190

<dd>Called to get the attribute of the owner class (class attribute access) or of an

1191

instance of that class (instance attribute access). owner is always the owner

1192

class, while instance is the instance that the attribute was accessed through,

1193

or <code class="docutils literal">None</code> when the attribute is accessed through the owner. This method

1194

should return the (computed) attribute value or raise an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a>

1195

exception.

1196

</dd></dl>

1197

1198

1199

1200

<code class="descclassname">object.</code><code class="descname">__set__</code>(self, instance, value)<a class="headerlink" href="#object.__set__" title="Permalink to this definition">¶</a></dt>

1201

<dd>Called to set the attribute on an instance instance of the owner class to a

1202

new value, value.

1203

</dd></dl>

1204

1205

1206

1207

<code class="descclassname">object.</code><code class="descname">__delete__</code>(self, instance)<a class="headerlink" href="#object.__delete__" title="Permalink to this definition">¶</a></dt>

1208

<dd>Called to delete the attribute on an instance instance of the owner class.

1209

</dd></dl>

1210

1211

</div>

1212

1213

<h4>3.4.2.3. Invoking Descriptors<a class="headerlink" href="#invoking-descriptors" title="Permalink to this headline">¶</a></h4>

1214

In general, a descriptor is an object attribute with “binding behavior”, one

1215

whose attribute access has been overridden by methods in the descriptor

1216

protocol: <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a>, <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal">__set__()</code></a>, and <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal">__delete__()</code></a>. If any of

1217

those methods are defined for an object, it is said to be a descriptor.

1218

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

1219

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

1220

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

1221

continuing through the base classes of <code class="docutils literal">type(a)</code> excluding metaclasses.

1222

However, if the looked-up value is an object defining one of the descriptor

1223

methods, then Python may override the default behavior and invoke the descriptor

1224

method instead. Where this occurs in the precedence chain depends on which

1225

descriptor methods were defined and how they were called. Note that descriptors

1226

are only invoked for new style objects or classes (ones that subclass

1227

<a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal">object()</code></a> or <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-class docutils literal">type()</code></a>).

1228

The starting point for descriptor invocation is a binding, <code class="docutils literal">a.x</code>. How the

1229

arguments are assembled depends on <code class="docutils literal">a</code>:

1230

1231

<dt>Direct Call</dt>

1232

<dd>The simplest and least common call is when user code directly invokes a

1233

descriptor method: <code class="docutils literal">x.__get__(a)</code>.</dd>

1234

<dt>Instance Binding</dt>

1235

<dd>If binding to a new-style object instance, <code class="docutils literal">a.x</code> is transformed into the call:

1236

1237

<dt>Class Binding</dt>

1238

<dd>If binding to a new-style class, <code class="docutils literal">A.x</code> is transformed into the call:

1239

1240

<dt>Super Binding</dt>

1241

<dd>If <code class="docutils literal">a</code> is an instance of <a class="reference internal" href="../library/functions.html#super" title="super"><code class="xref py py-class docutils literal">super</code></a>, then the binding <code class="docutils literal">super(B,

1242

obj).m()</code> searches <code class="docutils literal">obj.__class__.__mro__</code> for the base class <code class="docutils literal">A</code>

1243

immediately preceding <code class="docutils literal">B</code> and then invokes the descriptor with the call:

1244

<code class="docutils literal">A.__dict__['m'].__get__(obj, obj.__class__)</code>.</dd>

1245

</dl>

1246

For instance bindings, the precedence of descriptor invocation depends on the

1247

which descriptor methods are defined. A descriptor can define any combination

1248

of <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a>, <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal">__set__()</code></a> and <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal">__delete__()</code></a>. If it does not

1249

define <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a>, then accessing the attribute will return the descriptor

1250

object itself unless there is a value in the object’s instance dictionary. If

1251

the descriptor defines <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal">__set__()</code></a> and/or <a class="reference internal" href="#object.__delete__" title="object.__delete__"><code class="xref py py-meth docutils literal">__delete__()</code></a>, it is a data

1252

descriptor; if it defines neither, it is a non-data descriptor. Normally, data

1253

descriptors define both <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a> and <a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal">__set__()</code></a>, while non-data

1254

descriptors have just the <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a> method. Data descriptors with

1255

<a class="reference internal" href="#object.__set__" title="object.__set__"><code class="xref py py-meth docutils literal">__set__()</code></a> and <a class="reference internal" href="#object.__get__" title="object.__get__"><code class="xref py py-meth docutils literal">__get__()</code></a> defined always override a redefinition in an

1256

instance dictionary. In contrast, non-data descriptors can be overridden by

1257

instances.

1258

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

1259

implemented as non-data descriptors. Accordingly, instances can redefine and

1260

override methods. This allows individual instances to acquire behaviors that

1261

differ from other instances of the same class.

1262

The <a class="reference internal" href="../library/functions.html#property" title="property"><code class="xref py py-func docutils literal">property()</code></a> function is implemented as a data descriptor. Accordingly,

1263

instances cannot override the behavior of a property.

1264

</div>

1265

1266

<h4>3.4.2.4. __slots__<a class="headerlink" href="#slots" title="Permalink to this headline">¶</a></h4>

1267

By default, instances of both old and new-style classes have a dictionary for

1268

attribute storage. This wastes space for objects having very few instance

1269

variables. The space consumption can become acute when creating large numbers

1270

of instances.

1271

The default can be overridden by defining __slots__ in a new-style class

1272

definition. The __slots__ declaration takes a sequence of instance variables

1273

and reserves just enough space in each instance to hold a value for each

1274

variable. Space is saved because __dict__ is not created for each instance.

1275

1276

1277

<code class="descname">__slots__</code><a class="headerlink" href="#__slots__" title="Permalink to this definition">¶</a></dt>

1278

<dd>This class variable can be assigned a string, iterable, or sequence of strings

1279

with variable names used by instances. If defined in a new-style class,

1280

__slots__ reserves space for the declared variables and prevents the automatic

1281

creation of __dict__ and __weakref__ for each instance.

1282

1283

New in version 2.2.

1284

</div>

1285

</dd></dl>

1286

1287

Notes on using __slots__

1288

<ul>

1289

<li>When inheriting from a class without __slots__, the __dict__ attribute of

1290

that class will always be accessible, so a __slots__ definition in the

1291

subclass is meaningless.

1292

</li>

1293

<li>Without a __dict__ variable, instances cannot be assigned new variables not

1294

listed in the __slots__ definition. Attempts to assign to an unlisted

1295

variable name raises <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a>. If dynamic assignment of new

1296

variables is desired, then add <code class="docutils literal">'__dict__'</code> to the sequence of strings in the

1297

__slots__ declaration.

1298

1299

Changed in version 2.3: Previously, adding <code class="docutils literal">'__dict__'</code> to the __slots__ declaration would not

1300

enable the assignment of new attributes not specifically listed in the sequence

1301

of instance variable names.

1302

</div>

1303

</li>

1304

<li>Without a __weakref__ variable for each instance, classes defining

1305

__slots__ do not support weak references to its instances. If weak reference

1306

support is needed, then add <code class="docutils literal">'__weakref__'</code> to the sequence of strings in the

1307

__slots__ declaration.

1308

1309

Changed in version 2.3: Previously, adding <code class="docutils literal">'__weakref__'</code> to the __slots__ declaration would not

1310

enable support for weak references.

1311

</div>

1312

</li>

1313

<li>__slots__ are implemented at the class level by creating descriptors

1314

(<a class="reference internal" href="#descriptors">Implementing Descriptors</a>) for each variable name. As a result, class attributes

1315

cannot be used to set default values for instance variables defined by

1316

__slots__; otherwise, the class attribute would overwrite the descriptor

1317

assignment.

1318

</li>

1319

<li>The action of a __slots__ declaration is limited to the class where it is

1320

defined. As a result, subclasses will have a __dict__ unless they also define

1321

__slots__ (which must only contain names of any additional slots).

1322

</li>

1323

<li>If a class defines a slot also defined in a base class, the instance variable

1324

defined by the base class slot is inaccessible (except by retrieving its

1325

descriptor directly from the base class). This renders the meaning of the

1326

program undefined. In the future, a check may be added to prevent this.

1327

</li>

1328

<li>Nonempty __slots__ does not work for classes derived from “variable-length”

1329

built-in types such as <a class="reference internal" href="../library/functions.html#long" title="long"><code class="xref py py-class docutils literal">long</code></a>, <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> and <a class="reference internal" href="../library/functions.html#tuple" title="tuple"><code class="xref py py-class docutils literal">tuple</code></a>.

1330

</li>

1331

<li>Any non-string iterable may be assigned to __slots__. Mappings may also be

1332

used; however, in the future, special meaning may be assigned to the values

1333

corresponding to each key.

1334

</li>

1335

<li>__class__ assignment works only if both classes have the same __slots__.

1336

1337

Changed in version 2.6: Previously, __class__ assignment raised an error if either new or old class

1338

had __slots__.

1339

</div>

1340

</li>

1341

</ul>

1342

</div>

1343

</div>

1344

1345

<h3>3.4.3. Customizing class creation<a class="headerlink" href="#customizing-class-creation" title="Permalink to this headline">¶</a></h3>

1346

By default, new-style classes are constructed using <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal">type()</code></a>. A class

1347

definition is read into a separate namespace and the value of class name is

1348

bound to the result of <code class="docutils literal">type(name, bases, dict)</code>.

1349

When the class definition is read, if __metaclass__ is defined then the

1350

callable assigned to it will be called instead of <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-func docutils literal">type()</code></a>. This allows

1351

classes or functions to be written which monitor or alter the class creation

1352

process:

1353

1354

<li>Modifying the class dictionary prior to the class being created.</li>

1355

<li>Returning an instance of another class – essentially performing the role of a

1356

factory function.</li>

1357

</ul>

1358

These steps will have to be performed in the metaclass’s <a class="reference internal" href="#object.__new__" title="object.__new__"><code class="xref py py-meth docutils literal">__new__()</code></a> method

1359

– <code class="xref py py-meth docutils literal">type.__new__()</code> can then be called from this method to create a class

1360

with different properties. This example adds a new element to the class

1361

dictionary before creating the class:

1362

<div class="highlight-python"><div class="highlight"><pre>class metacls(type):

1363

def __new__(mcs, name, bases, dict):

1364

dict['foo'] = 'metacls was here'

1365

return type.__new__(mcs, name, bases, dict)

1366

</pre></div>

1367

</div>

1368

You can of course also override other class methods (or add new methods); for

1369

example defining a custom <a class="reference internal" href="#object.__call__" title="object.__call__"><code class="xref py py-meth docutils literal">__call__()</code></a> method in the metaclass allows custom

1370

behavior when the class is called, e.g. not always creating a new instance.

1371

1372

1373

<code class="descname">__metaclass__</code><a class="headerlink" href="#__metaclass__" title="Permalink to this definition">¶</a></dt>

1374

<dd>This variable can be any callable accepting arguments for <code class="docutils literal">name</code>, <code class="docutils literal">bases</code>,

1375

and <code class="docutils literal">dict</code>. Upon class creation, the callable is used instead of the built-in

1376

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

1377

1378

New in version 2.2.

1379

</div>

1380

</dd></dl>

1381

1382

The appropriate metaclass is determined by the following precedence rules:

1383

1384

<li>If <code class="docutils literal">dict['__metaclass__']</code> exists, it is used.</li>

1385

<li>Otherwise, if there is at least one base class, its metaclass is used (this

1386

looks for a __class__ attribute first and if not found, uses its type).</li>

1387

<li>Otherwise, if a global variable named __metaclass__ exists, it is used.</li>

1388

<li>Otherwise, the old-style, classic metaclass (types.ClassType) is used.</li>

1389

</ul>

1390

The potential uses for metaclasses are boundless. Some ideas that have been

1391

explored including logging, interface checking, automatic delegation, automatic

1392

property creation, proxies, frameworks, and automatic resource

1393

locking/synchronization.

1394

</div>

1395

1396

<h3>3.4.4. Customizing instance and subclass checks<a class="headerlink" href="#customizing-instance-and-subclass-checks" title="Permalink to this headline">¶</a></h3>

1397

1398

New in version 2.6.

1399

</div>

1400

The following methods are used to override the default behavior of the

1401

<a class="reference internal" href="../library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal">isinstance()</code></a> and <a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal">issubclass()</code></a> built-in functions.

1402

In particular, the metaclass <a class="reference internal" href="../library/abc.html#abc.ABCMeta" title="abc.ABCMeta"><code class="xref py py-class docutils literal">abc.ABCMeta</code></a> implements these methods in

1403

order to allow the addition of Abstract Base Classes (ABCs) as “virtual base

1404

classes” to any class or type (including built-in types), including other

1405

ABCs.

1406

1407

1408

<code class="descclassname">class.</code><code class="descname">__instancecheck__</code>(self, instance)<a class="headerlink" href="#class.__instancecheck__" title="Permalink to this definition">¶</a></dt>

1409

<dd>Return true if instance should be considered a (direct or indirect)

1410

instance of class. If defined, called to implement <code class="docutils literal">isinstance(instance,

1411

class)</code>.

1412

</dd></dl>

1413

1414

1415

1416

<code class="descclassname">class.</code><code class="descname">__subclasscheck__</code>(self, subclass)<a class="headerlink" href="#class.__subclasscheck__" title="Permalink to this definition">¶</a></dt>

1417

<dd>Return true if subclass should be considered a (direct or indirect)

1418

subclass of class. If defined, called to implement <code class="docutils literal">issubclass(subclass,

1419

class)</code>.

1420

</dd></dl>

1421

1422

Note that these methods are looked up on the type (metaclass) of a class. They

1423

cannot be defined as class methods in the actual class. This is consistent with

1424

the lookup of special methods that are called on instances, only in this

1425

case the instance is itself a class.

1426

1427

See also

1428

1429

<dt><a class="pep reference external" href="https://www.python.org/dev/peps/pep-3119">PEP 3119</a> - Introducing Abstract Base Classes</dt>

1430

<dd>Includes the specification for customizing <a class="reference internal" href="../library/functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal">isinstance()</code></a> and

1431

<a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal">issubclass()</code></a> behavior through <a class="reference internal" href="#class.__instancecheck__" title="class.__instancecheck__"><code class="xref py py-meth docutils literal">__instancecheck__()</code></a> and

1432

<a class="reference internal" href="#class.__subclasscheck__" title="class.__subclasscheck__"><code class="xref py py-meth docutils literal">__subclasscheck__()</code></a>, with motivation for this functionality

1433

in the context of adding Abstract Base Classes (see the <a class="reference internal" href="../library/abc.html#module-abc" title="abc: Abstract base classes according to PEP 3119."><code class="xref py py-mod docutils literal">abc</code></a>

1434

module) to the language.</dd>

1435

</dl>

1436

</div>

1437

</div>

1438

1439

<h3>3.4.5. Emulating callable objects<a class="headerlink" href="#emulating-callable-objects" title="Permalink to this headline">¶</a></h3>

1440

1441

1442

<code class="descclassname">object.</code><code class="descname">__call__</code>(self[, args...])<a class="headerlink" href="#object.__call__" title="Permalink to this definition">¶</a></dt>

1443

<dd>Called when the instance is “called” as a function; if this method is defined,

1444

<code class="docutils literal">x(arg1, arg2, ...)</code> is a shorthand for <code class="docutils literal">x.__call__(arg1, arg2, ...)</code>.

1445

</dd></dl>

1446

1447

</div>

1448

1449

<h3>3.4.6. Emulating container types<a class="headerlink" href="#emulating-container-types" title="Permalink to this headline">¶</a></h3>

1450

The following methods can be defined to implement container objects. Containers

1451

usually are sequences (such as lists or tuples) or mappings (like dictionaries),

1452

but can represent other containers as well. The first set of methods is used

1453

either to emulate a sequence or to emulate a mapping; the difference is that for

1454

a sequence, the allowable keys should be the integers k for which <code class="docutils literal">0 <= k <

1455

N</code> where N is the length of the sequence, or slice objects, which define a

1456

range of items. (For backwards compatibility, the method <a class="reference internal" href="#object.__getslice__" title="object.__getslice__"><code class="xref py py-meth docutils literal">__getslice__()</code></a>

1457

(see below) can also be defined to handle simple, but not extended slices.) It

1458

is also recommended that mappings provide the methods <code class="xref py py-meth docutils literal">keys()</code>,

1459

<code class="xref py py-meth docutils literal">values()</code>, <code class="xref py py-meth docutils literal">items()</code>, <code class="xref py py-meth docutils literal">has_key()</code>, <code class="xref py py-meth docutils literal">get()</code>, <code class="xref py py-meth docutils literal">clear()</code>,

1460

<code class="xref py py-meth docutils literal">setdefault()</code>, <code class="xref py py-meth docutils literal">iterkeys()</code>, <code class="xref py py-meth docutils literal">itervalues()</code>, <code class="xref py py-meth docutils literal">iteritems()</code>,

1461

<code class="xref py py-meth docutils literal">pop()</code>, <code class="xref py py-meth docutils literal">popitem()</code>, <code class="xref py py-meth docutils literal">copy()</code>, and <code class="xref py py-meth docutils literal">update()</code> behaving similar

1462

to those for Python’s standard dictionary objects. The <a class="reference internal" href="../library/userdict.html#module-UserDict" title="UserDict: Class wrapper for dictionary objects."><code class="xref py py-mod docutils literal">UserDict</code></a> module

1463

provides a <code class="xref py py-class docutils literal">DictMixin</code> class to help create those methods from a base set

1464

of <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>, <a class="reference internal" href="#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal">__setitem__()</code></a>, <a class="reference internal" href="#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal">__delitem__()</code></a>, and

1465

<code class="xref py py-meth docutils literal">keys()</code>. Mutable sequences should provide methods <code class="xref py py-meth docutils literal">append()</code>,

1466

<code class="xref py py-meth docutils literal">count()</code>, <code class="xref py py-meth docutils literal">index()</code>, <code class="xref py py-meth docutils literal">extend()</code>, <code class="xref py py-meth docutils literal">insert()</code>, <code class="xref py py-meth docutils literal">pop()</code>,

1467

<code class="xref py py-meth docutils literal">remove()</code>, <code class="xref py py-meth docutils literal">reverse()</code> and <code class="xref py py-meth docutils literal">sort()</code>, like Python standard list

1468

objects. Finally, sequence types should implement addition (meaning

1469

concatenation) and multiplication (meaning repetition) by defining the methods

1470

<a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal">__add__()</code></a>, <a class="reference internal" href="#object.__radd__" title="object.__radd__"><code class="xref py py-meth docutils literal">__radd__()</code></a>, <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal">__iadd__()</code></a>, <a class="reference internal" href="#object.__mul__" title="object.__mul__"><code class="xref py py-meth docutils literal">__mul__()</code></a>,

1471

<a class="reference internal" href="#object.__rmul__" title="object.__rmul__"><code class="xref py py-meth docutils literal">__rmul__()</code></a> and <a class="reference internal" href="#object.__imul__" title="object.__imul__"><code class="xref py py-meth docutils literal">__imul__()</code></a> described below; they should not define

1472

1473

mappings and sequences implement the <a class="reference internal" href="#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal">__contains__()</code></a> method to allow

1474

efficient use of the <code class="docutils literal">in</code> operator; for mappings, <code class="docutils literal">in</code> should be equivalent

1475

of <code class="xref py py-meth docutils literal">has_key()</code>; for sequences, it should search through the values. It is

1476

further recommended that both mappings and sequences implement the

1477

<a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a> method to allow efficient iteration through the container; for

1478

mappings, <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a> should be the same as <code class="xref py py-meth docutils literal">iterkeys()</code>; for

1479

sequences, it should iterate through the values.

1480

1481

1482

<code class="descclassname">object.</code><code class="descname">__len__</code>(self)<a class="headerlink" href="#object.__len__" title="Permalink to this definition">¶</a></dt>

1483

<dd>Called to implement the built-in function <a class="reference internal" href="../library/functions.html#len" title="len"><code class="xref py py-func docutils literal">len()</code></a>. Should return the length

1484

of the object, an integer <code class="docutils literal">>=</code> 0. Also, an object that doesn’t define a

1485

<a class="reference internal" href="#object.__nonzero__" title="object.__nonzero__"><code class="xref py py-meth docutils literal">__nonzero__()</code></a> method and whose <a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> method returns zero is

1486

considered to be false in a Boolean context.

1487

</dd></dl>

1488

1489

1490

1491

<code class="descclassname">object.</code><code class="descname">__getitem__</code>(self, key)<a class="headerlink" href="#object.__getitem__" title="Permalink to this definition">¶</a></dt>

1492

<dd>Called to implement evaluation of <code class="docutils literal">self[key]</code>. For sequence types, the

1493

accepted keys should be integers and slice objects. Note that the special

1494

interpretation of negative indexes (if the class wishes to emulate a sequence

1495

type) is up to the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> method. If key is of an inappropriate

1496

type, <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> may be raised; if of a value outside the set of indexes

1497

for the sequence (after any special interpretation of negative values),

1498

<a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal">IndexError</code></a> should be raised. For mapping types, if key is missing (not

1499

in the container), <a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><code class="xref py py-exc docutils literal">KeyError</code></a> should be raised.

1500

1501

Note

1502

<a class="reference internal" href="compound_stmts.html#for"><code class="xref std std-keyword docutils literal">for</code></a> loops expect that an <a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal">IndexError</code></a> will be raised for illegal

1503

indexes to allow proper detection of the end of the sequence.

1504

</div>

1505

</dd></dl>

1506

1507

1508

1509

<code class="descclassname">object.</code><code class="descname">__missing__</code>(self, key)<a class="headerlink" href="#object.__missing__" title="Permalink to this definition">¶</a></dt>

1510

<dd>Called by <a class="reference internal" href="../library/stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal">dict</code></a>.<a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> to implement <code class="docutils literal">self[key]</code> for dict subclasses

1511

when key is not in the dictionary.

1512

</dd></dl>

1513

1514

1515

1516

<code class="descclassname">object.</code><code class="descname">__setitem__</code>(self, key, value)<a class="headerlink" href="#object.__setitem__" title="Permalink to this definition">¶</a></dt>

1517

<dd>Called to implement assignment to <code class="docutils literal">self[key]</code>. Same note as for

1518

1519

objects support changes to the values for keys, or if new keys can be added, or

1520

for sequences if elements can be replaced. The same exceptions should be raised

1521

for improper key values as for the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> method.

1522

</dd></dl>

1523

1524

1525

1526

<code class="descclassname">object.</code><code class="descname">__delitem__</code>(self, key)<a class="headerlink" href="#object.__delitem__" title="Permalink to this definition">¶</a></dt>

1527

<dd>Called to implement deletion of <code class="docutils literal">self[key]</code>. Same note as for

1528

1529

objects support removal of keys, or for sequences if elements can be removed

1530

from the sequence. The same exceptions should be raised for improper key

1531

values as for the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> method.

1532

</dd></dl>

1533

1534

1535

1536

<code class="descclassname">object.</code><code class="descname">__iter__</code>(self)<a class="headerlink" href="#object.__iter__" title="Permalink to this definition">¶</a></dt>

1537

<dd>This method is called when an iterator is required for a container. This method

1538

should return a new iterator object that can iterate over all the objects in the

1539

container. For mappings, it should iterate over the keys of the container, and

1540

should also be made available as the method <code class="xref py py-meth docutils literal">iterkeys()</code>.

1541

Iterator objects also need to implement this method; they are required to return

1542

themselves. For more information on iterator objects, see <a class="reference internal" href="../library/stdtypes.html#typeiter">Iterator Types</a>.

1543

</dd></dl>

1544

1545

1546

1547

<code class="descclassname">object.</code><code class="descname">__reversed__</code>(self)<a class="headerlink" href="#object.__reversed__" title="Permalink to this definition">¶</a></dt>

1548

<dd>Called (if present) by the <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal">reversed()</code></a> built-in to implement

1549

reverse iteration. It should return a new iterator object that iterates

1550

over all the objects in the container in reverse order.

1551

If the <a class="reference internal" href="#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal">__reversed__()</code></a> method is not provided, the <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal">reversed()</code></a>

1552

built-in will fall back to using the sequence protocol (<a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> and

1553

1554

only provide <a class="reference internal" href="#object.__reversed__" title="object.__reversed__"><code class="xref py py-meth docutils literal">__reversed__()</code></a> if they can provide an implementation

1555

that is more efficient than the one provided by <a class="reference internal" href="../library/functions.html#reversed" title="reversed"><code class="xref py py-func docutils literal">reversed()</code></a>.

1556

1557

New in version 2.6.

1558

</div>

1559

</dd></dl>

1560

1561

The membership test operators (<a class="reference internal" href="expressions.html#in"><code class="xref std std-keyword docutils literal">in</code></a> and <a class="reference internal" href="expressions.html#not-in"><code class="xref std std-keyword docutils literal">not in</code></a>) are normally

1562

implemented as an iteration through a sequence. However, container objects can

1563

supply the following special method with a more efficient implementation, which

1564

also does not require the object be a sequence.

1565

1566

1567

<code class="descclassname">object.</code><code class="descname">__contains__</code>(self, item)<a class="headerlink" href="#object.__contains__" title="Permalink to this definition">¶</a></dt>

1568

<dd>Called to implement membership test operators. Should return true if item

1569

is in self, false otherwise. For mapping objects, this should consider the

1570

keys of the mapping rather than the values or the key-item pairs.

1571

For objects that don’t define <a class="reference internal" href="#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal">__contains__()</code></a>, the membership test first

1572

tries iteration via <a class="reference internal" href="#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal">__iter__()</code></a>, then the old sequence iteration

1573

protocol via <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>, see <a class="reference internal" href="expressions.html#membership-test-details">this section in the language

1574

reference</a>.

1575

</dd></dl>

1576

1577

</div>

1578

1579

<h3>3.4.7. Additional methods for emulation of sequence types<a class="headerlink" href="#additional-methods-for-emulation-of-sequence-types" title="Permalink to this headline">¶</a></h3>

1580

The following optional methods can be defined to further emulate sequence

1581

objects. Immutable sequences methods should at most only define

1582

1583

1584

1585

<code class="descclassname">object.</code><code class="descname">__getslice__</code>(self, i, j)<a class="headerlink" href="#object.__getslice__" title="Permalink to this definition">¶</a></dt>

1586

1587

Deprecated since version 2.0: Support slice objects as parameters to the <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> method.

1588

(However, built-in types in CPython currently still implement

1589

1590

classes when implementing slicing.)

1591

</div>

1592

Called to implement evaluation of <code class="docutils literal">self[i:j]</code>. The returned object should

1593

be of the same type as self. Note that missing i or j in the slice

1594

expression are replaced by zero or <a class="reference internal" href="../library/sys.html#sys.maxsize" title="sys.maxsize"><code class="xref py py-attr docutils literal">sys.maxsize</code></a>, respectively. If

1595

negative indexes are used in the slice, the length of the sequence is added

1596

to that index. If the instance does not implement the <a class="reference internal" href="#object.__len__" title="object.__len__"><code class="xref py py-meth docutils literal">__len__()</code></a> method,

1597

an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a> is raised. No guarantee is made that indexes

1598

adjusted this way are not still negative. Indexes which are greater than the

1599

length of the sequence are not modified. If no <a class="reference internal" href="#object.__getslice__" title="object.__getslice__"><code class="xref py py-meth docutils literal">__getslice__()</code></a> is found,

1600

a slice object is created instead, and passed to <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a> instead.

1601

</dd></dl>

1602

1603

1604

1605

<code class="descclassname">object.</code><code class="descname">__setslice__</code>(self, i, j, sequence)<a class="headerlink" href="#object.__setslice__" title="Permalink to this definition">¶</a></dt>

1606

<dd>Called to implement assignment to <code class="docutils literal">self[i:j]</code>. Same notes for i and j as

1607

for <a class="reference internal" href="#object.__getslice__" title="object.__getslice__"><code class="xref py py-meth docutils literal">__getslice__()</code></a>.

1608

This method is deprecated. If no <a class="reference internal" href="#object.__setslice__" title="object.__setslice__"><code class="xref py py-meth docutils literal">__setslice__()</code></a> is found, or for extended

1609

slicing of the form <code class="docutils literal">self[i:j:k]</code>, a slice object is created, and passed to

1610

<a class="reference internal" href="#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal">__setitem__()</code></a>, instead of <a class="reference internal" href="#object.__setslice__" title="object.__setslice__"><code class="xref py py-meth docutils literal">__setslice__()</code></a> being called.

1611

</dd></dl>

1612

1613

1614

1615

<code class="descclassname">object.</code><code class="descname">__delslice__</code>(self, i, j)<a class="headerlink" href="#object.__delslice__" title="Permalink to this definition">¶</a></dt>

1616

<dd>Called to implement deletion of <code class="docutils literal">self[i:j]</code>. Same notes for i and j as for

1617

<a class="reference internal" href="#object.__getslice__" title="object.__getslice__"><code class="xref py py-meth docutils literal">__getslice__()</code></a>. This method is deprecated. If no <a class="reference internal" href="#object.__delslice__" title="object.__delslice__"><code class="xref py py-meth docutils literal">__delslice__()</code></a> is

1618

found, or for extended slicing of the form <code class="docutils literal">self[i:j:k]</code>, a slice object is

1619

created, and passed to <a class="reference internal" href="#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal">__delitem__()</code></a>, instead of <a class="reference internal" href="#object.__delslice__" title="object.__delslice__"><code class="xref py py-meth docutils literal">__delslice__()</code></a>

1620

being called.

1621

</dd></dl>

1622

1623

Notice that these methods are only invoked when a single slice with a single

1624

colon is used, and the slice method is available. For slice operations

1625

involving extended slice notation, or in absence of the slice methods,

1626

<a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>, <a class="reference internal" href="#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal">__setitem__()</code></a> or <a class="reference internal" href="#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal">__delitem__()</code></a> is called with a

1627

slice object as argument.

1628

The following example demonstrate how to make your program or module compatible

1629

with earlier versions of Python (assuming that methods <a class="reference internal" href="#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal">__getitem__()</code></a>,

1630

<a class="reference internal" href="#object.__setitem__" title="object.__setitem__"><code class="xref py py-meth docutils literal">__setitem__()</code></a> and <a class="reference internal" href="#object.__delitem__" title="object.__delitem__"><code class="xref py py-meth docutils literal">__delitem__()</code></a> support slice objects as

1631

arguments):

1632

<div class="highlight-python"><div class="highlight"><pre>class MyClass:

1633

...

1634

def __getitem__(self, index):

1635

...

1636

def __setitem__(self, index, value):

1637

...

1638

def __delitem__(self, index):

1639

...

1640

1641

if sys.version_info < (2, 0):

1642

# They won't be defined if version is at least 2.0 final

1643

1644

def __getslice__(self, i, j):

1645

return self[max(0, i):max(0, j):]

1646

def __setslice__(self, i, j, seq):

1647

self[max(0, i):max(0, j):] = seq

1648

def __delslice__(self, i, j):

1649

del self[max(0, i):max(0, j):]

1650

...

1651

</pre></div>

1652

</div>

1653

Note the calls to <a class="reference internal" href="../library/functions.html#max" title="max"><code class="xref py py-func docutils literal">max()</code></a>; these are necessary because of the handling of

1654

negative indices before the <code class="xref py py-meth docutils literal">__*slice__()</code> methods are called. When

1655

negative indexes are used, the <code class="xref py py-meth docutils literal">__*item__()</code> methods receive them as

1656

provided, but the <code class="xref py py-meth docutils literal">__*slice__()</code> methods get a “cooked” form of the index

1657

values. For each negative index value, the length of the sequence is added to

1658

the index before calling the method (which may still result in a negative

1659

index); this is the customary handling of negative indexes by the built-in

1660

sequence types, and the <code class="xref py py-meth docutils literal">__*item__()</code> methods are expected to do this as

1661

well. However, since they should already be doing that, negative indexes cannot

1662

be passed in; they must be constrained to the bounds of the sequence before

1663

being passed to the <code class="xref py py-meth docutils literal">__*item__()</code> methods. Calling <code class="docutils literal">max(0, i)</code>

1664

conveniently returns the proper value.

1665

</div>

1666

1667

<h3>3.4.8. Emulating numeric types<a class="headerlink" href="#emulating-numeric-types" title="Permalink to this headline">¶</a></h3>

1668

The following methods can be defined to emulate numeric objects. Methods

1669

corresponding to operations that are not supported by the particular kind of

1670

number implemented (e.g., bitwise operations for non-integral numbers) should be

1671

left undefined.

1672

1673

1674

<code class="descclassname">object.</code><code class="descname">__add__</code>(self, other)<a class="headerlink" href="#object.__add__" title="Permalink to this definition">¶</a></dt>

1675

1676

<code class="descclassname">object.</code><code class="descname">__sub__</code>(self, other)<a class="headerlink" href="#object.__sub__" title="Permalink to this definition">¶</a></dt>

1677

1678

<code class="descclassname">object.</code><code class="descname">__mul__</code>(self, other)<a class="headerlink" href="#object.__mul__" title="Permalink to this definition">¶</a></dt>

1679

1680

<code class="descclassname">object.</code><code class="descname">__floordiv__</code>(self, other)<a class="headerlink" href="#object.__floordiv__" title="Permalink to this definition">¶</a></dt>

1681

1682

<code class="descclassname">object.</code><code class="descname">__mod__</code>(self, other)<a class="headerlink" href="#object.__mod__" title="Permalink to this definition">¶</a></dt>

1683

1684

<code class="descclassname">object.</code><code class="descname">__divmod__</code>(self, other)<a class="headerlink" href="#object.__divmod__" title="Permalink to this definition">¶</a></dt>

1685

1686

<code class="descclassname">object.</code><code class="descname">__pow__</code>(self, other[, modulo])<a class="headerlink" href="#object.__pow__" title="Permalink to this definition">¶</a></dt>

1687

1688

<code class="descclassname">object.</code><code class="descname">__lshift__</code>(self, other)<a class="headerlink" href="#object.__lshift__" title="Permalink to this definition">¶</a></dt>

1689

1690

<code class="descclassname">object.</code><code class="descname">__rshift__</code>(self, other)<a class="headerlink" href="#object.__rshift__" title="Permalink to this definition">¶</a></dt>

1691

1692

<code class="descclassname">object.</code><code class="descname">__and__</code>(self, other)<a class="headerlink" href="#object.__and__" title="Permalink to this definition">¶</a></dt>

1693

1694

<code class="descclassname">object.</code><code class="descname">__xor__</code>(self, other)<a class="headerlink" href="#object.__xor__" title="Permalink to this definition">¶</a></dt>

1695

1696

<code class="descclassname">object.</code><code class="descname">__or__</code>(self, other)<a class="headerlink" href="#object.__or__" title="Permalink to this definition">¶</a></dt>

1697

<dd>These methods are called to implement the binary arithmetic operations (<code class="docutils literal">+</code>,

1698

<code class="docutils literal">-</code>, <code class="docutils literal">*</code>, <code class="docutils literal">//</code>, <code class="docutils literal">%</code>, <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal">divmod()</code></a>, <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal">pow()</code></a>, <code class="docutils literal">**</code>, <code class="docutils literal"><<</code>,

1699

<code class="docutils literal">>></code>, <code class="docutils literal">&</code>, <code class="docutils literal">^</code>, <code class="docutils literal">|</code>). For instance, to evaluate the expression

1700

<code class="docutils literal">x + y</code>, where x is an instance of a class that has an <a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal">__add__()</code></a>

1701

method, <code class="docutils literal">x.__add__(y)</code> is called. The <a class="reference internal" href="#object.__divmod__" title="object.__divmod__"><code class="xref py py-meth docutils literal">__divmod__()</code></a> method should be the

1702

equivalent to using <a class="reference internal" href="#object.__floordiv__" title="object.__floordiv__"><code class="xref py py-meth docutils literal">__floordiv__()</code></a> and <a class="reference internal" href="#object.__mod__" title="object.__mod__"><code class="xref py py-meth docutils literal">__mod__()</code></a>; it should not be

1703

related to <a class="reference internal" href="#object.__truediv__" title="object.__truediv__"><code class="xref py py-meth docutils literal">__truediv__()</code></a> (described below). Note that <a class="reference internal" href="#object.__pow__" title="object.__pow__"><code class="xref py py-meth docutils literal">__pow__()</code></a>

1704

should be defined to accept an optional third argument if the ternary version of

1705

the built-in <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal">pow()</code></a> function is to be supported.

1706

If one of those methods does not support the operation with the supplied

1707

arguments, it should return <code class="docutils literal">NotImplemented</code>.

1708

</dd></dl>

1709

1710

1711

1712

<code class="descclassname">object.</code><code class="descname">__div__</code>(self, other)<a class="headerlink" href="#object.__div__" title="Permalink to this definition">¶</a></dt>

1713

1714

<code class="descclassname">object.</code><code class="descname">__truediv__</code>(self, other)<a class="headerlink" href="#object.__truediv__" title="Permalink to this definition">¶</a></dt>

1715

<dd>The division operator (<code class="docutils literal">/</code>) is implemented by these methods. The

1716

<a class="reference internal" href="#object.__truediv__" title="object.__truediv__"><code class="xref py py-meth docutils literal">__truediv__()</code></a> method is used when <code class="docutils literal">__future__.division</code> is in effect,

1717

otherwise <a class="reference internal" href="#object.__div__" title="object.__div__"><code class="xref py py-meth docutils literal">__div__()</code></a> is used. If only one of these two methods is defined,

1718

the object will not support division in the alternate context; <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a>

1719

will be raised instead.

1720

</dd></dl>

1721

1722

1723

1724

<code class="descclassname">object.</code><code class="descname">__radd__</code>(self, other)<a class="headerlink" href="#object.__radd__" title="Permalink to this definition">¶</a></dt>

1725

1726

<code class="descclassname">object.</code><code class="descname">__rsub__</code>(self, other)<a class="headerlink" href="#object.__rsub__" title="Permalink to this definition">¶</a></dt>

1727

1728

<code class="descclassname">object.</code><code class="descname">__rmul__</code>(self, other)<a class="headerlink" href="#object.__rmul__" title="Permalink to this definition">¶</a></dt>

1729

1730

<code class="descclassname">object.</code><code class="descname">__rdiv__</code>(self, other)<a class="headerlink" href="#object.__rdiv__" title="Permalink to this definition">¶</a></dt>

1731

1732

<code class="descclassname">object.</code><code class="descname">__rtruediv__</code>(self, other)<a class="headerlink" href="#object.__rtruediv__" title="Permalink to this definition">¶</a></dt>

1733

1734

<code class="descclassname">object.</code><code class="descname">__rfloordiv__</code>(self, other)<a class="headerlink" href="#object.__rfloordiv__" title="Permalink to this definition">¶</a></dt>

1735

1736

<code class="descclassname">object.</code><code class="descname">__rmod__</code>(self, other)<a class="headerlink" href="#object.__rmod__" title="Permalink to this definition">¶</a></dt>

1737

1738

<code class="descclassname">object.</code><code class="descname">__rdivmod__</code>(self, other)<a class="headerlink" href="#object.__rdivmod__" title="Permalink to this definition">¶</a></dt>

1739

1740

<code class="descclassname">object.</code><code class="descname">__rpow__</code>(self, other)<a class="headerlink" href="#object.__rpow__" title="Permalink to this definition">¶</a></dt>

1741

1742

<code class="descclassname">object.</code><code class="descname">__rlshift__</code>(self, other)<a class="headerlink" href="#object.__rlshift__" title="Permalink to this definition">¶</a></dt>

1743

1744

<code class="descclassname">object.</code><code class="descname">__rrshift__</code>(self, other)<a class="headerlink" href="#object.__rrshift__" title="Permalink to this definition">¶</a></dt>

1745

1746

<code class="descclassname">object.</code><code class="descname">__rand__</code>(self, other)<a class="headerlink" href="#object.__rand__" title="Permalink to this definition">¶</a></dt>

1747

1748

<code class="descclassname">object.</code><code class="descname">__rxor__</code>(self, other)<a class="headerlink" href="#object.__rxor__" title="Permalink to this definition">¶</a></dt>

1749

1750

<code class="descclassname">object.</code><code class="descname">__ror__</code>(self, other)<a class="headerlink" href="#object.__ror__" title="Permalink to this definition">¶</a></dt>

1751

<dd>These methods are called to implement the binary arithmetic operations (<code class="docutils literal">+</code>,

1752

<code class="docutils literal">-</code>, <code class="docutils literal">*</code>, <code class="docutils literal">/</code>, <code class="docutils literal">%</code>, <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal">divmod()</code></a>, <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal">pow()</code></a>, <code class="docutils literal">**</code>, <code class="docutils literal"><<</code>, <code class="docutils literal">>></code>,

1753

<code class="docutils literal">&</code>, <code class="docutils literal">^</code>, <code class="docutils literal">|</code>) with reflected (swapped) operands. These functions are

1754

only called if the left operand does not support the corresponding operation and

1755

the operands are of different types. <a class="footnote-reference" href="#id6" id="id3">[2]</a> For instance, to evaluate the

1756

expression <code class="docutils literal">x - y</code>, where y is an instance of a class that has an

1757

<a class="reference internal" href="#object.__rsub__" title="object.__rsub__"><code class="xref py py-meth docutils literal">__rsub__()</code></a> method, <code class="docutils literal">y.__rsub__(x)</code> is called if <code class="docutils literal">x.__sub__(y)</code> returns

1758

NotImplemented.

1759

Note that ternary <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal">pow()</code></a> will not try calling <a class="reference internal" href="#object.__rpow__" title="object.__rpow__"><code class="xref py py-meth docutils literal">__rpow__()</code></a> (the

1760

coercion rules would become too complicated).

1761

1762

Note

1763

If the right operand’s type is a subclass of the left operand’s type and that

1764

subclass provides the reflected method for the operation, this method will be

1765

called before the left operand’s non-reflected method. This behavior allows

1766

subclasses to override their ancestors’ operations.

1767

</div>

1768

</dd></dl>

1769

1770

1771

1772

<code class="descclassname">object.</code><code class="descname">__iadd__</code>(self, other)<a class="headerlink" href="#object.__iadd__" title="Permalink to this definition">¶</a></dt>

1773

1774

<code class="descclassname">object.</code><code class="descname">__isub__</code>(self, other)<a class="headerlink" href="#object.__isub__" title="Permalink to this definition">¶</a></dt>

1775

1776

<code class="descclassname">object.</code><code class="descname">__imul__</code>(self, other)<a class="headerlink" href="#object.__imul__" title="Permalink to this definition">¶</a></dt>

1777

1778

<code class="descclassname">object.</code><code class="descname">__idiv__</code>(self, other)<a class="headerlink" href="#object.__idiv__" title="Permalink to this definition">¶</a></dt>

1779

1780

<code class="descclassname">object.</code><code class="descname">__itruediv__</code>(self, other)<a class="headerlink" href="#object.__itruediv__" title="Permalink to this definition">¶</a></dt>

1781

1782

<code class="descclassname">object.</code><code class="descname">__ifloordiv__</code>(self, other)<a class="headerlink" href="#object.__ifloordiv__" title="Permalink to this definition">¶</a></dt>

1783

1784

<code class="descclassname">object.</code><code class="descname">__imod__</code>(self, other)<a class="headerlink" href="#object.__imod__" title="Permalink to this definition">¶</a></dt>

1785

1786

<code class="descclassname">object.</code><code class="descname">__ipow__</code>(self, other[, modulo])<a class="headerlink" href="#object.__ipow__" title="Permalink to this definition">¶</a></dt>

1787

1788

<code class="descclassname">object.</code><code class="descname">__ilshift__</code>(self, other)<a class="headerlink" href="#object.__ilshift__" title="Permalink to this definition">¶</a></dt>

1789

1790

<code class="descclassname">object.</code><code class="descname">__irshift__</code>(self, other)<a class="headerlink" href="#object.__irshift__" title="Permalink to this definition">¶</a></dt>

1791

1792

<code class="descclassname">object.</code><code class="descname">__iand__</code>(self, other)<a class="headerlink" href="#object.__iand__" title="Permalink to this definition">¶</a></dt>

1793

1794

<code class="descclassname">object.</code><code class="descname">__ixor__</code>(self, other)<a class="headerlink" href="#object.__ixor__" title="Permalink to this definition">¶</a></dt>

1795

1796

<code class="descclassname">object.</code><code class="descname">__ior__</code>(self, other)<a class="headerlink" href="#object.__ior__" title="Permalink to this definition">¶</a></dt>

1797

<dd>These methods are called to implement the augmented arithmetic assignments

1798

(<code class="docutils literal">+=</code>, <code class="docutils literal">-=</code>, <code class="docutils literal">*=</code>, <code class="docutils literal">/=</code>, <code class="docutils literal">//=</code>, <code class="docutils literal">%=</code>, <code class="docutils literal">**=</code>, <code class="docutils literal"><<=</code>, <code class="docutils literal">>>=</code>,

1799

<code class="docutils literal">&=</code>, <code class="docutils literal">^=</code>, <code class="docutils literal">|=</code>). These methods should attempt to do the operation

1800

in-place (modifying self) and return the result (which could be, but does

1801

not have to be, self). If a specific method is not defined, the augmented

1802

assignment falls back to the normal methods. For instance, to execute the

1803

statement <code class="docutils literal">x += y</code>, where x is an instance of a class that has an

1804

<a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal">__iadd__()</code></a> method, <code class="docutils literal">x.__iadd__(y)</code> is called. If x is an instance

1805

of a class that does not define a <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal">__iadd__()</code></a> method, <code class="docutils literal">x.__add__(y)</code>

1806

and <code class="docutils literal">y.__radd__(x)</code> are considered, as with the evaluation of <code class="docutils literal">x + y</code>.

1807

</dd></dl>

1808

1809

1810

1811

<code class="descclassname">object.</code><code class="descname">__neg__</code>(self)<a class="headerlink" href="#object.__neg__" title="Permalink to this definition">¶</a></dt>

1812

1813

<code class="descclassname">object.</code><code class="descname">__pos__</code>(self)<a class="headerlink" href="#object.__pos__" title="Permalink to this definition">¶</a></dt>

1814

1815

<code class="descclassname">object.</code><code class="descname">__abs__</code>(self)<a class="headerlink" href="#object.__abs__" title="Permalink to this definition">¶</a></dt>

1816

1817

<code class="descclassname">object.</code><code class="descname">__invert__</code>(self)<a class="headerlink" href="#object.__invert__" title="Permalink to this definition">¶</a></dt>

1818

<dd>Called to implement the unary arithmetic operations (<code class="docutils literal">-</code>, <code class="docutils literal">+</code>, <a class="reference internal" href="../library/functions.html#abs" title="abs"><code class="xref py py-func docutils literal">abs()</code></a>

1819

and <code class="docutils literal">~</code>).

1820

</dd></dl>

1821

1822

1823

1824

<code class="descclassname">object.</code><code class="descname">__complex__</code>(self)<a class="headerlink" href="#object.__complex__" title="Permalink to this definition">¶</a></dt>

1825

1826

<code class="descclassname">object.</code><code class="descname">__int__</code>(self)<a class="headerlink" href="#object.__int__" title="Permalink to this definition">¶</a></dt>

1827

1828

<code class="descclassname">object.</code><code class="descname">__long__</code>(self)<a class="headerlink" href="#object.__long__" title="Permalink to this definition">¶</a></dt>

1829

1830

<code class="descclassname">object.</code><code class="descname">__float__</code>(self)<a class="headerlink" href="#object.__float__" title="Permalink to this definition">¶</a></dt>

1831

<dd>Called to implement the built-in functions <a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-func docutils literal">complex()</code></a>, <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-func docutils literal">int()</code></a>,

1832

<a class="reference internal" href="../library/functions.html#long" title="long"><code class="xref py py-func docutils literal">long()</code></a>, and <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-func docutils literal">float()</code></a>. Should return a value of the appropriate type.

1833

</dd></dl>

1834

1835

1836

1837

<code class="descclassname">object.</code><code class="descname">__oct__</code>(self)<a class="headerlink" href="#object.__oct__" title="Permalink to this definition">¶</a></dt>

1838

1839

<code class="descclassname">object.</code><code class="descname">__hex__</code>(self)<a class="headerlink" href="#object.__hex__" title="Permalink to this definition">¶</a></dt>

1840

<dd>Called to implement the built-in functions <a class="reference internal" href="../library/functions.html#oct" title="oct"><code class="xref py py-func docutils literal">oct()</code></a> and <a class="reference internal" href="../library/functions.html#hex" title="hex"><code class="xref py py-func docutils literal">hex()</code></a>. Should

1841

return a string value.

1842

</dd></dl>

1843

1844

1845

1846

<code class="descclassname">object.</code><code class="descname">__index__</code>(self)<a class="headerlink" href="#object.__index__" title="Permalink to this definition">¶</a></dt>

1847

<dd>Called to implement <a class="reference internal" href="../library/operator.html#operator.index" title="operator.index"><code class="xref py py-func docutils literal">operator.index()</code></a>. Also called whenever Python needs

1848

an integer object (such as in slicing). Must return an integer (int or long).

1849

1850

New in version 2.5.

1851

</div>

1852

</dd></dl>

1853

1854

1855

1856

<code class="descclassname">object.</code><code class="descname">__coerce__</code>(self, other)<a class="headerlink" href="#object.__coerce__" title="Permalink to this definition">¶</a></dt>

1857

<dd>Called to implement “mixed-mode” numeric arithmetic. Should either return a

1858

2-tuple containing self and other converted to a common numeric type, or

1859

<code class="docutils literal">None</code> if conversion is impossible. When the common type would be the type of

1860

<code class="docutils literal">other</code>, it is sufficient to return <code class="docutils literal">None</code>, since the interpreter will also

1861

ask the other object to attempt a coercion (but sometimes, if the implementation

1862

of the other type cannot be changed, it is useful to do the conversion to the

1863

other type here). A return value of <code class="docutils literal">NotImplemented</code> is equivalent to

1864

returning <code class="docutils literal">None</code>.

1865

</dd></dl>

1866

1867

</div>

1868

1869

<h3>3.4.9. Coercion rules<a class="headerlink" href="#coercion-rules" title="Permalink to this headline">¶</a></h3>

1870

This section used to document the rules for coercion. As the language has

1871

evolved, the coercion rules have become hard to document precisely; documenting

1872

what one version of one particular implementation does is undesirable. Instead,

1873

here are some informal guidelines regarding coercion. In Python 3, coercion

1874

will not be supported.

1875

<ul>

1876

<li>If the left operand of a % operator is a string or Unicode object, no coercion

1877

takes place and the string formatting operation is invoked instead.

1878

</li>

1879

<li>It is no longer recommended to define a coercion operation. Mixed-mode

1880

operations on types that don’t define coercion pass the original arguments to

1881

the operation.

1882

</li>

1883

<li>New-style classes (those derived from <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a>) never invoke the

1884

1885

<a class="reference internal" href="#object.__coerce__" title="object.__coerce__"><code class="xref py py-meth docutils literal">__coerce__()</code></a> is invoked is when the built-in function <a class="reference internal" href="../library/functions.html#coerce" title="coerce"><code class="xref py py-func docutils literal">coerce()</code></a> is

1886

called.

1887

</li>

1888

<li>For most intents and purposes, an operator that returns <code class="docutils literal">NotImplemented</code> is

1889

treated the same as one that is not implemented at all.

1890

</li>

1891

<li>Below, <code class="xref py py-meth docutils literal">__op__()</code> and <code class="xref py py-meth docutils literal">__rop__()</code> are used to signify the generic method

1892

names corresponding to an operator; <code class="xref py py-meth docutils literal">__iop__()</code> is used for the

1893

corresponding in-place operator. For example, for the operator ‘<code class="docutils literal">+</code>‘,

1894

1895

the binary operator, and <a class="reference internal" href="#object.__iadd__" title="object.__iadd__"><code class="xref py py-meth docutils literal">__iadd__()</code></a> for the in-place variant.

1896

</li>

1897

<li>For objects x and y, first <code class="docutils literal">x.__op__(y)</code> is tried. If this is not

1898

implemented or returns <code class="docutils literal">NotImplemented</code>, <code class="docutils literal">y.__rop__(x)</code> is tried. If this

1899

is also not implemented or returns <code class="docutils literal">NotImplemented</code>, a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a>

1900

exception is raised. But see the following exception:

1901

</li>

1902

<li>Exception to the previous item: if the left operand is an instance of a built-in

1903

type or a new-style class, and the right operand is an instance of a proper

1904

subclass of that type or class and overrides the base’s <code class="xref py py-meth docutils literal">__rop__()</code> method,

1905

the right operand’s <code class="xref py py-meth docutils literal">__rop__()</code> method is tried before the left operand’s

1906

<code class="xref py py-meth docutils literal">__op__()</code> method.

1907

This is done so that a subclass can completely override binary operators.

1908

Otherwise, the left operand’s <code class="xref py py-meth docutils literal">__op__()</code> method would always accept the

1909

right operand: when an instance of a given class is expected, an instance of a

1910

subclass of that class is always acceptable.

1911

</li>

1912

<li>When either operand type defines a coercion, this coercion is called before that

1913

type’s <code class="xref py py-meth docutils literal">__op__()</code> or <code class="xref py py-meth docutils literal">__rop__()</code> method is called, but no sooner. If

1914

the coercion returns an object of a different type for the operand whose

1915

coercion is invoked, part of the process is redone using the new object.

1916

</li>

1917

<li>When an in-place operator (like ‘<code class="docutils literal">+=</code>‘) is used, if the left operand

1918

implements <code class="xref py py-meth docutils literal">__iop__()</code>, it is invoked without any coercion. When the

1919

operation falls back to <code class="xref py py-meth docutils literal">__op__()</code> and/or <code class="xref py py-meth docutils literal">__rop__()</code>, the normal

1920

coercion rules apply.

1921

</li>

1922

<li>In <code class="docutils literal">x + y</code>, if x is a sequence that implements sequence concatenation,

1923

sequence concatenation is invoked.

1924

</li>

1925

<li>In <code class="docutils literal">x * y</code>, if one operand is a sequence that implements sequence

1926

repetition, and the other is an integer (<a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a> or <a class="reference internal" href="../library/functions.html#long" title="long"><code class="xref py py-class docutils literal">long</code></a>),

1927

sequence repetition is invoked.

1928

</li>

1929

<li>Rich comparisons (implemented by methods <a class="reference internal" href="#object.__eq__" title="object.__eq__"><code class="xref py py-meth docutils literal">__eq__()</code></a> and so on) never use

1930

coercion. Three-way comparison (implemented by <a class="reference internal" href="#object.__cmp__" title="object.__cmp__"><code class="xref py py-meth docutils literal">__cmp__()</code></a>) does use

1931

coercion under the same conditions as other binary operations use it.

1932

</li>

1933

<li>In the current implementation, the built-in numeric types <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal">int</code></a>,

1934

<a class="reference internal" href="../library/functions.html#long" title="long"><code class="xref py py-class docutils literal">long</code></a>, <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a>, and <a class="reference internal" href="../library/functions.html#complex" title="complex"><code class="xref py py-class docutils literal">complex</code></a> do not use coercion.

1935

All these types implement a <a class="reference internal" href="#object.__coerce__" title="object.__coerce__"><code class="xref py py-meth docutils literal">__coerce__()</code></a> method, for use by the built-in

1936

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

1937

1938

Changed in version 2.7: The complex type no longer makes implicit calls to the <a class="reference internal" href="#object.__coerce__" title="object.__coerce__"><code class="xref py py-meth docutils literal">__coerce__()</code></a>

1939

method for mixed-type binary arithmetic operations.

1940

</div>

1941

</li>

1942

</ul>

1943

</div>

1944

1945

<h3>3.4.10. With Statement Context Managers<a class="headerlink" href="#with-statement-context-managers" title="Permalink to this headline">¶</a></h3>

1946

1947

New in version 2.5.

1948

</div>

1949

A context manager is an object that defines the runtime context to be

1950

established when executing a <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement. The context manager

1951

handles the entry into, and the exit from, the desired runtime context for the

1952

execution of the block of code. Context managers are normally invoked using the

1953

<a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement (described in section <a class="reference internal" href="compound_stmts.html#with">The with statement</a>), but can also be

1954

used by directly invoking their methods.

1955

Typical uses of context managers include saving and restoring various kinds of

1956

global state, locking and unlocking resources, closing opened files, etc.

1957

For more information on context managers, see <a class="reference internal" href="../library/stdtypes.html#typecontextmanager">Context Manager Types</a>.

1958

1959

1960

<code class="descclassname">object.</code><code class="descname">__enter__</code>(self)<a class="headerlink" href="#object.__enter__" title="Permalink to this definition">¶</a></dt>

1961

<dd>Enter the runtime context related to this object. The <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement

1962

will bind this method’s return value to the target(s) specified in the

1963

<a class="reference internal" href="compound_stmts.html#as"><code class="xref std std-keyword docutils literal">as</code></a> clause of the statement, if any.

1964

</dd></dl>

1965

1966

1967

1968

<code class="descclassname">object.</code><code class="descname">__exit__</code>(self, exc_type, exc_value, traceback)<a class="headerlink" href="#object.__exit__" title="Permalink to this definition">¶</a></dt>

1969

<dd>Exit the runtime context related to this object. The parameters describe the

1970

exception that caused the context to be exited. If the context was exited

1971

without an exception, all three arguments will be <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

1972

If an exception is supplied, and the method wishes to suppress the exception

1973

(i.e., prevent it from being propagated), it should return a true value.

1974

Otherwise, the exception will be processed normally upon exit from this method.

1975

Note that <a class="reference internal" href="#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal">__exit__()</code></a> methods should not reraise the passed-in exception;

1976

this is the caller’s responsibility.

1977

</dd></dl>

1978

1979

1980

See also

1981

1982

<dt><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0343">PEP 343</a> - The “with” statement</dt>

1983

<dd>The specification, background, and examples for the Python <a class="reference internal" href="compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a>

1984

statement.</dd>

1985

</dl>

1986

</div>

1987

</div>

1988

1989

<h3>3.4.11. Special method lookup for old-style classes<a class="headerlink" href="#special-method-lookup-for-old-style-classes" title="Permalink to this headline">¶</a></h3>

1990

For old-style classes, special methods are always looked up in exactly the

1991

same way as any other method or attribute. This is the case regardless of

1992

whether the method is being looked up explicitly as in <code class="docutils literal">x.__getitem__(i)</code>

1993

or implicitly as in <code class="docutils literal">x[i]</code>.

1994

This behaviour means that special methods may exhibit different behaviour

1995

for different instances of a single old-style class if the appropriate

1996

special attributes are set differently:

1997

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

1998

... pass

1999

...

2000

>>> c1 = C()

2001

>>> c2 = C()

2002

>>> c1.__len__ = lambda: 5

2003

>>> c2.__len__ = lambda: 9

2004

>>> len(c1)

2005

5

2006

>>> len(c2)

2007

9

2008

</pre></div>

2009

</div>

2010

</div>

2011

2012

<h3>3.4.12. Special method lookup for new-style classes<a class="headerlink" href="#special-method-lookup-for-new-style-classes" title="Permalink to this headline">¶</a></h3>

2013

For new-style classes, implicit invocations of special methods are only guaranteed

2014

to work correctly if defined on an object’s type, not in the object’s instance

2015

dictionary. That behaviour is the reason why the following code raises an

2016

exception (unlike the equivalent example with old-style classes):

2017

<div class="highlight-python"><div class="highlight"><pre>>>> class C(object):

2018

... pass

2019

...

2020

>>> c = C()

2021

>>> c.__len__ = lambda: 5

2022

>>> len(c)

2023

Traceback (most recent call last):

2024

File "<stdin>", line 1, in <module>

2025

TypeError: object of type 'C' has no len()

2026

</pre></div>

2027

</div>

2028

The rationale behind this behaviour lies with a number of special methods such

2029

as <a class="reference internal" href="#object.__hash__" title="object.__hash__"><code class="xref py py-meth docutils literal">__hash__()</code></a> and <a class="reference internal" href="#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal">__repr__()</code></a> that are implemented by all objects,

2030

including type objects. If the implicit lookup of these methods used the

2031

conventional lookup process, they would fail when invoked on the type object

2032

itself:

2033

<div class="highlight-python"><div class="highlight"><pre>>>> 1 .__hash__() == hash(1)

2034

True

2035

>>> int.__hash__() == hash(int)

2036

Traceback (most recent call last):

2037

File "<stdin>", line 1, in <module>

2038

TypeError: descriptor '__hash__' of 'int' object needs an argument

2039

</pre></div>

2040

</div>

2041

Incorrectly attempting to invoke an unbound method of a class in this way is

2042

sometimes referred to as ‘metaclass confusion’, and is avoided by bypassing

2043

the instance when looking up special methods:

2044

<div class="highlight-python"><div class="highlight"><pre>>>> type(1).__hash__(1) == hash(1)

2045

True

2046

>>> type(int).__hash__(int) == hash(int)

2047

True

2048

</pre></div>

2049

</div>

2050

In addition to bypassing any instance attributes in the interest of

2051

correctness, implicit special method lookup generally also bypasses the

2052

2053

<div class="highlight-python"><div class="highlight"><pre>>>> class Meta(type):

2054

... def __getattribute__(*args):

2055

... print "Metaclass getattribute invoked"

2056

... return type.__getattribute__(*args)

2057

...

2058

>>> class C(object):

2059

... __metaclass__ = Meta

2060

... def __len__(self):

2061

... return 10

2062

... def __getattribute__(*args):

2063

... print "Class getattribute invoked"

2064

... return object.__getattribute__(*args)

2065

...

2066

>>> c = C()

2067

>>> c.__len__() # Explicit lookup via instance

2068

Class getattribute invoked

2069

10

2070

>>> type(c).__len__(c) # Explicit lookup via type

2071

Metaclass getattribute invoked

2072

10

2073

>>> len(c) # Implicit lookup

2074

10

2075

</pre></div>

2076

</div>

2077

Bypassing the <a class="reference internal" href="#object.__getattribute__" title="object.__getattribute__"><code class="xref py py-meth docutils literal">__getattribute__()</code></a> machinery in this fashion

2078

provides significant scope for speed optimisations within the

2079

interpreter, at the cost of some flexibility in the handling of

2080

special methods (the special method must be set on the class

2081

object itself in order to be consistently invoked by the interpreter).

2082

Footnotes

2083

2084

2085

2086

<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>It is possible in some cases to change an object’s type, under certain

2087

controlled conditions. It generally isn’t a good idea though, since it can

2088

lead to some very strange behaviour if it is handled incorrectly.</td></tr>

2089

</tbody>

2090

</table>

2091

2092

2093

2094

<tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td>For operands of the same type, it is assumed that if the non-reflected method

2095

(such as <a class="reference internal" href="#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal">__add__()</code></a>) fails the operation is not supported, which is why the

2096

reflected method is not called.</td></tr>

2097

</tbody>

2098

</table>

2099

</div>

2100

</div>

2101

</div>

2102

2103

2104

</div>

2105

</div>

2106

</div>

2107

2108

2109

<h3><a href="../contents.html">Table Of Contents</a></h3>

2110

<ul>

2111

<li><a class="reference internal" href="#">3. Data model</a><ul>

2112

<li><a class="reference internal" href="#objects-values-and-types">3.1. Objects, values and types</a></li>

2113

<li><a class="reference internal" href="#the-standard-type-hierarchy">3.2. The standard type hierarchy</a></li>

2114

<li><a class="reference internal" href="#new-style-and-classic-classes">3.3. New-style and classic classes</a></li>

2115

<li><a class="reference internal" href="#special-method-names">3.4. Special method names</a><ul>

2116

<li><a class="reference internal" href="#basic-customization">3.4.1. Basic customization</a></li>

2117

<li><a class="reference internal" href="#customizing-attribute-access">3.4.2. Customizing attribute access</a><ul>

2118

<li><a class="reference internal" href="#more-attribute-access-for-new-style-classes">3.4.2.1. More attribute access for new-style classes</a></li>

2119

<li><a class="reference internal" href="#implementing-descriptors">3.4.2.2. Implementing Descriptors</a></li>

2120

<li><a class="reference internal" href="#invoking-descriptors">3.4.2.3. Invoking Descriptors</a></li>

2121

<li><a class="reference internal" href="#slots">3.4.2.4. __slots__</a></li>

2122

</ul>

2123

</li>

2124

<li><a class="reference internal" href="#customizing-class-creation">3.4.3. Customizing class creation</a></li>

2125

<li><a class="reference internal" href="#customizing-instance-and-subclass-checks">3.4.4. Customizing instance and subclass checks</a></li>

2126

<li><a class="reference internal" href="#emulating-callable-objects">3.4.5. Emulating callable objects</a></li>

2127

<li><a class="reference internal" href="#emulating-container-types">3.4.6. Emulating container types</a></li>

2128

<li><a class="reference internal" href="#additional-methods-for-emulation-of-sequence-types">3.4.7. Additional methods for emulation of sequence types</a></li>

2129

<li><a class="reference internal" href="#emulating-numeric-types">3.4.8. Emulating numeric types</a></li>

2130

<li><a class="reference internal" href="#coercion-rules">3.4.9. Coercion rules</a></li>

2131

<li><a class="reference internal" href="#with-statement-context-managers">3.4.10. With Statement Context Managers</a></li>

2132

<li><a class="reference internal" href="#special-method-lookup-for-old-style-classes">3.4.11. Special method lookup for old-style classes</a></li>

2133

<li><a class="reference internal" href="#special-method-lookup-for-new-style-classes">3.4.12. Special method lookup for new-style classes</a></li>

2134

</ul>

2135

</li>

2136

</ul>

2137

</li>

2138

</ul>

2139

2140

<h4>Previous topic</h4>

2141

<a href="lexical_analysis.html"

2142

title="previous chapter">2. Lexical analysis</a>

2143

<h4>Next topic</h4>

2144

<a href="executionmodel.html"

2145

title="next chapter">4. Execution model</a>

2146

2147

2148

<li><a href="../bugs.html">Report a Bug</a></li>

2149

<li><a href="../_sources/reference/datamodel.txt"

2150

rel="nofollow">Show Source</a></li>

2151

</ul>

2152

2153

2154

<h3>Quick search</h3>

2155

2156

2157

2158

2159

2160

</form>

2161

2162

Enter search terms or a module, class or function name.

2163

2164

</div>

2165

2166

</div>

2167

</div>

2168

2169

</div>

2170

2171

<h3>Navigation</h3>

2172

<ul>

2173

2174

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

2175

>index</a></li>

2176

2177

<a href="../py-modindex.html" title="Python Module Index"

2178

>modules</a> |</li>

2179

2180

<a href="executionmodel.html" title="4. Execution model"

2181

>next</a> |</li>

2182

2183

<a href="lexical_analysis.html" title="2. Lexical analysis"

2184

>previous</a> |</li>

2185

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

2186

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

2187

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

2188

<li>

2189

2.7.12

2190

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

2191

</li>

2192

2193

<li class="nav-item nav-item-1"><a href="index.html" >The Python Language Reference</a> »</li>

2194

</ul>

2195

</div>

2196

2197

2198

2199

The Python Software Foundation is a non-profit corporation.

2200

<a href="https://www.python.org/psf/donations/">Please donate.</a>

2201

2202

Last updated on Nov 26, 2016.

2203

<a href="../bugs.html">Found a bug</a>?

2204

2205

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

2206

</div>

2207

2208

</body>

2209

</html>

b'\\ No newline at end of file'

Older »