~dkuhlman/python-training-materials/Materials

structure that defines a new type: the <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal">PyTypeObject</code></a> structure. Type

objects can be handled using any of the <code class="xref c c-func docutils literal">PyObject_*()</code> or

<code class="xref c c-func docutils literal">PyType_*()</code> functions, but do not offer much that’s interesting to most

Python applications. These objects are fundamental to how objects behave, so

they are very important to the interpreter itself and to any extension module

that implements new types.

Type objects are fairly large compared to most of the standard types. The reason

for the size is that each type object stores a large number of values, mostly C

function pointers, each of which implements a small part of the type’s

functionality. The fields of the type object are examined in detail in this

section. The fields will be described in the order in which they occur in the

structure.

Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc,

intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,

freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,

reprfunc, hashfunc

The structure definition for <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal">PyTypeObject</code></a> can be found in

<code class="file docutils literal">Include/object.h</code>. For convenience of reference, this repeats the

definition found there:

<div class="highlight-c"><div class="highlight"><pre>typedef struct _typeobject {

100

PyObject_VAR_HEAD

101

const char *tp_name; /* For printing, in format "<module>.<name>" */

102

Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

103

104

/* Methods to implement standard operations */

105

106

destructor tp_dealloc;

107

printfunc tp_print;

108

getattrfunc tp_getattr;

109

setattrfunc tp_setattr;

110

PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)

111

or tp_reserved (Python 3) */

112

reprfunc tp_repr;

113

114

/* Method suites for standard classes */

115

116

PyNumberMethods *tp_as_number;

117

PySequenceMethods *tp_as_sequence;

118

PyMappingMethods *tp_as_mapping;

119

120

/* More standard operations (here for binary compatibility) */

121

122

hashfunc tp_hash;

123

ternaryfunc tp_call;

124

reprfunc tp_str;

125

getattrofunc tp_getattro;

126

setattrofunc tp_setattro;

127

128

/* Functions to access object as input/output buffer */

129

PyBufferProcs *tp_as_buffer;

130

131

/* Flags to define presence of optional/expanded features */

132

unsigned long tp_flags;

133

134

const char *tp_doc; /* Documentation string */

135

136

/* call function for all accessible objects */

137

traverseproc tp_traverse;

138

139

/* delete references to contained objects */

140

inquiry tp_clear;

141

142

/* rich comparisons */

143

richcmpfunc tp_richcompare;

144

145

/* weak reference enabler */

146

Py_ssize_t tp_weaklistoffset;

147

148

/* Iterators */

149

getiterfunc tp_iter;

150

iternextfunc tp_iternext;

151

152

/* Attribute descriptor and subclassing stuff */

153

struct PyMethodDef *tp_methods;

154

struct PyMemberDef *tp_members;

155

struct PyGetSetDef *tp_getset;

156

struct _typeobject *tp_base;

157

PyObject *tp_dict;

158

descrgetfunc tp_descr_get;

159

descrsetfunc tp_descr_set;

160

Py_ssize_t tp_dictoffset;

161

initproc tp_init;

162

allocfunc tp_alloc;

163

newfunc tp_new;

164

freefunc tp_free; /* Low-level free-memory routine */

165

inquiry tp_is_gc; /* For PyObject_IS_GC */

166

PyObject *tp_bases;

167

PyObject *tp_mro; /* method resolution order */

168

PyObject *tp_cache;

169

PyObject *tp_subclasses;

170

PyObject *tp_weaklist;

171

destructor tp_del;

172

173

/* Type attribute cache version tag. Added in version 2.6 */

174

unsigned int tp_version_tag;

175

176

destructor tp_finalize;

177

178

} PyTypeObject;

179

</pre></div>

180

</div>

181

The type object structure extends the <a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal">PyVarObject</code></a> structure. The

182

<code class="xref py py-attr docutils literal">ob_size</code> field is used for dynamic types (created by <code class="xref py py-func docutils literal">type_new()</code>,

183

usually called from a class statement). Note that <a class="reference internal" href="type.html#c.PyType_Type" title="PyType_Type"><code class="xref c c-data docutils literal">PyType_Type</code></a> (the

184

metatype) initializes <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a>, which means that its instances (i.e.

185

type objects) must have the <code class="xref py py-attr docutils literal">ob_size</code> field.

186

187

188

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject._ob_next</code><a class="headerlink" href="#c.PyObject._ob_next" title="Permalink to this definition">¶</a></dt>

189

190

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject._ob_prev</code><a class="headerlink" href="#c.PyObject._ob_prev" title="Permalink to this definition">¶</a></dt>

191

<dd>These fields are only present when the macro <code class="docutils literal">Py_TRACE_REFS</code> is defined.

192

Their initialization to NULL is taken care of by the <code class="docutils literal">PyObject_HEAD_INIT</code>

193

macro. For statically allocated objects, these fields always remain NULL.

194

For dynamically allocated objects, these two fields are used to link the object

195

into a doubly-linked list of all live objects on the heap. This could be used

196

for various debugging purposes; currently the only use is to print the objects

197

that are still alive at the end of a run when the environment variable

198

<a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDUMPREFS"><code class="xref std std-envvar docutils literal">PYTHONDUMPREFS</code></a> is set.

199

These fields are not inherited by subtypes.

200

</dd></dl>

201

202

203

204

Py_ssize_t <code class="descname">PyObject.ob_refcnt</code><a class="headerlink" href="#c.PyObject.ob_refcnt" title="Permalink to this definition">¶</a></dt>

205

<dd>This is the type object’s reference count, initialized to <code class="docutils literal">1</code> by the

206

<code class="docutils literal">PyObject_HEAD_INIT</code> macro. Note that for statically allocated type objects,

207

the type’s instances (objects whose <code class="xref py py-attr docutils literal">ob_type</code> points back to the type) do

208

not count as references. But for dynamically allocated type objects, the

209

instances do count as references.

210

This field is not inherited by subtypes.

211

</dd></dl>

212

213

214

215

<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyObject.ob_type</code><a class="headerlink" href="#c.PyObject.ob_type" title="Permalink to this definition">¶</a></dt>

216

<dd>This is the type’s type, in other words its metatype. It is initialized by the

217

argument to the <code class="docutils literal">PyObject_HEAD_INIT</code> macro, and its value should normally be

218

<code class="docutils literal">&PyType_Type</code>. However, for dynamically loadable extension modules that must

219

be usable on Windows (at least), the compiler complains that this is not a valid

220

initializer. Therefore, the convention is to pass NULL to the

221

<code class="docutils literal">PyObject_HEAD_INIT</code> macro and to initialize this field explicitly at the

222

start of the module’s initialization function, before doing anything else. This

223

is typically done like this:

224

<div class="highlight-c"><div class="highlight"><pre>Foo_Type.ob_type = &PyType_Type;

225

</pre></div>

226

</div>

227

This should be done before any instances of the type are created.

228

<a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal">PyType_Ready()</code></a> checks if <code class="xref py py-attr docutils literal">ob_type</code> is NULL, and if so,

229

initializes it to the <code class="xref py py-attr docutils literal">ob_type</code> field of the base class.

230

231

This field is inherited by subtypes.

232

</dd></dl>

233

234

235

236

Py_ssize_t <code class="descname">PyVarObject.ob_size</code><a class="headerlink" href="#c.PyVarObject.ob_size" title="Permalink to this definition">¶</a></dt>

237

<dd>For statically allocated type objects, this should be initialized to zero. For

238

dynamically allocated type objects, this field has a special internal meaning.

239

This field is not inherited by subtypes.

240

</dd></dl>

241

242

243

244

const char* <code class="descname">PyTypeObject.tp_name</code><a class="headerlink" href="#c.PyTypeObject.tp_name" title="Permalink to this definition">¶</a></dt>

245

<dd>Pointer to a NUL-terminated string containing the name of the type. For types

246

that are accessible as module globals, the string should be the full module

247

name, followed by a dot, followed by the type name; for built-in types, it

248

should be just the type name. If the module is a submodule of a package, the

249

full package name is part of the full module name. For example, a type named

250

<code class="xref py py-class docutils literal">T</code> defined in module <code class="xref py py-mod docutils literal">M</code> in subpackage <code class="xref py py-mod docutils literal">Q</code> in package <code class="xref py py-mod docutils literal">P</code>

251

should have the <a class="reference internal" href="#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal">tp_name</code></a> initializer <code class="docutils literal">"P.Q.M.T"</code>.

252

For dynamically allocated type objects, this should just be the type name, and

253

the module name explicitly stored in the type dict as the value for key

254

<code class="docutils literal">'__module__'</code>.

255

For statically allocated type objects, the tp_name field should contain a dot.

256

Everything before the last dot is made accessible as the <code class="xref py py-attr docutils literal">__module__</code>

257

attribute, and everything after the last dot is made accessible as the

258

<a class="reference internal" href="../reference/import.html#__name__" title="__name__"><code class="xref py py-attr docutils literal">__name__</code></a> attribute.

259

If no dot is present, the entire <a class="reference internal" href="#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal">tp_name</code></a> field is made accessible as the

260

<a class="reference internal" href="../reference/import.html#__name__" title="__name__"><code class="xref py py-attr docutils literal">__name__</code></a> attribute, and the <code class="xref py py-attr docutils literal">__module__</code> attribute is undefined

261

(unless explicitly set in the dictionary, as explained above). This means your

262

type will be impossible to pickle.

263

This field is not inherited by subtypes.

264

</dd></dl>

265

266

267

268

Py_ssize_t <code class="descname">PyTypeObject.tp_basicsize</code><a class="headerlink" href="#c.PyTypeObject.tp_basicsize" title="Permalink to this definition">¶</a></dt>

269

270

Py_ssize_t <code class="descname">PyTypeObject.tp_itemsize</code><a class="headerlink" href="#c.PyTypeObject.tp_itemsize" title="Permalink to this definition">¶</a></dt>

271

<dd>These fields allow calculating the size in bytes of instances of the type.

272

There are two kinds of types: types with fixed-length instances have a zero

273

<a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a> field, types with variable-length instances have a non-zero

274

275

instances have the same size, given in <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a>.

276

For a type with variable-length instances, the instances must have an

277

<code class="xref py py-attr docutils literal">ob_size</code> field, and the instance size is <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a> plus N

278

times <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a>, where N is the “length” of the object. The value of

279

N is typically stored in the instance’s <code class="xref py py-attr docutils literal">ob_size</code> field. There are

280

exceptions: for example, ints use a negative <code class="xref py py-attr docutils literal">ob_size</code> to indicate a

281

negative number, and N is <code class="docutils literal">abs(ob_size)</code> there. Also, the presence of an

282

<code class="xref py py-attr docutils literal">ob_size</code> field in the instance layout doesn’t mean that the instance

283

structure is variable-length (for example, the structure for the list type has

284

fixed-length instances, yet those instances have a meaningful <code class="xref py py-attr docutils literal">ob_size</code>

285

field).

286

The basic size includes the fields in the instance declared by the macro

287

<a class="reference internal" href="structures.html#c.PyObject_HEAD" title="PyObject_HEAD"><code class="xref c c-macro docutils literal">PyObject_HEAD</code></a> or <a class="reference internal" href="structures.html#c.PyObject_VAR_HEAD" title="PyObject_VAR_HEAD"><code class="xref c c-macro docutils literal">PyObject_VAR_HEAD</code></a> (whichever is used to

288

declare the instance struct) and this in turn includes the <code class="xref py py-attr docutils literal">_ob_prev</code> and

289

<code class="xref py py-attr docutils literal">_ob_next</code> fields if they are present. This means that the only correct

290

way to get an initializer for the <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a> is to use the

291

<code class="docutils literal">sizeof</code> operator on the struct used to declare the instance layout.

292

The basic size does not include the GC header size.

293

These fields are inherited separately by subtypes. If the base type has a

294

non-zero <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a>, it is generally not safe to set

295

<a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a> to a different non-zero value in a subtype (though this

296

depends on the implementation of the base type).

297

A note about alignment: if the variable items require a particular alignment,

298

this should be taken care of by the value of <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a>. Example:

299

suppose a type implements an array of <code class="docutils literal">double</code>. <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a> is

300

<code class="docutils literal">sizeof(double)</code>. It is the programmer’s responsibility that

301

<a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a> is a multiple of <code class="docutils literal">sizeof(double)</code> (assuming this is the

302

alignment requirement for <code class="docutils literal">double</code>).

303

</dd></dl>

304

305

306

307

destructor <code class="descname">PyTypeObject.tp_dealloc</code><a class="headerlink" href="#c.PyTypeObject.tp_dealloc" title="Permalink to this definition">¶</a></dt>

308

<dd>A pointer to the instance destructor function. This function must be defined

309

unless the type guarantees that its instances will never be deallocated (as is

310

the case for the singletons <code class="docutils literal">None</code> and <code class="docutils literal">Ellipsis</code>).

311

The destructor function is called by the <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal">Py_DECREF()</code></a> and

312

<a class="reference internal" href="refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal">Py_XDECREF()</code></a> macros when the new reference count is zero. At this point,

313

the instance is still in existence, but there are no references to it. The

314

destructor function should free all references which the instance owns, free all

315

memory buffers owned by the instance (using the freeing function corresponding

316

to the allocation function used to allocate the buffer), and finally (as its

317

last action) call the type’s <a class="reference internal" href="#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal">tp_free</code></a> function. If the type is not

318

subtypable (doesn’t have the <a class="reference internal" href="#Py_TPFLAGS_BASETYPE" title="Py_TPFLAGS_BASETYPE"><code class="xref py py-const docutils literal">Py_TPFLAGS_BASETYPE</code></a> flag bit set), it is

319

permissible to call the object deallocator directly instead of via

320

<a class="reference internal" href="#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal">tp_free</code></a>. The object deallocator should be the one used to allocate the

321

instance; this is normally <a class="reference internal" href="allocation.html#c.PyObject_Del" title="PyObject_Del"><code class="xref c c-func docutils literal">PyObject_Del()</code></a> if the instance was allocated

322

using <a class="reference internal" href="allocation.html#c.PyObject_New" title="PyObject_New"><code class="xref c c-func docutils literal">PyObject_New()</code></a> or <code class="xref c c-func docutils literal">PyObject_VarNew()</code>, or

323

<a class="reference internal" href="gcsupport.html#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal">PyObject_GC_Del()</code></a> if the instance was allocated using

324

<a class="reference internal" href="gcsupport.html#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal">PyObject_GC_New()</code></a> or <a class="reference internal" href="gcsupport.html#c.PyObject_GC_NewVar" title="PyObject_GC_NewVar"><code class="xref c c-func docutils literal">PyObject_GC_NewVar()</code></a>.

325

This field is inherited by subtypes.

326

</dd></dl>

327

328

329

330

printfunc <code class="descname">PyTypeObject.tp_print</code><a class="headerlink" href="#c.PyTypeObject.tp_print" title="Permalink to this definition">¶</a></dt>

331

<dd>Reserved slot, formerly used for print formatting in Python 2.x.

332

</dd></dl>

333

334

335

336

getattrfunc <code class="descname">PyTypeObject.tp_getattr</code><a class="headerlink" href="#c.PyTypeObject.tp_getattr" title="Permalink to this definition">¶</a></dt>

337

<dd>An optional pointer to the get-attribute-string function.

338

This field is deprecated. When it is defined, it should point to a function

339

that acts the same as the <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal">tp_getattro</code></a> function, but taking a C string

340

instead of a Python string object to give the attribute name. The signature is

341

the same as for <a class="reference internal" href="object.html#c.PyObject_GetAttrString" title="PyObject_GetAttrString"><code class="xref c c-func docutils literal">PyObject_GetAttrString()</code></a>.

342

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal">tp_getattro</code></a>: a subtype

343

inherits both <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal">tp_getattr</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal">tp_getattro</code></a> from its base type when

344

the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal">tp_getattr</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal">tp_getattro</code></a> are both NULL.

345

</dd></dl>

346

347

348

349

setattrfunc <code class="descname">PyTypeObject.tp_setattr</code><a class="headerlink" href="#c.PyTypeObject.tp_setattr" title="Permalink to this definition">¶</a></dt>

350

<dd>An optional pointer to the function for setting and deleting attributes.

351

This field is deprecated. When it is defined, it should point to a function

352

that acts the same as the <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal">tp_setattro</code></a> function, but taking a C string

353

instead of a Python string object to give the attribute name. The signature is

354

the same as for <a class="reference internal" href="object.html#c.PyObject_SetAttrString" title="PyObject_SetAttrString"><code class="xref c c-func docutils literal">PyObject_SetAttrString()</code></a>, but setting

355

v to NULL to delete an attribute must be supported.

356

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal">tp_setattro</code></a>: a subtype

357

inherits both <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal">tp_setattr</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal">tp_setattro</code></a> from its base type when

358

the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal">tp_setattr</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal">tp_setattro</code></a> are both NULL.

359

</dd></dl>

360

361

362

363

<a class="reference internal" href="#c.PyAsyncMethods" title="PyAsyncMethods">PyAsyncMethods</a>* <code class="descname">tp_as_async</code><a class="headerlink" href="#c.tp_as_async" title="Permalink to this definition">¶</a></dt>

364

<dd>Pointer to an additional structure that contains fields relevant only to

365

objects which implement <a class="reference internal" href="../glossary.html#term-awaitable">awaitable</a> and <a class="reference internal" href="../glossary.html#term-asynchronous-iterator">asynchronous iterator</a>

366

protocols at the C-level. See <a class="reference internal" href="#async-structs">Async Object Structures</a> for details.

367

368

New in version 3.5: Formerly known as <code class="docutils literal">tp_compare</code> and <code class="docutils literal">tp_reserved</code>.

369

</div>

370

</dd></dl>

371

372

373

374

reprfunc <code class="descname">PyTypeObject.tp_repr</code><a class="headerlink" href="#c.PyTypeObject.tp_repr" title="Permalink to this definition">¶</a></dt>

375

<dd>An optional pointer to a function that implements the built-in function

376

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

377

The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal">PyObject_Repr()</code></a>; it must return a string

378

or a Unicode object. Ideally, this function should return a string that, when

379

passed to <a class="reference internal" href="../library/functions.html#eval" title="eval"><code class="xref py py-func docutils literal">eval()</code></a>, given a suitable environment, returns an object with the

380

same value. If this is not feasible, it should return a string starting with

381

<code class="docutils literal">'<'</code> and ending with <code class="docutils literal">'>'</code> from which both the type and the value of the

382

object can be deduced.

383

When this field is not set, a string of the form <code class="docutils literal"><%s object at %p></code> is

384

returned, where <code class="docutils literal">%s</code> is replaced by the type name, and <code class="docutils literal">%p</code> by the object’s

385

memory address.

386

This field is inherited by subtypes.

387

</dd></dl>

388

389

390

391

<a class="reference internal" href="#c.PyNumberMethods" title="PyNumberMethods">PyNumberMethods</a>* <code class="descname">tp_as_number</code><a class="headerlink" href="#c.tp_as_number" title="Permalink to this definition">¶</a></dt>

392

<dd>Pointer to an additional structure that contains fields relevant only to

393

objects which implement the number protocol. These fields are documented in

394

<a class="reference internal" href="#number-structs">Number Object Structures</a>.

395

The <code class="xref c c-member docutils literal">tp_as_number</code> field is not inherited, but the contained fields are

396

inherited individually.

397

</dd></dl>

398

399

400

401

<a class="reference internal" href="#c.PySequenceMethods" title="PySequenceMethods">PySequenceMethods</a>* <code class="descname">tp_as_sequence</code><a class="headerlink" href="#c.tp_as_sequence" title="Permalink to this definition">¶</a></dt>

402

<dd>Pointer to an additional structure that contains fields relevant only to

403

objects which implement the sequence protocol. These fields are documented

404

in <a class="reference internal" href="#sequence-structs">Sequence Object Structures</a>.

405

The <code class="xref c c-member docutils literal">tp_as_sequence</code> field is not inherited, but the contained fields

406

are inherited individually.

407

</dd></dl>

408

409

410

411

<a class="reference internal" href="#c.PyMappingMethods" title="PyMappingMethods">PyMappingMethods</a>* <code class="descname">tp_as_mapping</code><a class="headerlink" href="#c.tp_as_mapping" title="Permalink to this definition">¶</a></dt>

412

<dd>Pointer to an additional structure that contains fields relevant only to

413

objects which implement the mapping protocol. These fields are documented in

414

<a class="reference internal" href="#mapping-structs">Mapping Object Structures</a>.

415

The <code class="xref c c-member docutils literal">tp_as_mapping</code> field is not inherited, but the contained fields

416

are inherited individually.

417

</dd></dl>

418

419

420

421

hashfunc <code class="descname">PyTypeObject.tp_hash</code><a class="headerlink" href="#c.PyTypeObject.tp_hash" title="Permalink to this definition">¶</a></dt>

422

<dd>An optional pointer to a function that implements the built-in function

423

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

424

The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Hash" title="PyObject_Hash"><code class="xref c c-func docutils literal">PyObject_Hash()</code></a>; it must return a

425

value of the type Py_hash_t. The value <code class="docutils literal">-1</code> should not be returned as a

426

normal return value; when an error occurs during the computation of the hash

427

value, the function should set an exception and return <code class="docutils literal">-1</code>.

428

This field can be set explicitly to <a class="reference internal" href="object.html#c.PyObject_HashNotImplemented" title="PyObject_HashNotImplemented"><code class="xref c c-func docutils literal">PyObject_HashNotImplemented()</code></a> to

429

block inheritance of the hash method from a parent type. This is interpreted

430

as the equivalent of <code class="docutils literal">__hash__ = None</code> at the Python level, causing

431

<code class="docutils literal">isinstance(o, collections.Hashable)</code> to correctly return <code class="docutils literal">False</code>. Note

432

that the converse is also true - setting <code class="docutils literal">__hash__ = None</code> on a class at

433

the Python level will result in the <code class="docutils literal">tp_hash</code> slot being set to

434

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

435

When this field is not set, an attempt to take the hash of the

436

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

437

This field is inherited by subtypes together with

438

439

<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal">tp_richcompare</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal">tp_hash</code></a>, when the subtype’s

440

441

</dd></dl>

442

443

444

445

ternaryfunc <code class="descname">PyTypeObject.tp_call</code><a class="headerlink" href="#c.PyTypeObject.tp_call" title="Permalink to this definition">¶</a></dt>

446

<dd>An optional pointer to a function that implements calling the object. This

447

should be NULL if the object is not callable. The signature is the same as

448

for <a class="reference internal" href="object.html#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal">PyObject_Call()</code></a>.

449

This field is inherited by subtypes.

450

</dd></dl>

451

452

453

454

reprfunc <code class="descname">PyTypeObject.tp_str</code><a class="headerlink" href="#c.PyTypeObject.tp_str" title="Permalink to this definition">¶</a></dt>

455

<dd>An optional pointer to a function that implements the built-in operation

456

<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal">str()</code></a>. (Note that <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> is a type now, and <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-func docutils literal">str()</code></a> calls the

457

constructor for that type. This constructor calls <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal">PyObject_Str()</code></a> to do

458

the actual work, and <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal">PyObject_Str()</code></a> will call this handler.)

459

The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal">PyObject_Str()</code></a>; it must return a string

460

or a Unicode object. This function should return a “friendly” string

461

representation of the object, as this is the representation that will be used,

462

among other things, by the <a class="reference internal" href="../library/functions.html#print" title="print"><code class="xref py py-func docutils literal">print()</code></a> function.

463

When this field is not set, <a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal">PyObject_Repr()</code></a> is called to return a string

464

representation.

465

This field is inherited by subtypes.

466

</dd></dl>

467

468

469

470

getattrofunc <code class="descname">PyTypeObject.tp_getattro</code><a class="headerlink" href="#c.PyTypeObject.tp_getattro" title="Permalink to this definition">¶</a></dt>

471

<dd>An optional pointer to the get-attribute function.

472

The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal">PyObject_GetAttr()</code></a>. It is usually

473

convenient to set this field to <a class="reference internal" href="object.html#c.PyObject_GenericGetAttr" title="PyObject_GenericGetAttr"><code class="xref c c-func docutils literal">PyObject_GenericGetAttr()</code></a>, which

474

implements the normal way of looking for object attributes.

475

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal">tp_getattr</code></a>: a subtype

476

477

478

</dd></dl>

479

480

481

482

setattrofunc <code class="descname">PyTypeObject.tp_setattro</code><a class="headerlink" href="#c.PyTypeObject.tp_setattro" title="Permalink to this definition">¶</a></dt>

483

<dd>An optional pointer to the function for setting and deleting attributes.

484

The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_SetAttr" title="PyObject_SetAttr"><code class="xref c c-func docutils literal">PyObject_SetAttr()</code></a>, but setting

485

v to NULL to delete an attribute must be supported. It is usually

486

convenient to set this field to <a class="reference internal" href="object.html#c.PyObject_GenericSetAttr" title="PyObject_GenericSetAttr"><code class="xref c c-func docutils literal">PyObject_GenericSetAttr()</code></a>, which

487

implements the normal way of setting object attributes.

488

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal">tp_setattr</code></a>: a subtype

489

490

491

</dd></dl>

492

493

494

495

<a class="reference internal" href="#c.PyBufferProcs" title="PyBufferProcs">PyBufferProcs</a>* <code class="descname">PyTypeObject.tp_as_buffer</code><a class="headerlink" href="#c.PyTypeObject.tp_as_buffer" title="Permalink to this definition">¶</a></dt>

496

<dd>Pointer to an additional structure that contains fields relevant only to objects

497

which implement the buffer interface. These fields are documented in

498

<a class="reference internal" href="#buffer-structs">Buffer Object Structures</a>.

499

The <a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal">tp_as_buffer</code></a> field is not inherited, but the contained fields are

500

inherited individually.

501

</dd></dl>

502

503

504

505

unsigned long <code class="descname">PyTypeObject.tp_flags</code><a class="headerlink" href="#c.PyTypeObject.tp_flags" title="Permalink to this definition">¶</a></dt>

506

<dd>This field is a bit mask of various flags. Some flags indicate variant

507

semantics for certain situations; others are used to indicate that certain

508

fields in the type object (or in the extension structures referenced via

509

<code class="xref c c-member docutils literal">tp_as_number</code>, <code class="xref c c-member docutils literal">tp_as_sequence</code>, <code class="xref c c-member docutils literal">tp_as_mapping</code>, and

510

<a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal">tp_as_buffer</code></a>) that were historically not always present are valid; if

511

such a flag bit is clear, the type fields it guards must not be accessed and

512

must be considered to have a zero or NULL value instead.

513

Inheritance of this field is complicated. Most flag bits are inherited

514

individually, i.e. if the base type has a flag bit set, the subtype inherits

515

this flag bit. The flag bits that pertain to extension structures are strictly

516

inherited if the extension structure is inherited, i.e. the base type’s value of

517

the flag bit is copied into the subtype together with a pointer to the extension

518

structure. The <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_GC</code></a> flag bit is inherited together with

519

the <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> fields, i.e. if the

520

521

<a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> fields in the subtype exist and have

522

NULL values.

523

The following bit masks are currently defined; these can be ORed together using

524

the <code class="docutils literal">|</code> operator to form the value of the <a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal">tp_flags</code></a> field. The macro

525

<a class="reference internal" href="type.html#c.PyType_HasFeature" title="PyType_HasFeature"><code class="xref c c-func docutils literal">PyType_HasFeature()</code></a> takes a type and a flags value, tp and f, and

526

checks whether <code class="docutils literal">tp->tp_flags & f</code> is non-zero.

527

528

529

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

530

<dd>This bit is set when the type object itself is allocated on the heap. In this

531

case, the <code class="xref py py-attr docutils literal">ob_type</code> field of its instances is considered a reference to

532

the type, and the type object is INCREF’ed when a new instance is created, and

533

DECREF’ed when an instance is destroyed (this does not apply to instances of

534

subtypes; only the type referenced by the instance’s ob_type gets INCREF’ed or

535

DECREF’ed).

536

</dd></dl>

537

538

539

540

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

541

<dd>This bit is set when the type can be used as the base type of another type. If

542

this bit is clear, the type cannot be subtyped (similar to a “final” class in

543

Java).

544

</dd></dl>

545

546

547

548

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

549

<dd>This bit is set when the type object has been fully initialized by

550

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

551

</dd></dl>

552

553

554

555

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

556

<dd>This bit is set while <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal">PyType_Ready()</code></a> is in the process of initializing

557

the type object.

558

</dd></dl>

559

560

561

562

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

563

<dd>This bit is set when the object supports garbage collection. If this bit

564

is set, instances must be created using <a class="reference internal" href="gcsupport.html#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal">PyObject_GC_New()</code></a> and

565

destroyed using <a class="reference internal" href="gcsupport.html#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal">PyObject_GC_Del()</code></a>. More information in section

566

<a class="reference internal" href="gcsupport.html#supporting-cycle-detection">Supporting Cyclic Garbage Collection</a>. This bit also implies that the

567

GC-related fields <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> are present in

568

the type object.

569

</dd></dl>

570

571

572

573

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

574

<dd>This is a bitmask of all the bits that pertain to the existence of certain

575

fields in the type object and its extension structures. Currently, it includes

576

the following bits: <code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_STACKLESS_EXTENSION</code>,

577

<code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_VERSION_TAG</code>.

578

</dd></dl>

579

580

581

582

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

583

584

585

586

587

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

588

589

590

591

592

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

593

594

595

596

597

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

598

599

600

601

602

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

603

604

605

606

607

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

608

609

610

611

612

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

613

614

615

616

617

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

618

<dd>These flags are used by functions such as

619

<a class="reference internal" href="long.html#c.PyLong_Check" title="PyLong_Check"><code class="xref c c-func docutils literal">PyLong_Check()</code></a> to quickly determine if a type is a subclass

620

of a built-in type; such specific checks are faster than a generic

621

check, like <a class="reference internal" href="object.html#c.PyObject_IsInstance" title="PyObject_IsInstance"><code class="xref c c-func docutils literal">PyObject_IsInstance()</code></a>. Custom types that inherit

622

from built-ins should have their <a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal">tp_flags</code></a>

623

set appropriately, or the code that interacts with such types

624

will behave differently depending on what kind of check is used.

625

</dd></dl>

626

627

628

629

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

630

<dd>This bit is set when the <a class="reference internal" href="#c.PyTypeObject.tp_finalize" title="PyTypeObject.tp_finalize"><code class="xref c c-member docutils literal">tp_finalize</code></a> slot is present in the

631

type structure.

632

633

New in version 3.4.

634

</div>

635

</dd></dl>

636

637

</dd></dl>

638

639

640

641

const char* <code class="descname">PyTypeObject.tp_doc</code><a class="headerlink" href="#c.PyTypeObject.tp_doc" title="Permalink to this definition">¶</a></dt>

642

<dd>An optional pointer to a NUL-terminated C string giving the docstring for this

643

type object. This is exposed as the <code class="xref py py-attr docutils literal">__doc__</code> attribute on the type and

644

instances of the type.

645

This field is not inherited by subtypes.

646

</dd></dl>

647

648

649

650

<a class="reference internal" href="gcsupport.html#c.traverseproc" title="traverseproc">traverseproc</a> <code class="descname">PyTypeObject.tp_traverse</code><a class="headerlink" href="#c.PyTypeObject.tp_traverse" title="Permalink to this definition">¶</a></dt>

651

<dd>An optional pointer to a traversal function for the garbage collector. This is

652

only used if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_GC</code></a> flag bit is set. More information

653

about Python’s garbage collection scheme can be found in section

654

<a class="reference internal" href="gcsupport.html#supporting-cycle-detection">Supporting Cyclic Garbage Collection</a>.

655

The <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> pointer is used by the garbage collector to detect

656

reference cycles. A typical implementation of a <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> function

657

simply calls <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal">Py_VISIT()</code></a> on each of the instance’s members that are Python

658

objects. For example, this is function <code class="xref c c-func docutils literal">local_traverse()</code> from the

659

<a class="reference internal" href="../library/_thread.html#module-_thread" title="_thread: Low-level threading API."><code class="xref py py-mod docutils literal">_thread</code></a> extension module:

660

<div class="highlight-c"><div class="highlight"><pre>static int

661

local_traverse(localobject *self, visitproc visit, void *arg)

662

{

663

Py_VISIT(self->args);

664

Py_VISIT(self->kw);

665

Py_VISIT(self->dict);

666

return 0;

667

}

668

</pre></div>

669

</div>

670

Note that <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal">Py_VISIT()</code></a> is called only on those members that can participate

671

in reference cycles. Although there is also a <code class="docutils literal">self->key</code> member, it can only

672

be NULL or a Python string and therefore cannot be part of a reference cycle.

673

On the other hand, even if you know a member can never be part of a cycle, as a

674

debugging aid you may want to visit it anyway just so 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’s

675

<a class="reference internal" href="../library/gc.html#gc.get_referents" title="gc.get_referents"><code class="xref py py-func docutils literal">get_referents()</code></a> function will include it.

676

Note that <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal">Py_VISIT()</code></a> requires the visit and arg parameters to

677

<code class="xref c c-func docutils literal">local_traverse()</code> to have these specific names; don’t name them just

678

anything.

679

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> and the

680

<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_GC</code></a> flag bit: the flag bit, <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a>, and

681

<a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> are all inherited from the base type if they are all zero in

682

the subtype.

683

</dd></dl>

684

685

686

687

<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry">inquiry</a> <code class="descname">PyTypeObject.tp_clear</code><a class="headerlink" href="#c.PyTypeObject.tp_clear" title="Permalink to this definition">¶</a></dt>

688

<dd>An optional pointer to a clear function for the garbage collector. This is only

689

used if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_GC</code></a> flag bit is set.

690

The <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> member function is used to break reference cycles in cyclic

691

garbage detected by the garbage collector. Taken together, all <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a>

692

functions in the system must combine to break all reference cycles. This is

693

subtle, and if in any doubt supply a <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> function. For example,

694

the tuple type does not implement a <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> function, because it’s

695

possible to prove that no reference cycle can be composed entirely of tuples.

696

Therefore the <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> functions of other types must be sufficient to

697

break any cycle containing a tuple. This isn’t immediately obvious, and there’s

698

rarely a good reason to avoid implementing <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a>.

699

Implementations of <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> should drop the instance’s references to

700

those of its members that may be Python objects, and set its pointers to those

701

members to NULL, as in the following example:

702

<div class="highlight-c"><div class="highlight"><pre>static int

703

local_clear(localobject *self)

704

{

705

Py_CLEAR(self->key);

706

Py_CLEAR(self->args);

707

Py_CLEAR(self->kw);

708

Py_CLEAR(self->dict);

709

return 0;

710

}

711

</pre></div>

712

</div>

713

The <a class="reference internal" href="refcounting.html#c.Py_CLEAR" title="Py_CLEAR"><code class="xref c c-func docutils literal">Py_CLEAR()</code></a> macro should be used, because clearing references is

714

delicate: the reference to the contained object must not be decremented until

715

after the pointer to the contained object is set to NULL. This is because

716

decrementing the reference count may cause the contained object to become trash,

717

triggering a chain of reclamation activity that may include invoking arbitrary

718

Python code (due to finalizers, or weakref callbacks, associated with the

719

contained object). If it’s possible for such code to reference self again,

720

it’s important that the pointer to the contained object be NULL at that time,

721

so that self knows the contained object can no longer be used. The

722

<a class="reference internal" href="refcounting.html#c.Py_CLEAR" title="Py_CLEAR"><code class="xref c c-func docutils literal">Py_CLEAR()</code></a> macro performs the operations in a safe order.

723

Because the goal of <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a> functions is to break reference cycles,

724

it’s not necessary to clear contained objects like Python strings or Python

725

integers, which can’t participate in reference cycles. On the other hand, it may

726

be convenient to clear all contained Python objects, and write the type’s

727

<a class="reference internal" href="#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code class="xref c c-member docutils literal">tp_dealloc</code></a> function to invoke <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal">tp_clear</code></a>.

728

More information about Python’s garbage collection scheme can be found in

729

section <a class="reference internal" href="gcsupport.html#supporting-cycle-detection">Supporting Cyclic Garbage Collection</a>.

730

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal">tp_traverse</code></a> and the

731

732

733

the subtype.

734

</dd></dl>

735

736

737

738

richcmpfunc <code class="descname">PyTypeObject.tp_richcompare</code><a class="headerlink" href="#c.PyTypeObject.tp_richcompare" title="Permalink to this definition">¶</a></dt>

739

<dd>An optional pointer to the rich comparison function, whose signature is

740

<code class="docutils literal">PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)</code>. The first

741

parameter is guaranteed to be an instance of the type that is defined

742

by <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal">PyTypeObject</code></a>.

743

The function should return the result of the comparison (usually <code class="docutils literal">Py_True</code>

744

or <code class="docutils literal">Py_False</code>). If the comparison is undefined, it must return

745

<code class="docutils literal">Py_NotImplemented</code>, if another error occurred it must return <code class="docutils literal">NULL</code> and

746

set an exception condition.

747

748

Note

749

If you want to implement a type for which only a limited set of

750

comparisons makes sense (e.g. <code class="docutils literal">==</code> and <code class="docutils literal">!=</code>, but not <code class="docutils literal"><</code> and

751

friends), directly raise <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> in the rich comparison function.

752

</div>

753

This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal">tp_hash</code></a>:

754

a subtype inherits <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal">tp_richcompare</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal">tp_hash</code></a> when

755

the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal">tp_richcompare</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal">tp_hash</code></a> are both

756

NULL.

757

The following constants are defined to be used as the third argument for

758

<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal">tp_richcompare</code></a> and for <a class="reference internal" href="object.html#c.PyObject_RichCompare" title="PyObject_RichCompare"><code class="xref c c-func docutils literal">PyObject_RichCompare()</code></a>:

759

760

761

762

763

</colgroup>

764

765

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

766

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

767

</tr>

768

</thead>

769

770

771

772

</tr>

773

774

775

</tr>

776

777

778

</tr>

779

780

781

</tr>

782

783

784

</tr>

785

786

787

</tr>

788

</tbody>

789

</table>

790

</dd></dl>

791

792

793

794

Py_ssize_t <code class="descname">PyTypeObject.tp_weaklistoffset</code><a class="headerlink" href="#c.PyTypeObject.tp_weaklistoffset" title="Permalink to this definition">¶</a></dt>

795

<dd>If the instances of this type are weakly referenceable, this field is greater

796

than zero and contains the offset in the instance structure of the weak

797

reference list head (ignoring the GC header, if present); this offset is used by

798

<code class="xref c c-func docutils literal">PyObject_ClearWeakRefs()</code> and the <code class="xref c c-func docutils literal">PyWeakref_*()</code> functions. The

799

instance structure needs to include a field of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal">PyObject*</code></a> which is

800

initialized to NULL.

801

Do not confuse this field with <a class="reference internal" href="#c.PyTypeObject.tp_weaklist" title="PyTypeObject.tp_weaklist"><code class="xref c c-member docutils literal">tp_weaklist</code></a>; that is the list head for

802

weak references to the type object itself.

803

This field is inherited by subtypes, but see the rules listed below. A subtype

804

may override this offset; this means that the subtype uses a different weak

805

reference list head than the base type. Since the list head is always found via

806

<a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal">tp_weaklistoffset</code></a>, this should not be a problem.

807

When a type defined by a class statement has no <a class="reference internal" href="../reference/datamodel.html#object.__slots__" title="object.__slots__"><code class="xref py py-attr docutils literal">__slots__</code></a> declaration,

808

and none of its base types are weakly referenceable, the type is made weakly

809

referenceable by adding a weak reference list head slot to the instance layout

810

and setting the <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal">tp_weaklistoffset</code></a> of that slot’s offset.

811

When a type’s <code class="xref py py-attr docutils literal">__slots__</code> declaration contains a slot named

812

<code class="xref py py-attr docutils literal">__weakref__</code>, that slot becomes the weak reference list head for

813

instances of the type, and the slot’s offset is stored in the type’s

814

815

When a type’s <code class="xref py py-attr docutils literal">__slots__</code> declaration does not contain a slot named

816

<code class="xref py py-attr docutils literal">__weakref__</code>, the type inherits its <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal">tp_weaklistoffset</code></a> from its

817

base type.

818

</dd></dl>

819

820

821

822

getiterfunc <code class="descname">PyTypeObject.tp_iter</code><a class="headerlink" href="#c.PyTypeObject.tp_iter" title="Permalink to this definition">¶</a></dt>

823

<dd>An optional pointer to a function that returns an iterator for the object. Its

824

presence normally signals that the instances of this type are iterable (although

825

sequences may be iterable without this function).

826

This function has the same signature as <a class="reference internal" href="object.html#c.PyObject_GetIter" title="PyObject_GetIter"><code class="xref c c-func docutils literal">PyObject_GetIter()</code></a>.

827

This field is inherited by subtypes.

828

</dd></dl>

829

830

831

832

iternextfunc <code class="descname">PyTypeObject.tp_iternext</code><a class="headerlink" href="#c.PyTypeObject.tp_iternext" title="Permalink to this definition">¶</a></dt>

833

<dd>An optional pointer to a function that returns the next item in an iterator.

834

When the iterator is exhausted, it must return NULL; a <a class="reference internal" href="../library/exceptions.html#StopIteration" title="StopIteration"><code class="xref py py-exc docutils literal">StopIteration</code></a>

835

exception may or may not be set. When another error occurs, it must return

836

NULL too. Its presence signals that the instances of this type are

837

iterators.

838

Iterator types should also define the <a class="reference internal" href="#c.PyTypeObject.tp_iter" title="PyTypeObject.tp_iter"><code class="xref c c-member docutils literal">tp_iter</code></a> function, and that

839

function should return the iterator instance itself (not a new iterator

840

instance).

841

This function has the same signature as <a class="reference internal" href="iter.html#c.PyIter_Next" title="PyIter_Next"><code class="xref c c-func docutils literal">PyIter_Next()</code></a>.

842

This field is inherited by subtypes.

843

</dd></dl>

844

845

846

847

struct <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a>* <code class="descname">PyTypeObject.tp_methods</code><a class="headerlink" href="#c.PyTypeObject.tp_methods" title="Permalink to this definition">¶</a></dt>

848

<dd>An optional pointer to a static NULL-terminated array of <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal">PyMethodDef</code></a>

849

structures, declaring regular methods of this type.

850

For each entry in the array, an entry is added to the type’s dictionary (see

851

<a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal">tp_dict</code></a> below) containing a method descriptor.

852

This field is not inherited by subtypes (methods are inherited through a

853

different mechanism).

854

</dd></dl>

855

856

857

858

struct <a class="reference internal" href="structures.html#c.PyMemberDef" title="PyMemberDef">PyMemberDef</a>* <code class="descname">PyTypeObject.tp_members</code><a class="headerlink" href="#c.PyTypeObject.tp_members" title="Permalink to this definition">¶</a></dt>

859

<dd>An optional pointer to a static NULL-terminated array of <a class="reference internal" href="structures.html#c.PyMemberDef" title="PyMemberDef"><code class="xref c c-type docutils literal">PyMemberDef</code></a>

860

structures, declaring regular data members (fields or slots) of instances of

861

this type.

862

For each entry in the array, an entry is added to the type’s dictionary (see

863

864

This field is not inherited by subtypes (members are inherited through a

865

different mechanism).

866

</dd></dl>

867

868

869

870

struct PyGetSetDef* <code class="descname">PyTypeObject.tp_getset</code><a class="headerlink" href="#c.PyTypeObject.tp_getset" title="Permalink to this definition">¶</a></dt>

871

<dd>An optional pointer to a static NULL-terminated array of <code class="xref c c-type docutils literal">PyGetSetDef</code>

872

structures, declaring computed attributes of instances of this type.

873

For each entry in the array, an entry is added to the type’s dictionary (see

874

875

This field is not inherited by subtypes (computed attributes are inherited

876

through a different mechanism).

877

Docs for PyGetSetDef:

878

<div class="highlight-c"><div class="highlight"><pre>typedef PyObject *(*getter)(PyObject *, void *);

879

typedef int (*setter)(PyObject *, PyObject *, void *);

880

881

typedef struct PyGetSetDef {

882

char *name; /* attribute name */

883

getter get; /* C function to get the attribute */

884

setter set; /* C function to set or delete the attribute */

885

char *doc; /* optional doc string */

886

void *closure; /* optional additional data for getter and setter */

887

} PyGetSetDef;

888

</pre></div>

889

</div>

890

</dd></dl>

891

892

893

894

<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyTypeObject.tp_base</code><a class="headerlink" href="#c.PyTypeObject.tp_base" title="Permalink to this definition">¶</a></dt>

895

<dd>An optional pointer to a base type from which type properties are inherited. At

896

this level, only single inheritance is supported; multiple inheritance require

897

dynamically creating a type object by calling the metatype.

898

This field is not inherited by subtypes (obviously), but it defaults to

899

<code class="docutils literal">&PyBaseObject_Type</code> (which to Python programmers is known as the type

900

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

901

</dd></dl>

902

903

904

905

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_dict</code><a class="headerlink" href="#c.PyTypeObject.tp_dict" title="Permalink to this definition">¶</a></dt>

906

<dd>The type’s dictionary is stored here by <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal">PyType_Ready()</code></a>.

907

This field should normally be initialized to NULL before PyType_Ready is

908

called; it may also be initialized to a dictionary containing initial attributes

909

for the type. Once <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal">PyType_Ready()</code></a> has initialized the type, extra

910

attributes for the type may be added to this dictionary only if they don’t

911

correspond to overloaded operations (like <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal">__add__()</code></a>).

912

This field is not inherited by subtypes (though the attributes defined in here

913

are inherited through a different mechanism).

914

915

Warning

916

It is not safe to use <a class="reference internal" href="dict.html#c.PyDict_SetItem" title="PyDict_SetItem"><code class="xref c c-func docutils literal">PyDict_SetItem()</code></a> on or otherwise modify

917

918

</div>

919

</dd></dl>

920

921

922

923

descrgetfunc <code class="descname">PyTypeObject.tp_descr_get</code><a class="headerlink" href="#c.PyTypeObject.tp_descr_get" title="Permalink to this definition">¶</a></dt>

924

<dd>An optional pointer to a “descriptor get” function.

925

The function signature is

926

<div class="highlight-c"><div class="highlight"><pre>PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

927

</pre></div>

928

</div>

929

This field is inherited by subtypes.

930

</dd></dl>

931

932

933

934

descrsetfunc <code class="descname">PyTypeObject.tp_descr_set</code><a class="headerlink" href="#c.PyTypeObject.tp_descr_set" title="Permalink to this definition">¶</a></dt>

935

<dd>An optional pointer to a function for setting and deleting

936

a descriptor’s value.

937

The function signature is

938

<div class="highlight-c"><div class="highlight"><pre>int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

939

</pre></div>

940

</div>

941

The value argument is set to NULL to delete the value.

942

This field is inherited by subtypes.

943

</dd></dl>

944

945

946

947

Py_ssize_t <code class="descname">PyTypeObject.tp_dictoffset</code><a class="headerlink" href="#c.PyTypeObject.tp_dictoffset" title="Permalink to this definition">¶</a></dt>

948

<dd>If the instances of this type have a dictionary containing instance variables,

949

this field is non-zero and contains the offset in the instances of the type of

950

the instance variable dictionary; this offset is used by

951

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

952

Do not confuse this field with <a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal">tp_dict</code></a>; that is the dictionary for

953

attributes of the type object itself.

954

If the value of this field is greater than zero, it specifies the offset from

955

the start of the instance structure. If the value is less than zero, it

956

specifies the offset from the end of the instance structure. A negative

957

offset is more expensive to use, and should only be used when the instance

958

structure contains a variable-length part. This is used for example to add an

959

instance variable dictionary to subtypes of <a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> or <a class="reference internal" href="../library/stdtypes.html#tuple" title="tuple"><code class="xref py py-class docutils literal">tuple</code></a>. Note

960

that the <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a> field should account for the dictionary added to

961

the end in that case, even though the dictionary is not included in the basic

962

object layout. On a system with a pointer size of 4 bytes,

963

<a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal">tp_dictoffset</code></a> should be set to <code class="docutils literal">-4</code> to indicate that the dictionary is

964

at the very end of the structure.

965

The real dictionary offset in an instance can be computed from a negative

966

967

<div class="highlight-c"><div class="highlight"><pre>dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset

968

if dictoffset is not aligned on sizeof(void*):

969

round up to sizeof(void*)

970

</pre></div>

971

</div>

972

where <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal">tp_dictoffset</code></a> are

973

taken from the type object, and <code class="xref py py-attr docutils literal">ob_size</code> is taken from the instance. The

974

absolute value is taken because ints use the sign of <code class="xref py py-attr docutils literal">ob_size</code> to

975

store the sign of the number. (There’s never a need to do this calculation

976

yourself; it is done for you by <code class="xref c c-func docutils literal">_PyObject_GetDictPtr()</code>.)

977

This field is inherited by subtypes, but see the rules listed below. A subtype

978

may override this offset; this means that the subtype instances store the

979

dictionary at a difference offset than the base type. Since the dictionary is

980

always found via <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal">tp_dictoffset</code></a>, this should not be a problem.

981

982

and none of its base types has an instance variable dictionary, a dictionary

983

slot is added to the instance layout and the <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal">tp_dictoffset</code></a> is set to

984

that slot’s offset.

985

When a type defined by a class statement has a <code class="xref py py-attr docutils literal">__slots__</code> declaration,

986

the type inherits its <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal">tp_dictoffset</code></a> from its base type.

987

(Adding a slot named <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal">__dict__</code></a> to the <code class="xref py py-attr docutils literal">__slots__</code> declaration does

988

not have the expected effect, it just causes confusion. Maybe this should be

989

added as a feature just like <code class="xref py py-attr docutils literal">__weakref__</code> though.)

990

</dd></dl>

991

992

993

994

initproc <code class="descname">PyTypeObject.tp_init</code><a class="headerlink" href="#c.PyTypeObject.tp_init" title="Permalink to this definition">¶</a></dt>

995

<dd>An optional pointer to an instance initialization function.

996

This function corresponds to the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a> method of classes. Like

997

<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a>, it is possible to create an instance without calling

998

<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal">__init__()</code></a>, and it is possible to reinitialize an instance by calling its

999

1000

The function signature is

1001

<div class="highlight-c"><div class="highlight"><pre>int tp_init(PyObject *self, PyObject *args, PyObject *kwds)

1002

</pre></div>

1003

</div>

1004

The self argument is the instance to be initialized; the args and kwds

1005

arguments represent positional and keyword arguments of the call to

1006

1007

The <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal">tp_init</code></a> function, if not NULL, is called when an instance is

1008

created normally by calling its type, after the type’s <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a> function

1009

has returned an instance of the type. If the <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a> function returns an

1010

instance of some other type that is not a subtype of the original type, no

1011

<a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal">tp_init</code></a> function is called; if <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a> returns an instance of a

1012

subtype of the original type, the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal">tp_init</code></a> is called.

1013

This field is inherited by subtypes.

1014

</dd></dl>

1015

1016

1017

1018

allocfunc <code class="descname">PyTypeObject.tp_alloc</code><a class="headerlink" href="#c.PyTypeObject.tp_alloc" title="Permalink to this definition">¶</a></dt>

1019

<dd>An optional pointer to an instance allocation function.

1020

The function signature is

1021

<div class="highlight-c"><div class="highlight"><pre>PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)

1022

</pre></div>

1023

</div>

1024

The purpose of this function is to separate memory allocation from memory

1025

initialization. It should return a pointer to a block of memory of adequate

1026

length for the instance, suitably aligned, and initialized to zeros, but with

1027

<code class="xref py py-attr docutils literal">ob_refcnt</code> set to <code class="docutils literal">1</code> and <code class="xref py py-attr docutils literal">ob_type</code> set to the type argument. If

1028

the type’s <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal">tp_itemsize</code></a> is non-zero, the object’s <code class="xref py py-attr docutils literal">ob_size</code> field

1029

should be initialized to nitems and the length of the allocated memory block

1030

should be <code class="docutils literal">tp_basicsize + nitems*tp_itemsize</code>, rounded up to a multiple of

1031

<code class="docutils literal">sizeof(void*)</code>; otherwise, nitems is not used and the length of the block

1032

should be <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal">tp_basicsize</code></a>.

1033

Do not use this function to do any other instance initialization, not even to

1034

allocate additional memory; that should be done by <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a>.

1035

This field is inherited by static subtypes, but not by dynamic subtypes

1036

(subtypes created by a class statement); in the latter, this field is always set

1037

to <a class="reference internal" href="type.html#c.PyType_GenericAlloc" title="PyType_GenericAlloc"><code class="xref c c-func docutils literal">PyType_GenericAlloc()</code></a>, to force a standard heap allocation strategy.

1038

That is also the recommended value for statically defined types.

1039

</dd></dl>

1040

1041

1042

1043

newfunc <code class="descname">PyTypeObject.tp_new</code><a class="headerlink" href="#c.PyTypeObject.tp_new" title="Permalink to this definition">¶</a></dt>

1044

<dd>An optional pointer to an instance creation function.

1045

If this function is NULL for a particular type, that type cannot be called to

1046

create new instances; presumably there is some other way to create instances,

1047

like a factory function.

1048

The function signature is

1049

<div class="highlight-c"><div class="highlight"><pre>PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)

1050

</pre></div>

1051

</div>

1052

The subtype argument is the type of the object being created; the args and

1053

kwds arguments represent positional and keyword arguments of the call to the

1054

type. Note that subtype doesn’t have to equal the type whose <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a>

1055

function is called; it may be a subtype of that type (but not an unrelated

1056

type).

1057

The <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a> function should call <code class="docutils literal">subtype->tp_alloc(subtype, nitems)</code>

1058

to allocate space for the object, and then do only as much further

1059

initialization as is absolutely necessary. Initialization that can safely be

1060

ignored or repeated should be placed in the <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal">tp_init</code></a> handler. A good

1061

rule of thumb is that for immutable types, all initialization should take place

1062

in <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal">tp_new</code></a>, while for mutable types, most initialization should be

1063

deferred to <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal">tp_init</code></a>.

1064

This field is inherited by subtypes, except it is not inherited by static types

1065

whose <a class="reference internal" href="#c.PyTypeObject.tp_base" title="PyTypeObject.tp_base"><code class="xref c c-member docutils literal">tp_base</code></a> is NULL or <code class="docutils literal">&PyBaseObject_Type</code>.

1066

</dd></dl>

1067

1068

1069

1070

destructor <code class="descname">PyTypeObject.tp_free</code><a class="headerlink" href="#c.PyTypeObject.tp_free" title="Permalink to this definition">¶</a></dt>

1071

<dd>An optional pointer to an instance deallocation function. Its signature is

1072

<code class="xref c c-type docutils literal">freefunc</code>:

1073

<div class="highlight-c"><div class="highlight"><pre>void tp_free(void *)

1074

</pre></div>

1075

</div>

1076

An initializer that is compatible with this signature is <code class="xref c c-func docutils literal">PyObject_Free()</code>.

1077

This field is inherited by static subtypes, but not by dynamic subtypes

1078

(subtypes created by a class statement); in the latter, this field is set to a

1079

deallocator suitable to match <a class="reference internal" href="type.html#c.PyType_GenericAlloc" title="PyType_GenericAlloc"><code class="xref c c-func docutils literal">PyType_GenericAlloc()</code></a> and the value of the

1080

1081

</dd></dl>

1082

1083

1084

1085

<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry">inquiry</a> <code class="descname">PyTypeObject.tp_is_gc</code><a class="headerlink" href="#c.PyTypeObject.tp_is_gc" title="Permalink to this definition">¶</a></dt>

1086

<dd>An optional pointer to a function called by the garbage collector.

1087

The garbage collector needs to know whether a particular object is collectible

1088

or not. Normally, it is sufficient to look at the object’s type’s

1089

<a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal">tp_flags</code></a> field, and check the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_GC</code></a> flag bit. But

1090

some types have a mixture of statically and dynamically allocated instances, and

1091

the statically allocated instances are not collectible. Such types should

1092

define this function; it should return <code class="docutils literal">1</code> for a collectible instance, and

1093

<code class="docutils literal">0</code> for a non-collectible instance. The signature is

1094

<div class="highlight-c"><div class="highlight"><pre>int tp_is_gc(PyObject *self)

1095

</pre></div>

1096

</div>

1097

(The only example of this are types themselves. The metatype,

1098

<a class="reference internal" href="type.html#c.PyType_Type" title="PyType_Type"><code class="xref c c-data docutils literal">PyType_Type</code></a>, defines this function to distinguish between statically

1099

and dynamically allocated types.)

1100

This field is inherited by subtypes.

1101

</dd></dl>

1102

1103

1104

1105

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_bases</code><a class="headerlink" href="#c.PyTypeObject.tp_bases" title="Permalink to this definition">¶</a></dt>

1106

<dd>Tuple of base types.

1107

This is set for types created by a class statement. It should be NULL for

1108

statically defined types.

1109

This field is not inherited.

1110

</dd></dl>

1111

1112

1113

1114

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_mro</code><a class="headerlink" href="#c.PyTypeObject.tp_mro" title="Permalink to this definition">¶</a></dt>

1115

<dd>Tuple containing the expanded set of base types, starting with the type itself

1116

and ending with <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal">object</code></a>, in Method Resolution Order.

1117

This field is not inherited; it is calculated fresh by <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal">PyType_Ready()</code></a>.

1118

</dd></dl>

1119

1120

1121

1122

destructor <code class="descname">PyTypeObject.tp_finalize</code><a class="headerlink" href="#c.PyTypeObject.tp_finalize" title="Permalink to this definition">¶</a></dt>

1123

<dd>An optional pointer to an instance finalization function. Its signature is

1124

<code class="xref c c-type docutils literal">destructor</code>:

1125

<div class="highlight-c"><div class="highlight"><pre>void tp_finalize(PyObject *)

1126

</pre></div>

1127

</div>

1128

If <a class="reference internal" href="#c.PyTypeObject.tp_finalize" title="PyTypeObject.tp_finalize"><code class="xref c c-member docutils literal">tp_finalize</code></a> is set, the interpreter calls it once when

1129

finalizing an instance. It is called either from the garbage

1130

collector (if the instance is part of an isolated reference cycle) or

1131

just before the object is deallocated. Either way, it is guaranteed

1132

to be called before attempting to break reference cycles, ensuring

1133

that it finds the object in a sane state.

1134

<a class="reference internal" href="#c.PyTypeObject.tp_finalize" title="PyTypeObject.tp_finalize"><code class="xref c c-member docutils literal">tp_finalize</code></a> should not mutate the current exception status;

1135

therefore, a recommended way to write a non-trivial finalizer is:

1136

<div class="highlight-c"><div class="highlight"><pre>static void

1137

local_finalize(PyObject *self)

1138

{

1139

PyObject *error_type, *error_value, *error_traceback;

1140

1141

/* Save the current exception, if any. */

1142

PyErr_Fetch(&error_type, &error_value, &error_traceback);

1143

1144

/* ... */

1145

1146

/* Restore the saved exception. */

1147

PyErr_Restore(error_type, error_value, error_traceback);

1148

}

1149

</pre></div>

1150

</div>

1151

For this field to be taken into account (even through inheritance),

1152

you must also set the <a class="reference internal" href="#Py_TPFLAGS_HAVE_FINALIZE" title="Py_TPFLAGS_HAVE_FINALIZE"><code class="xref py py-const docutils literal">Py_TPFLAGS_HAVE_FINALIZE</code></a> flags bit.

1153

This field is inherited by subtypes.

1154

1155

New in version 3.4.

1156

</div>

1157

1158

See also

1159

“Safe object finalization” (<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0442">PEP 442</a>)

1160

</div>

1161

</dd></dl>

1162

1163

1164

1165

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_cache</code><a class="headerlink" href="#c.PyTypeObject.tp_cache" title="Permalink to this definition">¶</a></dt>

1166

<dd>Unused. Not inherited. Internal use only.

1167

</dd></dl>

1168

1169

1170

1171

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_subclasses</code><a class="headerlink" href="#c.PyTypeObject.tp_subclasses" title="Permalink to this definition">¶</a></dt>

1172

<dd>List of weak references to subclasses. Not inherited. Internal use only.

1173

</dd></dl>

1174

1175

1176

1177

<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_weaklist</code><a class="headerlink" href="#c.PyTypeObject.tp_weaklist" title="Permalink to this definition">¶</a></dt>

1178

<dd>Weak reference list head, for weak references to this type object. Not

1179

inherited. Internal use only.

1180

</dd></dl>

1181

1182

The remaining fields are only defined if the feature test macro

1183

<code class="xref py py-const docutils literal">COUNT_ALLOCS</code> is defined, and are for internal use only. They are

1184

documented here for completeness. None of these fields are inherited by

1185

subtypes.

1186

1187

1188

Py_ssize_t <code class="descname">PyTypeObject.tp_allocs</code><a class="headerlink" href="#c.PyTypeObject.tp_allocs" title="Permalink to this definition">¶</a></dt>

1189

<dd>Number of allocations.

1190

</dd></dl>

1191

1192

1193

1194

Py_ssize_t <code class="descname">PyTypeObject.tp_frees</code><a class="headerlink" href="#c.PyTypeObject.tp_frees" title="Permalink to this definition">¶</a></dt>

1195

<dd>Number of frees.

1196

</dd></dl>

1197

1198

1199

1200

Py_ssize_t <code class="descname">PyTypeObject.tp_maxalloc</code><a class="headerlink" href="#c.PyTypeObject.tp_maxalloc" title="Permalink to this definition">¶</a></dt>

1201

<dd>Maximum simultaneously allocated objects.

1202

</dd></dl>

1203

1204

1205

1206

<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyTypeObject.tp_next</code><a class="headerlink" href="#c.PyTypeObject.tp_next" title="Permalink to this definition">¶</a></dt>

1207

<dd>Pointer to the next type object with a non-zero <a class="reference internal" href="#c.PyTypeObject.tp_allocs" title="PyTypeObject.tp_allocs"><code class="xref c c-member docutils literal">tp_allocs</code></a> field.

1208

</dd></dl>

1209

1210

Also, note that, in a garbage collected Python, tp_dealloc may be called from

1211

any Python thread, not just the thread which created the object (if the object

1212

becomes part of a refcount cycle, that cycle might be collected by a garbage

1213

collection on any thread). This is not a problem for Python API calls, since

1214

the thread on which tp_dealloc is called will own the Global Interpreter Lock

1215

(GIL). However, if the object being destroyed in turn destroys objects from some

1216

other C or C++ library, care should be taken to ensure that destroying those

1217

objects on the thread which called tp_dealloc will not violate any assumptions

1218

of the library.

1219

</div>

1220

1221

<h1>Number Object Structures<a class="headerlink" href="#number-object-structures" title="Permalink to this headline">¶</a></h1>

1222

1223

1224

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

1225

<dd>This structure holds pointers to the functions which an object uses to

1226

implement the number protocol. Each function is used by the function of

1227

similar name documented in the <a class="reference internal" href="number.html#number">Number Protocol</a> section.

1228

Here is the structure definition:

1229

<div class="highlight-c"><div class="highlight"><pre>typedef struct {

1230

binaryfunc nb_add;

1231

binaryfunc nb_subtract;

1232

binaryfunc nb_multiply;

1233

binaryfunc nb_remainder;

1234

binaryfunc nb_divmod;

1235

ternaryfunc nb_power;

1236

unaryfunc nb_negative;

1237

unaryfunc nb_positive;

1238

unaryfunc nb_absolute;

1239

inquiry nb_bool;

1240

unaryfunc nb_invert;

1241

binaryfunc nb_lshift;

1242

binaryfunc nb_rshift;

1243

binaryfunc nb_and;

1244

binaryfunc nb_xor;

1245

binaryfunc nb_or;

1246

unaryfunc nb_int;

1247

void *nb_reserved;

1248

unaryfunc nb_float;

1249

1250

binaryfunc nb_inplace_add;

1251

binaryfunc nb_inplace_subtract;

1252

binaryfunc nb_inplace_multiply;

1253

binaryfunc nb_inplace_remainder;

1254

ternaryfunc nb_inplace_power;

1255

binaryfunc nb_inplace_lshift;

1256

binaryfunc nb_inplace_rshift;

1257

binaryfunc nb_inplace_and;

1258

binaryfunc nb_inplace_xor;

1259

binaryfunc nb_inplace_or;

1260

1261

binaryfunc nb_floor_divide;

1262

binaryfunc nb_true_divide;

1263

binaryfunc nb_inplace_floor_divide;

1264

binaryfunc nb_inplace_true_divide;

1265

1266

unaryfunc nb_index;

1267

1268

binaryfunc nb_matrix_multiply;

1269

binaryfunc nb_inplace_matrix_multiply;

1270

} PyNumberMethods;

1271

</pre></div>

1272

</div>

1273

1274

Note

1275

Binary and ternary functions must check the type of all their operands,

1276

and implement the necessary conversions (at least one of the operands is

1277

an instance of the defined type). If the operation is not defined for the

1278

given operands, binary and ternary functions must return

1279

<code class="docutils literal">Py_NotImplemented</code>, if another error occurred they must return <code class="docutils literal">NULL</code>

1280

and set an exception.

1281

</div>

1282

1283

Note

1284

The <code class="xref c c-data docutils literal">nb_reserved</code> field should always be <code class="docutils literal">NULL</code>. It

1285

was previously called <code class="xref c c-data docutils literal">nb_long</code>, and was renamed in

1286

Python 3.0.1.

1287

</div>

1288

</dd></dl>

1289

1290

</div>

1291

1292

<h1>Mapping Object Structures<a class="headerlink" href="#mapping-object-structures" title="Permalink to this headline">¶</a></h1>

1293

1294

1295

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

1296

<dd>This structure holds pointers to the functions which an object uses to

1297

implement the mapping protocol. It has three members:

1298

</dd></dl>

1299

1300

1301

1302

lenfunc <code class="descname">PyMappingMethods.mp_length</code><a class="headerlink" href="#c.PyMappingMethods.mp_length" title="Permalink to this definition">¶</a></dt>

1303

<dd>This function is used by <a class="reference internal" href="mapping.html#c.PyMapping_Length" title="PyMapping_Length"><code class="xref c c-func docutils literal">PyMapping_Length()</code></a> and

1304

<a class="reference internal" href="object.html#c.PyObject_Size" title="PyObject_Size"><code class="xref c c-func docutils literal">PyObject_Size()</code></a>, and has the same signature. This slot may be set to

1305

NULL if the object has no defined length.

1306

</dd></dl>

1307

1308

1309

1310

binaryfunc <code class="descname">PyMappingMethods.mp_subscript</code><a class="headerlink" href="#c.PyMappingMethods.mp_subscript" title="Permalink to this definition">¶</a></dt>

1311

<dd>This function is used by <a class="reference internal" href="object.html#c.PyObject_GetItem" title="PyObject_GetItem"><code class="xref c c-func docutils literal">PyObject_GetItem()</code></a> and has the same

1312

signature. This slot must be filled for the <a class="reference internal" href="mapping.html#c.PyMapping_Check" title="PyMapping_Check"><code class="xref c c-func docutils literal">PyMapping_Check()</code></a>

1313

function to return <code class="docutils literal">1</code>, it can be NULL otherwise.

1314

</dd></dl>

1315

1316

1317

1318

objobjargproc <code class="descname">PyMappingMethods.mp_ass_subscript</code><a class="headerlink" href="#c.PyMappingMethods.mp_ass_subscript" title="Permalink to this definition">¶</a></dt>

1319

<dd>This function is used by <a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal">PyObject_SetItem()</code></a> and

1320

<a class="reference internal" href="object.html#c.PyObject_DelItem" title="PyObject_DelItem"><code class="xref c c-func docutils literal">PyObject_DelItem()</code></a>. It has the same signature as

1321

<a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal">PyObject_SetItem()</code></a>, but v can also be set to NULL to delete

1322

an item. If this slot is NULL, the object does not support item

1323

assignment and deletion.

1324

</dd></dl>

1325

1326

</div>

1327

1328

<h1>Sequence Object Structures<a class="headerlink" href="#sequence-object-structures" title="Permalink to this headline">¶</a></h1>

1329

1330

1331

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

1332

<dd>This structure holds pointers to the functions which an object uses to

1333

implement the sequence protocol.

1334

</dd></dl>

1335

1336

1337

1338

lenfunc <code class="descname">PySequenceMethods.sq_length</code><a class="headerlink" href="#c.PySequenceMethods.sq_length" title="Permalink to this definition">¶</a></dt>

1339

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Size" title="PySequence_Size"><code class="xref c c-func docutils literal">PySequence_Size()</code></a> and <a class="reference internal" href="object.html#c.PyObject_Size" title="PyObject_Size"><code class="xref c c-func docutils literal">PyObject_Size()</code></a>,

1340

and has the same signature.

1341

</dd></dl>

1342

1343

1344

1345

binaryfunc <code class="descname">PySequenceMethods.sq_concat</code><a class="headerlink" href="#c.PySequenceMethods.sq_concat" title="Permalink to this definition">¶</a></dt>

1346

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Concat" title="PySequence_Concat"><code class="xref c c-func docutils literal">PySequence_Concat()</code></a> and has the same

1347

signature. It is also used by the <code class="docutils literal">+</code> operator, after trying the numeric

1348

addition via the <code class="xref c c-member docutils literal">nb_add</code> slot.

1349

</dd></dl>

1350

1351

1352

1353

ssizeargfunc <code class="descname">PySequenceMethods.sq_repeat</code><a class="headerlink" href="#c.PySequenceMethods.sq_repeat" title="Permalink to this definition">¶</a></dt>

1354

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Repeat" title="PySequence_Repeat"><code class="xref c c-func docutils literal">PySequence_Repeat()</code></a> and has the same

1355

signature. It is also used by the <code class="docutils literal">*</code> operator, after trying numeric

1356

multiplication via the <code class="xref c c-member docutils literal">nb_multiply</code>

1357

slot.

1358

</dd></dl>

1359

1360

1361

1362

ssizeargfunc <code class="descname">PySequenceMethods.sq_item</code><a class="headerlink" href="#c.PySequenceMethods.sq_item" title="Permalink to this definition">¶</a></dt>

1363

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal">PySequence_GetItem()</code></a> and has the same

1364

signature. This slot must be filled for the <a class="reference internal" href="sequence.html#c.PySequence_Check" title="PySequence_Check"><code class="xref c c-func docutils literal">PySequence_Check()</code></a>

1365

function to return <code class="docutils literal">1</code>, it can be NULL otherwise.

1366

Negative indexes are handled as follows: if the <code class="xref py py-attr docutils literal">sq_length</code> slot is

1367

filled, it is called and the sequence length is used to compute a positive

1368

index which is passed to <code class="xref py py-attr docutils literal">sq_item</code>. If <code class="xref py py-attr docutils literal">sq_length</code> is NULL,

1369

the index is passed as is to the function.

1370

</dd></dl>

1371

1372

1373

1374

ssizeobjargproc <code class="descname">PySequenceMethods.sq_ass_item</code><a class="headerlink" href="#c.PySequenceMethods.sq_ass_item" title="Permalink to this definition">¶</a></dt>

1375

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_SetItem" title="PySequence_SetItem"><code class="xref c c-func docutils literal">PySequence_SetItem()</code></a> and has the same

1376

signature. This slot may be left to NULL if the object does not support

1377

item assignment and deletion.

1378

</dd></dl>

1379

1380

1381

1382

objobjproc <code class="descname">PySequenceMethods.sq_contains</code><a class="headerlink" href="#c.PySequenceMethods.sq_contains" title="Permalink to this definition">¶</a></dt>

1383

<dd>This function may be used by <a class="reference internal" href="sequence.html#c.PySequence_Contains" title="PySequence_Contains"><code class="xref c c-func docutils literal">PySequence_Contains()</code></a> and has the same

1384

signature. This slot may be left to NULL, in this case

1385

<a class="reference internal" href="sequence.html#c.PySequence_Contains" title="PySequence_Contains"><code class="xref c c-func docutils literal">PySequence_Contains()</code></a> simply traverses the sequence until it finds a

1386

match.

1387

</dd></dl>

1388

1389

1390

1391

binaryfunc <code class="descname">PySequenceMethods.sq_inplace_concat</code><a class="headerlink" href="#c.PySequenceMethods.sq_inplace_concat" title="Permalink to this definition">¶</a></dt>

1392

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_InPlaceConcat" title="PySequence_InPlaceConcat"><code class="xref c c-func docutils literal">PySequence_InPlaceConcat()</code></a> and has the same

1393

signature. It should modify its first operand, and return it.

1394

</dd></dl>

1395

1396

1397

1398

ssizeargfunc <code class="descname">PySequenceMethods.sq_inplace_repeat</code><a class="headerlink" href="#c.PySequenceMethods.sq_inplace_repeat" title="Permalink to this definition">¶</a></dt>

1399

<dd>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_InPlaceRepeat" title="PySequence_InPlaceRepeat"><code class="xref c c-func docutils literal">PySequence_InPlaceRepeat()</code></a> and has the same

1400

signature. It should modify its first operand, and return it.

1401

</dd></dl>

1402

1403

</div>

1404

1405

<h1>Buffer Object Structures<a class="headerlink" href="#buffer-object-structures" title="Permalink to this headline">¶</a></h1>

1406

1407

1408

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

1409

<dd>This structure holds pointers to the functions required by the

1410

<a class="reference internal" href="buffer.html#bufferobjects">Buffer protocol</a>. The protocol defines how

1411

an exporter object can expose its internal data to consumer objects.

1412

</dd></dl>

1413

1414

1415

1416

getbufferproc <code class="descname">PyBufferProcs.bf_getbuffer</code><a class="headerlink" href="#c.PyBufferProcs.bf_getbuffer" title="Permalink to this definition">¶</a></dt>

1417

<dd>The signature of this function is:

1418

<div class="highlight-c"><div class="highlight"><pre>int (PyObject *exporter, Py_buffer *view, int flags);

1419

</pre></div>

1420

</div>

1421

Handle a request to exporter to fill in view as specified by flags.

1422

Except for point (3), an implementation of this function MUST take these

1423

steps:

1424

1425

<li>Check if the request can be met. If not, raise <code class="xref c c-data docutils literal">PyExc_BufferError</code>,

1426

set <code class="xref c c-data docutils literal">view->obj</code> to NULL and return -1.</li>

1427

<li>Fill in the requested fields.</li>

1428

<li>Increment an internal counter for the number of exports.</li>

1429

<li>Set <code class="xref c c-data docutils literal">view->obj</code> to exporter and increment <code class="xref c c-data docutils literal">view->obj</code>.</li>

1430

<li>Return 0.</li>

1431

</ol>

1432

If exporter is part of a chain or tree of buffer providers, two main

1433

schemes can be used:

1434

1435

<li>Re-export: Each member of the tree acts as the exporting object and

1436

sets <code class="xref c c-data docutils literal">view->obj</code> to a new reference to itself.</li>

1437

<li>Redirect: The buffer request is redirected to the root object of the

1438

tree. Here, <code class="xref c c-data docutils literal">view->obj</code> will be a new reference to the root

1439

object.</li>

1440

</ul>

1441

The individual fields of view are described in section

1442

<a class="reference internal" href="buffer.html#buffer-structure">Buffer structure</a>, the rules how an exporter

1443

must react to specific requests are in section

1444

<a class="reference internal" href="buffer.html#buffer-request-types">Buffer request types</a>.

1445

All memory pointed to in the <a class="reference internal" href="buffer.html#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal">Py_buffer</code></a> structure belongs to

1446

the exporter and must remain valid until there are no consumers left.

1447

<a class="reference internal" href="buffer.html#c.Py_buffer.format" title="Py_buffer.format"><code class="xref c c-member docutils literal">format</code></a>, <a class="reference internal" href="buffer.html#c.Py_buffer.shape" title="Py_buffer.shape"><code class="xref c c-member docutils literal">shape</code></a>,

1448

<a class="reference internal" href="buffer.html#c.Py_buffer.strides" title="Py_buffer.strides"><code class="xref c c-member docutils literal">strides</code></a>, <a class="reference internal" href="buffer.html#c.Py_buffer.suboffsets" title="Py_buffer.suboffsets"><code class="xref c c-member docutils literal">suboffsets</code></a>

1449

and <a class="reference internal" href="buffer.html#c.Py_buffer.internal" title="Py_buffer.internal"><code class="xref c c-member docutils literal">internal</code></a>

1450

are read-only for the consumer.

1451

<a class="reference internal" href="buffer.html#c.PyBuffer_FillInfo" title="PyBuffer_FillInfo"><code class="xref c c-func docutils literal">PyBuffer_FillInfo()</code></a> provides an easy way of exposing a simple

1452

bytes buffer while dealing correctly with all request types.

1453

<a class="reference internal" href="buffer.html#c.PyObject_GetBuffer" title="PyObject_GetBuffer"><code class="xref c c-func docutils literal">PyObject_GetBuffer()</code></a> is the interface for the consumer that

1454

wraps this function.

1455

</dd></dl>

1456

1457

1458

1459

releasebufferproc <code class="descname">PyBufferProcs.bf_releasebuffer</code><a class="headerlink" href="#c.PyBufferProcs.bf_releasebuffer" title="Permalink to this definition">¶</a></dt>

1460

<dd>The signature of this function is:

1461

<div class="highlight-c"><div class="highlight"><pre>void (PyObject *exporter, Py_buffer *view);

1462

</pre></div>

1463

</div>

1464

Handle a request to release the resources of the buffer. If no resources

1465

need to be released, <a class="reference internal" href="#c.PyBufferProcs.bf_releasebuffer" title="PyBufferProcs.bf_releasebuffer"><code class="xref c c-member docutils literal">PyBufferProcs.bf_releasebuffer</code></a> may be

1466

NULL. Otherwise, a standard implementation of this function will take

1467

these optional steps:

1468

1469

<li>Decrement an internal counter for the number of exports.</li>

1470

<li>If the counter is 0, free all memory associated with view.</li>

1471

</ol>

1472

The exporter MUST use the <a class="reference internal" href="buffer.html#c.Py_buffer.internal" title="Py_buffer.internal"><code class="xref c c-member docutils literal">internal</code></a> field to keep

1473

track of buffer-specific resources. This field is guaranteed to remain

1474

constant, while a consumer MAY pass a copy of the original buffer as the

1475

view argument.

1476

This function MUST NOT decrement <code class="xref c c-data docutils literal">view->obj</code>, since that is

1477

done automatically in <a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal">PyBuffer_Release()</code></a> (this scheme is

1478

useful for breaking reference cycles).

1479

<a class="reference internal" href="buffer.html#c.PyBuffer_Release" title="PyBuffer_Release"><code class="xref c c-func docutils literal">PyBuffer_Release()</code></a> is the interface for the consumer that

1480

wraps this function.

1481

</dd></dl>

1482

1483

</div>

1484

1485

<h1>Async Object Structures<a class="headerlink" href="#async-object-structures" title="Permalink to this headline">¶</a></h1>

1486

1487

New in version 3.5.

1488

</div>

1489

1490

1491

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

1492

<dd>This structure holds pointers to the functions required to implement

1493

<a class="reference internal" href="../glossary.html#term-awaitable">awaitable</a> and <a class="reference internal" href="../glossary.html#term-asynchronous-iterator">asynchronous iterator</a> objects.

1494

Here is the structure definition:

1495

<div class="highlight-c"><div class="highlight"><pre>typedef struct {

1496

unaryfunc am_await;

1497

unaryfunc am_aiter;

1498

unaryfunc am_anext;

1499

} PyAsyncMethods;

1500

</pre></div>

1501

</div>

1502

</dd></dl>

1503

1504

1505

1506

unaryfunc <code class="descname">PyAsyncMethods.am_await</code><a class="headerlink" href="#c.PyAsyncMethods.am_await" title="Permalink to this definition">¶</a></dt>

1507

<dd>The signature of this function is:

1508

<div class="highlight-c"><div class="highlight"><pre>PyObject *am_await(PyObject *self)

1509

</pre></div>

1510

</div>

1511

The returned object must be an iterator, i.e. <a class="reference internal" href="iter.html#c.PyIter_Check" title="PyIter_Check"><code class="xref c c-func docutils literal">PyIter_Check()</code></a> must

1512

return <code class="docutils literal">1</code> for it.

1513

This slot may be set to NULL if an object is not an <a class="reference internal" href="../glossary.html#term-awaitable">awaitable</a>.

1514

</dd></dl>

1515

1516

1517

1518

unaryfunc <code class="descname">PyAsyncMethods.am_aiter</code><a class="headerlink" href="#c.PyAsyncMethods.am_aiter" title="Permalink to this definition">¶</a></dt>

1519

<dd>The signature of this function is:

1520

<div class="highlight-c"><div class="highlight"><pre>PyObject *am_aiter(PyObject *self)

1521

</pre></div>

1522

</div>

1523

Must return an <a class="reference internal" href="../glossary.html#term-awaitable">awaitable</a> object. See <a class="reference internal" href="../reference/datamodel.html#object.__anext__" title="object.__anext__"><code class="xref py py-meth docutils literal">__anext__()</code></a> for details.

1524

This slot may be set to NULL if an object does not implement

1525

asynchronous iteration protocol.

1526

</dd></dl>

1527

1528

1529

1530

unaryfunc <code class="descname">PyAsyncMethods.am_anext</code><a class="headerlink" href="#c.PyAsyncMethods.am_anext" title="Permalink to this definition">¶</a></dt>

1531

<dd>The signature of this function is:

1532

<div class="highlight-c"><div class="highlight"><pre>PyObject *am_anext(PyObject *self)

1533

</pre></div>

1534

</div>

1535

1536

This slot may be set to NULL.

1537

</dd></dl>

1538

1539

</div>

1540

1541

1542

</div>

1543

</div>

1544

</div>

1545

1546

1547

<h3><a href="../contents.html">Table Of Contents</a></h3>

1548

<ul>

1549

<li><a class="reference internal" href="#">Type Objects</a></li>

1550

<li><a class="reference internal" href="#number-object-structures">Number Object Structures</a></li>

1551

<li><a class="reference internal" href="#mapping-object-structures">Mapping Object Structures</a></li>

1552

<li><a class="reference internal" href="#sequence-object-structures">Sequence Object Structures</a></li>

1553

<li><a class="reference internal" href="#buffer-object-structures">Buffer Object Structures</a></li>

1554

<li><a class="reference internal" href="#async-object-structures">Async Object Structures</a></li>

1555

</ul>

1556

1557

<h4>Previous topic</h4>

1558

<a href="structures.html"

1559

title="previous chapter">Common Object Structures</a>

1560

<h4>Next topic</h4>

1561

<a href="gcsupport.html"

1562

title="next chapter">Supporting Cyclic Garbage Collection</a>

1563

1564

1565

<li><a href="../bugs.html">Report a Bug</a></li>

1566

<li><a href="../_sources/c-api/typeobj.txt"

1567

rel="nofollow">Show Source</a></li>

1568

</ul>

1569

1570

1571

<h3>Quick search</h3>

1572

1573

1574

1575

1576

1577

</form>

1578

1579

Enter search terms or a module, class or function name.

1580

1581

</div>

1582

1583

</div>

1584

</div>

1585

1586

</div>

1587

1588

<h3>Navigation</h3>

1589

<ul>

1590

1591

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

1592

>index</a></li>

1593

1594

<a href="../py-modindex.html" title="Python Module Index"

1595

>modules</a> |</li>

1596

1597

<a href="gcsupport.html" title="Supporting Cyclic Garbage Collection"

1598

>next</a> |</li>

1599

1600

<a href="structures.html" title="Common Object Structures"

1601

>previous</a> |</li>

1602

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

1603

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

1604

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

1605

<li>

1606

3.5.1

1607

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

1608

</li>

1609

1610

<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>

1611

<li class="nav-item nav-item-2"><a href="objimpl.html" >Object Implementation Support</a> »</li>

1612

</ul>

1613

</div>

1614

1615

1616

1617

The Python Software Foundation is a non-profit corporation.

1618

<a href="https://www.python.org/psf/donations/">Please donate.</a>

1619

1620

Last updated on Jan 22, 2016.

1621

<a href="../bugs.html">Found a bug</a>?

1622

1623

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

1624

</div>

1625

1626

</body>

1627

</html>

b'\\ No newline at end of file'

Older »