| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _common-structs: |
| 4 |
|
| 5 |
Common Object Structures |
| 6 |
======================== |
| 7 |
|
| 8 |
There are a large number of structures which are used in the definition of |
| 9 |
object types for Python. This section describes these structures and how they |
| 10 |
are used. |
| 11 |
|
| 12 |
|
| 13 |
Base object types and macros |
| 14 |
---------------------------- |
| 15 |
|
| 16 |
All Python objects ultimately share a small number of fields at the beginning |
| 17 |
of the object's representation in memory. These are represented by the |
| 18 |
:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn, |
| 19 |
by the expansions of some macros also used, whether directly or indirectly, in |
| 20 |
the definition of all other Python objects. Additional macros can be found |
| 21 |
under :ref:`reference counting <countingrefs>`. |
| 22 |
|
| 23 |
|
| 24 |
.. c:type:: PyObject |
| 25 |
|
| 26 |
All object types are extensions of this type. This is a type which |
| 27 |
contains the information Python needs to treat a pointer to an object as an |
| 28 |
object. In a normal "release" build, it contains only the object's |
| 29 |
reference count and a pointer to the corresponding type object. |
| 30 |
Nothing is actually declared to be a :c:type:`PyObject`, but every pointer |
| 31 |
to a Python object can be cast to a :c:expr:`PyObject*`. |
| 32 |
|
| 33 |
The members must not be accessed directly; instead use macros such as |
| 34 |
:c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`. |
| 35 |
|
| 36 |
.. c:member:: Py_ssize_t ob_refcnt |
| 37 |
|
| 38 |
The object's reference count, as returned by :c:macro:`Py_REFCNT`. |
| 39 |
Do not use this field directly; instead use functions and macros such as |
| 40 |
:c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`. |
| 41 |
|
| 42 |
The field type may be different from ``Py_ssize_t``, depending on |
| 43 |
build configuration and platform. |
| 44 |
|
| 45 |
.. c:member:: PyTypeObject* ob_type |
| 46 |
|
| 47 |
The object's type. |
| 48 |
Do not use this field directly; use :c:macro:`Py_TYPE` and |
| 49 |
:c:func:`Py_SET_TYPE` instead. |
| 50 |
|
| 51 |
|
| 52 |
.. c:type:: PyVarObject |
| 53 |
|
| 54 |
An extension of :c:type:`PyObject` that adds the |
| 55 |
:c:member:`~PyVarObject.ob_size` field. |
| 56 |
This is intended for objects that have some notion of *length*. |
| 57 |
|
| 58 |
As with :c:type:`!PyObject`, the members must not be accessed directly; |
| 59 |
instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and |
| 60 |
:c:macro:`Py_TYPE`. |
| 61 |
|
| 62 |
.. c:member:: Py_ssize_t ob_size |
| 63 |
|
| 64 |
A size field, whose contents should be considered an object's internal |
| 65 |
implementation detail. |
| 66 |
|
| 67 |
Do not use this field directly; use :c:macro:`Py_SIZE` instead. |
| 68 |
|
| 69 |
Object creation functions such as :c:func:`PyObject_NewVar` will |
| 70 |
generally set this field to the requested size (number of items). |
| 71 |
After creation, arbitrary values can be stored in :c:member:`!ob_size` |
| 72 |
using :c:macro:`Py_SET_SIZE`. |
| 73 |
|
| 74 |
To get an object's publicly exposed length, as returned by |
| 75 |
the Python function :py:func:`len`, use :c:func:`PyObject_Length` |
| 76 |
instead. |
| 77 |
|
| 78 |
|
| 79 |
.. c:macro:: PyObject_HEAD |
| 80 |
|
| 81 |
This is a macro used when declaring new types which represent objects |
| 82 |
without a varying length. The PyObject_HEAD macro expands to:: |
| 83 |
|
| 84 |
PyObject ob_base; |
| 85 |
|
| 86 |
See documentation of :c:type:`PyObject` above. |
| 87 |
|
| 88 |
|
| 89 |
.. c:macro:: PyObject_VAR_HEAD |
| 90 |
|
| 91 |
This is a macro used when declaring new types which represent objects |
| 92 |
with a length that varies from instance to instance. |
| 93 |
The PyObject_VAR_HEAD macro expands to:: |
| 94 |
|
| 95 |
PyVarObject ob_base; |
| 96 |
|
| 97 |
See documentation of :c:type:`PyVarObject` above. |
| 98 |
|
| 99 |
|
| 100 |
.. c:var:: PyTypeObject PyBaseObject_Type |
| 101 |
|
| 102 |
The base class of all other objects, the same as :class:`object` in Python. |
| 103 |
|
| 104 |
|
| 105 |
.. c:function:: int Py_Is(PyObject *x, PyObject *y) |
| 106 |
|
| 107 |
Test if the *x* object is the *y* object, the same as ``x is y`` in Python. |
| 108 |
|
| 109 |
.. versionadded:: 3.10 |
| 110 |
|
| 111 |
|
| 112 |
.. c:function:: int Py_IsNone(PyObject *x) |
| 113 |
|
| 114 |
Test if an object is the ``None`` singleton, |
| 115 |
the same as ``x is None`` in Python. |
| 116 |
|
| 117 |
.. versionadded:: 3.10 |
| 118 |
|
| 119 |
|
| 120 |
.. c:function:: int Py_IsTrue(PyObject *x) |
| 121 |
|
| 122 |
Test if an object is the ``True`` singleton, |
| 123 |
the same as ``x is True`` in Python. |
| 124 |
|
| 125 |
.. versionadded:: 3.10 |
| 126 |
|
| 127 |
|
| 128 |
.. c:function:: int Py_IsFalse(PyObject *x) |
| 129 |
|
| 130 |
Test if an object is the ``False`` singleton, |
| 131 |
the same as ``x is False`` in Python. |
| 132 |
|
| 133 |
.. versionadded:: 3.10 |
| 134 |
|
| 135 |
|
| 136 |
.. c:function:: PyTypeObject* Py_TYPE(PyObject *o) |
| 137 |
|
| 138 |
Get the type of the Python object *o*. |
| 139 |
|
| 140 |
The returned reference is :term:`borrowed <borrowed reference>` from *o*. |
| 141 |
Do not release it with :c:func:`Py_DECREF` or similar. |
| 142 |
|
| 143 |
.. versionchanged:: 3.11 |
| 144 |
:c:func:`Py_TYPE()` is changed to an inline static function. |
| 145 |
The parameter type is no longer :c:expr:`const PyObject*`. |
| 146 |
|
| 147 |
|
| 148 |
.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type) |
| 149 |
|
| 150 |
Return non-zero if the object *o* type is *type*. Return zero otherwise. |
| 151 |
Equivalent to: ``Py_TYPE(o) == type``. |
| 152 |
|
| 153 |
.. versionadded:: 3.9 |
| 154 |
|
| 155 |
|
| 156 |
.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type) |
| 157 |
|
| 158 |
Set the type of object *o* to *type*, without any checking or reference |
| 159 |
counting. |
| 160 |
|
| 161 |
This is a very low-level operation. |
| 162 |
Consider instead setting the Python attribute :attr:`~object.__class__` |
| 163 |
using :c:func:`PyObject_SetAttrString` or similar. |
| 164 |
|
| 165 |
Note that assigning an incompatible type can lead to undefined behavior. |
| 166 |
|
| 167 |
If *type* is a :ref:`heap type <heap-types>`, the caller must create a |
| 168 |
new reference to it. |
| 169 |
Similarly, if the old type of *o* is a heap type, the caller must release |
| 170 |
a reference to that type. |
| 171 |
|
| 172 |
.. versionadded:: 3.9 |
| 173 |
|
| 174 |
|
| 175 |
.. c:function:: Py_ssize_t Py_SIZE(PyVarObject *o) |
| 176 |
|
| 177 |
Get the :c:member:`~PyVarObject.ob_size` field of *o*. |
| 178 |
|
| 179 |
.. versionchanged:: 3.11 |
| 180 |
:c:func:`Py_SIZE()` is changed to an inline static function. |
| 181 |
The parameter type is no longer :c:expr:`const PyVarObject*`. |
| 182 |
|
| 183 |
|
| 184 |
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size) |
| 185 |
|
| 186 |
Set the :c:member:`~PyVarObject.ob_size` field of *o* to *size*. |
| 187 |
|
| 188 |
.. versionadded:: 3.9 |
| 189 |
|
| 190 |
|
| 191 |
.. c:macro:: PyObject_HEAD_INIT(type) |
| 192 |
|
| 193 |
This is a macro which expands to initialization values for a new |
| 194 |
:c:type:`PyObject` type. This macro expands to:: |
| 195 |
|
| 196 |
_PyObject_EXTRA_INIT |
| 197 |
1, type, |
| 198 |
|
| 199 |
|
| 200 |
.. c:macro:: PyVarObject_HEAD_INIT(type, size) |
| 201 |
|
| 202 |
This is a macro which expands to initialization values for a new |
| 203 |
:c:type:`PyVarObject` type, including the :c:member:`~PyVarObject.ob_size` field. |
| 204 |
This macro expands to:: |
| 205 |
|
| 206 |
_PyObject_EXTRA_INIT |
| 207 |
1, type, size, |
| 208 |
|
| 209 |
|
| 210 |
Implementing functions and methods |
| 211 |
---------------------------------- |
| 212 |
|
| 213 |
.. c:type:: PyCFunction |
| 214 |
|
| 215 |
Type of the functions used to implement most Python callables in C. |
| 216 |
Functions of this type take two :c:expr:`PyObject*` parameters and return |
| 217 |
one such value. If the return value is ``NULL``, an exception shall have |
| 218 |
been set. If not ``NULL``, the return value is interpreted as the return |
| 219 |
value of the function as exposed in Python. The function must return a new |
| 220 |
reference. |
| 221 |
|
| 222 |
The function signature is:: |
| 223 |
|
| 224 |
PyObject *PyCFunction(PyObject *self, |
| 225 |
PyObject *args); |
| 226 |
|
| 227 |
.. c:type:: PyCFunctionWithKeywords |
| 228 |
|
| 229 |
Type of the functions used to implement Python callables in C |
| 230 |
with signature :ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`. |
| 231 |
The function signature is:: |
| 232 |
|
| 233 |
PyObject *PyCFunctionWithKeywords(PyObject *self, |
| 234 |
PyObject *args, |
| 235 |
PyObject *kwargs); |
| 236 |
|
| 237 |
|
| 238 |
.. c:type:: PyCFunctionFast |
| 239 |
|
| 240 |
Type of the functions used to implement Python callables in C |
| 241 |
with signature :c:macro:`METH_FASTCALL`. |
| 242 |
The function signature is:: |
| 243 |
|
| 244 |
PyObject *PyCFunctionFast(PyObject *self, |
| 245 |
PyObject *const *args, |
| 246 |
Py_ssize_t nargs); |
| 247 |
|
| 248 |
.. c:type:: PyCFunctionFastWithKeywords |
| 249 |
|
| 250 |
Type of the functions used to implement Python callables in C |
| 251 |
with signature :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>`. |
| 252 |
The function signature is:: |
| 253 |
|
| 254 |
PyObject *PyCFunctionFastWithKeywords(PyObject *self, |
| 255 |
PyObject *const *args, |
| 256 |
Py_ssize_t nargs, |
| 257 |
PyObject *kwnames); |
| 258 |
|
| 259 |
.. c:type:: PyCMethod |
| 260 |
|
| 261 |
Type of the functions used to implement Python callables in C |
| 262 |
with signature :ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`. |
| 263 |
The function signature is:: |
| 264 |
|
| 265 |
PyObject *PyCMethod(PyObject *self, |
| 266 |
PyTypeObject *defining_class, |
| 267 |
PyObject *const *args, |
| 268 |
Py_ssize_t nargs, |
| 269 |
PyObject *kwnames) |
| 270 |
|
| 271 |
.. versionadded:: 3.9 |
| 272 |
|
| 273 |
|
| 274 |
.. c:type:: PyMethodDef |
| 275 |
|
| 276 |
Structure used to describe a method of an extension type. This structure has |
| 277 |
four fields: |
| 278 |
|
| 279 |
.. c:member:: const char *ml_name |
| 280 |
|
| 281 |
Name of the method. |
| 282 |
|
| 283 |
.. c:member:: PyCFunction ml_meth |
| 284 |
|
| 285 |
Pointer to the C implementation. |
| 286 |
|
| 287 |
.. c:member:: int ml_flags |
| 288 |
|
| 289 |
Flags bits indicating how the call should be constructed. |
| 290 |
|
| 291 |
.. c:member:: const char *ml_doc |
| 292 |
|
| 293 |
Points to the contents of the docstring. |
| 294 |
|
| 295 |
The :c:member:`~PyMethodDef.ml_meth` is a C function pointer. |
| 296 |
The functions may be of different |
| 297 |
types, but they always return :c:expr:`PyObject*`. If the function is not of |
| 298 |
the :c:type:`PyCFunction`, the compiler will require a cast in the method table. |
| 299 |
Even though :c:type:`PyCFunction` defines the first parameter as |
| 300 |
:c:expr:`PyObject*`, it is common that the method implementation uses the |
| 301 |
specific C type of the *self* object. |
| 302 |
|
| 303 |
The :c:member:`~PyMethodDef.ml_flags` field is a bitfield which can include |
| 304 |
the following flags. |
| 305 |
The individual flags indicate either a calling convention or a binding |
| 306 |
convention. |
| 307 |
|
| 308 |
There are these calling conventions: |
| 309 |
|
| 310 |
.. c:macro:: METH_VARARGS |
| 311 |
|
| 312 |
This is the typical calling convention, where the methods have the type |
| 313 |
:c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values. |
| 314 |
The first one is the *self* object for methods; for module functions, it is |
| 315 |
the module object. The second parameter (often called *args*) is a tuple |
| 316 |
object representing all arguments. This parameter is typically processed |
| 317 |
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. |
| 318 |
|
| 319 |
|
| 320 |
.. c:macro:: METH_KEYWORDS |
| 321 |
|
| 322 |
Can only be used in certain combinations with other flags: |
| 323 |
:ref:`METH_VARARGS | METH_KEYWORDS <METH_VARARGS-METH_KEYWORDS>`, |
| 324 |
:ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>` and |
| 325 |
:ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`. |
| 326 |
|
| 327 |
|
| 328 |
.. _METH_VARARGS-METH_KEYWORDS: |
| 329 |
|
| 330 |
:c:expr:`METH_VARARGS | METH_KEYWORDS` |
| 331 |
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. |
| 332 |
The function expects three parameters: *self*, *args*, *kwargs* where |
| 333 |
*kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` |
| 334 |
if there are no keyword arguments. The parameters are typically processed |
| 335 |
using :c:func:`PyArg_ParseTupleAndKeywords`. |
| 336 |
|
| 337 |
|
| 338 |
.. c:macro:: METH_FASTCALL |
| 339 |
|
| 340 |
Fast calling convention supporting only positional arguments. |
| 341 |
The methods have the type :c:type:`PyCFunctionFast`. |
| 342 |
The first parameter is *self*, the second parameter is a C array |
| 343 |
of :c:expr:`PyObject*` values indicating the arguments and the third |
| 344 |
parameter is the number of arguments (the length of the array). |
| 345 |
|
| 346 |
.. versionadded:: 3.7 |
| 347 |
|
| 348 |
.. versionchanged:: 3.10 |
| 349 |
|
| 350 |
``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`. |
| 351 |
|
| 352 |
|
| 353 |
.. _METH_FASTCALL-METH_KEYWORDS: |
| 354 |
|
| 355 |
:c:expr:`METH_FASTCALL | METH_KEYWORDS` |
| 356 |
Extension of :c:macro:`METH_FASTCALL` supporting also keyword arguments, |
| 357 |
with methods of type :c:type:`PyCFunctionFastWithKeywords`. |
| 358 |
Keyword arguments are passed the same way as in the |
| 359 |
:ref:`vectorcall protocol <vectorcall>`: |
| 360 |
there is an additional fourth :c:expr:`PyObject*` parameter |
| 361 |
which is a tuple representing the names of the keyword arguments |
| 362 |
(which are guaranteed to be strings) |
| 363 |
or possibly ``NULL`` if there are no keywords. The values of the keyword |
| 364 |
arguments are stored in the *args* array, after the positional arguments. |
| 365 |
|
| 366 |
.. versionadded:: 3.7 |
| 367 |
|
| 368 |
|
| 369 |
.. c:macro:: METH_METHOD |
| 370 |
|
| 371 |
Can only be used in the combination with other flags: |
| 372 |
:ref:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS <METH_METHOD-METH_FASTCALL-METH_KEYWORDS>`. |
| 373 |
|
| 374 |
|
| 375 |
.. _METH_METHOD-METH_FASTCALL-METH_KEYWORDS: |
| 376 |
|
| 377 |
:c:expr:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS` |
| 378 |
Extension of :ref:`METH_FASTCALL | METH_KEYWORDS <METH_FASTCALL-METH_KEYWORDS>` |
| 379 |
supporting the *defining class*, that is, |
| 380 |
the class that contains the method in question. |
| 381 |
The defining class might be a superclass of ``Py_TYPE(self)``. |
| 382 |
|
| 383 |
The method needs to be of type :c:type:`PyCMethod`, the same as for |
| 384 |
``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after |
| 385 |
``self``. |
| 386 |
|
| 387 |
.. versionadded:: 3.9 |
| 388 |
|
| 389 |
|
| 390 |
.. c:macro:: METH_NOARGS |
| 391 |
|
| 392 |
Methods without parameters don't need to check whether arguments are given if |
| 393 |
they are listed with the :c:macro:`METH_NOARGS` flag. They need to be of type |
| 394 |
:c:type:`PyCFunction`. The first parameter is typically named *self* and will |
| 395 |
hold a reference to the module or object instance. In all cases the second |
| 396 |
parameter will be ``NULL``. |
| 397 |
|
| 398 |
The function must have 2 parameters. Since the second parameter is unused, |
| 399 |
:c:macro:`Py_UNUSED` can be used to prevent a compiler warning. |
| 400 |
|
| 401 |
|
| 402 |
.. c:macro:: METH_O |
| 403 |
|
| 404 |
Methods with a single object argument can be listed with the :c:macro:`METH_O` |
| 405 |
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. |
| 406 |
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a |
| 407 |
:c:expr:`PyObject*` parameter representing the single argument. |
| 408 |
|
| 409 |
|
| 410 |
These two constants are not used to indicate the calling convention but the |
| 411 |
binding when used with methods of classes. These may not be used for functions |
| 412 |
defined for modules. At most one of these flags may be set for any given |
| 413 |
method. |
| 414 |
|
| 415 |
|
| 416 |
.. c:macro:: METH_CLASS |
| 417 |
|
| 418 |
.. index:: pair: built-in function; classmethod |
| 419 |
|
| 420 |
The method will be passed the type object as the first parameter rather |
| 421 |
than an instance of the type. This is used to create *class methods*, |
| 422 |
similar to what is created when using the :func:`classmethod` built-in |
| 423 |
function. |
| 424 |
|
| 425 |
|
| 426 |
.. c:macro:: METH_STATIC |
| 427 |
|
| 428 |
.. index:: pair: built-in function; staticmethod |
| 429 |
|
| 430 |
The method will be passed ``NULL`` as the first parameter rather than an |
| 431 |
instance of the type. This is used to create *static methods*, similar to |
| 432 |
what is created when using the :func:`staticmethod` built-in function. |
| 433 |
|
| 434 |
One other constant controls whether a method is loaded in place of another |
| 435 |
definition with the same method name. |
| 436 |
|
| 437 |
|
| 438 |
.. c:macro:: METH_COEXIST |
| 439 |
|
| 440 |
The method will be loaded in place of existing definitions. Without |
| 441 |
*METH_COEXIST*, the default is to skip repeated definitions. Since slot |
| 442 |
wrappers are loaded before the method table, the existence of a |
| 443 |
*sq_contains* slot, for example, would generate a wrapped method named |
| 444 |
:meth:`~object.__contains__` and preclude the loading of a corresponding |
| 445 |
PyCFunction with the same name. With the flag defined, the PyCFunction |
| 446 |
will be loaded in place of the wrapper object and will co-exist with the |
| 447 |
slot. This is helpful because calls to PyCFunctions are optimized more |
| 448 |
than wrapper object calls. |
| 449 |
|
| 450 |
|
| 451 |
.. c:var:: PyTypeObject PyCMethod_Type |
| 452 |
|
| 453 |
The type object corresponding to Python C method objects. This is |
| 454 |
available as :class:`types.BuiltinMethodType` in the Python layer. |
| 455 |
|
| 456 |
|
| 457 |
.. c:function:: int PyCMethod_Check(PyObject *op) |
| 458 |
|
| 459 |
Return true if *op* is an instance of the :c:type:`PyCMethod_Type` type |
| 460 |
or a subtype of it. This function always succeeds. |
| 461 |
|
| 462 |
|
| 463 |
.. c:function:: int PyCMethod_CheckExact(PyObject *op) |
| 464 |
|
| 465 |
This is the same as :c:func:`PyCMethod_Check`, but does not account for |
| 466 |
subtypes. |
| 467 |
|
| 468 |
|
| 469 |
.. c:function:: PyObject * PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls) |
| 470 |
|
| 471 |
Turn *ml* into a Python :term:`callable` object. |
| 472 |
The caller must ensure that *ml* outlives the :term:`callable`. |
| 473 |
Typically, *ml* is defined as a static variable. |
| 474 |
|
| 475 |
The *self* parameter will be passed as the *self* argument |
| 476 |
to the C function in ``ml->ml_meth`` when invoked. |
| 477 |
*self* can be ``NULL``. |
| 478 |
|
| 479 |
The :term:`callable` object's ``__module__`` attribute |
| 480 |
can be set from the given *module* argument. |
| 481 |
*module* should be a Python string, |
| 482 |
which will be used as name of the module the function is defined in. |
| 483 |
If unavailable, it can be set to :const:`None` or ``NULL``. |
| 484 |
|
| 485 |
.. seealso:: :attr:`function.__module__` |
| 486 |
|
| 487 |
The *cls* parameter will be passed as the *defining_class* |
| 488 |
argument to the C function. |
| 489 |
Must be set if :c:macro:`METH_METHOD` is set on ``ml->ml_flags``. |
| 490 |
|
| 491 |
.. versionadded:: 3.9 |
| 492 |
|
| 493 |
|
| 494 |
.. c:var:: PyTypeObject PyCFunction_Type |
| 495 |
|
| 496 |
The type object corresponding to Python C function objects. This is |
| 497 |
available as :class:`types.BuiltinFunctionType` in the Python layer. |
| 498 |
|
| 499 |
|
| 500 |
.. c:function:: int PyCFunction_Check(PyObject *op) |
| 501 |
|
| 502 |
Return true if *op* is an instance of the :c:type:`PyCFunction_Type` type |
| 503 |
or a subtype of it. This function always succeeds. |
| 504 |
|
| 505 |
|
| 506 |
.. c:function:: int PyCFunction_CheckExact(PyObject *op) |
| 507 |
|
| 508 |
This is the same as :c:func:`PyCFunction_Check`, but does not account for |
| 509 |
subtypes. |
| 510 |
|
| 511 |
|
| 512 |
.. c:function:: PyObject * PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module) |
| 513 |
|
| 514 |
Equivalent to ``PyCMethod_New(ml, self, module, NULL)``. |
| 515 |
|
| 516 |
|
| 517 |
.. c:function:: PyObject * PyCFunction_New(PyMethodDef *ml, PyObject *self) |
| 518 |
|
| 519 |
Equivalent to ``PyCMethod_New(ml, self, NULL, NULL)``. |
| 520 |
|
| 521 |
|
| 522 |
.. c:function:: int PyCFunction_GetFlags(PyObject *func) |
| 523 |
|
| 524 |
Get the function's flags on *func* as they were passed to |
| 525 |
:c:member:`~PyMethodDef.ml_flags`. |
| 526 |
|
| 527 |
If *func* is not a C function object, this fails with an exception. |
| 528 |
*func* must not be ``NULL``. |
| 529 |
|
| 530 |
This function returns the function's flags on success, and ``-1`` with an |
| 531 |
exception set on failure. |
| 532 |
|
| 533 |
|
| 534 |
.. c:function:: int PyCFunction_GET_FLAGS(PyObject *func) |
| 535 |
|
| 536 |
This is the same as :c:func:`PyCFunction_GetFlags`, but without error |
| 537 |
or type checking. |
| 538 |
|
| 539 |
|
| 540 |
.. c:function:: PyCFunction PyCFunction_GetFunction(PyObject *func) |
| 541 |
|
| 542 |
Get the function pointer on *func* as it was passed to |
| 543 |
:c:member:`~PyMethodDef.ml_meth`. |
| 544 |
|
| 545 |
If *func* is not a C function object, this fails with an exception. |
| 546 |
*func* must not be ``NULL``. |
| 547 |
|
| 548 |
This function returns the function pointer on success, and ``NULL`` with an |
| 549 |
exception set on failure. |
| 550 |
|
| 551 |
|
| 552 |
.. c:function:: int PyCFunction_GET_FUNCTION(PyObject *func) |
| 553 |
|
| 554 |
This is the same as :c:func:`PyCFunction_GetFunction`, but without error |
| 555 |
or type checking. |
| 556 |
|
| 557 |
|
| 558 |
.. c:function:: PyObject *PyCFunction_GetSelf(PyObject *func) |
| 559 |
|
| 560 |
Get the "self" object on *func*. This is the object that would be passed |
| 561 |
to the first argument of a :c:type:`PyCFunction`. For C function objects |
| 562 |
created through a :c:type:`PyMethodDef` on a :c:type:`PyModuleDef`, this |
| 563 |
is the resulting module object. |
| 564 |
|
| 565 |
If *func* is not a C function object, this fails with an exception. |
| 566 |
*func* must not be ``NULL``. |
| 567 |
|
| 568 |
This function returns a :term:`borrowed reference` to the "self" object |
| 569 |
on success, and ``NULL`` with an exception set on failure. |
| 570 |
|
| 571 |
|
| 572 |
.. c:function:: PyObject *PyCFunction_GET_SELF(PyObject *func) |
| 573 |
|
| 574 |
This is the same as :c:func:`PyCFunction_GetSelf`, but without error or |
| 575 |
type checking. |
| 576 |
|
| 577 |
|
| 578 |
Accessing attributes of extension types |
| 579 |
--------------------------------------- |
| 580 |
|
| 581 |
.. c:type:: PyMemberDef |
| 582 |
|
| 583 |
Structure which describes an attribute of a type which corresponds to a C |
| 584 |
struct member. |
| 585 |
When defining a class, put a NULL-terminated array of these |
| 586 |
structures in the :c:member:`~PyTypeObject.tp_members` slot. |
| 587 |
|
| 588 |
Its fields are, in order: |
| 589 |
|
| 590 |
.. c:member:: const char* name |
| 591 |
|
| 592 |
Name of the member. |
| 593 |
A NULL value marks the end of a ``PyMemberDef[]`` array. |
| 594 |
|
| 595 |
The string should be static, no copy is made of it. |
| 596 |
|
| 597 |
.. c:member:: int type |
| 598 |
|
| 599 |
The type of the member in the C struct. |
| 600 |
See :ref:`PyMemberDef-types` for the possible values. |
| 601 |
|
| 602 |
.. c:member:: Py_ssize_t offset |
| 603 |
|
| 604 |
The offset in bytes that the member is located on the type’s object struct. |
| 605 |
|
| 606 |
.. c:member:: int flags |
| 607 |
|
| 608 |
Zero or more of the :ref:`PyMemberDef-flags`, combined using bitwise OR. |
| 609 |
|
| 610 |
.. c:member:: const char* doc |
| 611 |
|
| 612 |
The docstring, or NULL. |
| 613 |
The string should be static, no copy is made of it. |
| 614 |
Typically, it is defined using :c:macro:`PyDoc_STR`. |
| 615 |
|
| 616 |
By default (when :c:member:`~PyMemberDef.flags` is ``0``), members allow |
| 617 |
both read and write access. |
| 618 |
Use the :c:macro:`Py_READONLY` flag for read-only access. |
| 619 |
Certain types, like :c:macro:`Py_T_STRING`, imply :c:macro:`Py_READONLY`. |
| 620 |
Only :c:macro:`Py_T_OBJECT_EX` (and legacy :c:macro:`T_OBJECT`) members can |
| 621 |
be deleted. |
| 622 |
|
| 623 |
.. _pymemberdef-offsets: |
| 624 |
|
| 625 |
For heap-allocated types (created using :c:func:`PyType_FromSpec` or similar), |
| 626 |
``PyMemberDef`` may contain a definition for the special member |
| 627 |
``"__vectorcalloffset__"``, corresponding to |
| 628 |
:c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects. |
| 629 |
This member must be defined with ``Py_T_PYSSIZET``, and either |
| 630 |
``Py_READONLY`` or ``Py_READONLY | Py_RELATIVE_OFFSET``. For example:: |
| 631 |
|
| 632 |
static PyMemberDef spam_type_members[] = { |
| 633 |
{"__vectorcalloffset__", Py_T_PYSSIZET, |
| 634 |
offsetof(Spam_object, vectorcall), Py_READONLY}, |
| 635 |
{NULL} /* Sentinel */ |
| 636 |
}; |
| 637 |
|
| 638 |
(You may need to ``#include <stddef.h>`` for :c:func:`!offsetof`.) |
| 639 |
|
| 640 |
The legacy offsets :c:member:`~PyTypeObject.tp_dictoffset` and |
| 641 |
:c:member:`~PyTypeObject.tp_weaklistoffset` can be defined similarly using |
| 642 |
``"__dictoffset__"`` and ``"__weaklistoffset__"`` members, but extensions |
| 643 |
are strongly encouraged to use :c:macro:`Py_TPFLAGS_MANAGED_DICT` and |
| 644 |
:c:macro:`Py_TPFLAGS_MANAGED_WEAKREF` instead. |
| 645 |
|
| 646 |
.. versionchanged:: 3.12 |
| 647 |
|
| 648 |
``PyMemberDef`` is always available. |
| 649 |
Previously, it required including ``"structmember.h"``. |
| 650 |
|
| 651 |
.. versionchanged:: 3.14 |
| 652 |
|
| 653 |
:c:macro:`Py_RELATIVE_OFFSET` is now allowed for |
| 654 |
``"__vectorcalloffset__"``, ``"__dictoffset__"`` and |
| 655 |
``"__weaklistoffset__"``. |
| 656 |
|
| 657 |
.. c:function:: PyObject* PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m) |
| 658 |
|
| 659 |
Get an attribute belonging to the object at address *obj_addr*. The |
| 660 |
attribute is described by ``PyMemberDef`` *m*. Returns ``NULL`` |
| 661 |
on error. |
| 662 |
|
| 663 |
.. versionchanged:: 3.12 |
| 664 |
|
| 665 |
``PyMember_GetOne`` is always available. |
| 666 |
Previously, it required including ``"structmember.h"``. |
| 667 |
|
| 668 |
.. c:function:: int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o) |
| 669 |
|
| 670 |
Set an attribute belonging to the object at address *obj_addr* to object *o*. |
| 671 |
The attribute to set is described by ``PyMemberDef`` *m*. Returns ``0`` |
| 672 |
if successful and a negative value on failure. |
| 673 |
|
| 674 |
.. versionchanged:: 3.12 |
| 675 |
|
| 676 |
``PyMember_SetOne`` is always available. |
| 677 |
Previously, it required including ``"structmember.h"``. |
| 678 |
|
| 679 |
.. _PyMemberDef-flags: |
| 680 |
|
| 681 |
Member flags |
| 682 |
^^^^^^^^^^^^ |
| 683 |
|
| 684 |
The following flags can be used with :c:member:`PyMemberDef.flags`: |
| 685 |
|
| 686 |
.. c:macro:: Py_READONLY |
| 687 |
|
| 688 |
Not writable. |
| 689 |
|
| 690 |
.. c:macro:: Py_AUDIT_READ |
| 691 |
|
| 692 |
Emit an ``object.__getattr__`` :ref:`audit event <audit-events>` |
| 693 |
before reading. |
| 694 |
|
| 695 |
.. c:macro:: Py_RELATIVE_OFFSET |
| 696 |
|
| 697 |
Indicates that the :c:member:`~PyMemberDef.offset` of this ``PyMemberDef`` |
| 698 |
entry indicates an offset from the subclass-specific data, rather than |
| 699 |
from ``PyObject``. |
| 700 |
|
| 701 |
Can only be used as part of the :c:data:`Py_tp_members` |
| 702 |
:c:type:`slot <PyType_Slot>` when creating a class using negative |
| 703 |
:c:member:`~PyType_Spec.basicsize`. |
| 704 |
It is mandatory in that case. |
| 705 |
When setting :c:member:`~PyTypeObject.tp_members` from the slot during |
| 706 |
class creation, Python clears the flag and sets |
| 707 |
:c:member:`PyMemberDef.offset` to the offset from the ``PyObject`` struct. |
| 708 |
|
| 709 |
.. index:: |
| 710 |
single: READ_RESTRICTED (C macro) |
| 711 |
single: WRITE_RESTRICTED (C macro) |
| 712 |
single: RESTRICTED (C macro) |
| 713 |
|
| 714 |
.. versionchanged:: 3.10 |
| 715 |
|
| 716 |
The :c:macro:`!RESTRICTED`, :c:macro:`!READ_RESTRICTED` and |
| 717 |
:c:macro:`!WRITE_RESTRICTED` macros available with |
| 718 |
``#include "structmember.h"`` are deprecated. |
| 719 |
:c:macro:`!READ_RESTRICTED` and :c:macro:`!RESTRICTED` are equivalent to |
| 720 |
:c:macro:`Py_AUDIT_READ`; :c:macro:`!WRITE_RESTRICTED` does nothing. |
| 721 |
|
| 722 |
.. index:: |
| 723 |
single: READONLY (C macro) |
| 724 |
|
| 725 |
.. versionchanged:: 3.12 |
| 726 |
|
| 727 |
The :c:macro:`!READONLY` macro was renamed to :c:macro:`Py_READONLY`. |
| 728 |
The :c:macro:`!PY_AUDIT_READ` macro was renamed with the ``Py_`` prefix. |
| 729 |
The new names are now always available. |
| 730 |
Previously, these required ``#include "structmember.h"``. |
| 731 |
The header is still available and it provides the old names. |
| 732 |
|
| 733 |
.. _PyMemberDef-types: |
| 734 |
|
| 735 |
Member types |
| 736 |
^^^^^^^^^^^^ |
| 737 |
|
| 738 |
:c:member:`PyMemberDef.type` can be one of the following macros corresponding |
| 739 |
to various C types. |
| 740 |
When the member is accessed in Python, it will be converted to the |
| 741 |
equivalent Python type. |
| 742 |
When it is set from Python, it will be converted back to the C type. |
| 743 |
If that is not possible, an exception such as :exc:`TypeError` or |
| 744 |
:exc:`ValueError` is raised. |
| 745 |
|
| 746 |
Unless marked (D), attributes defined this way cannot be deleted |
| 747 |
using e.g. :keyword:`del` or :py:func:`delattr`. |
| 748 |
|
| 749 |
================================ ============================= ====================== |
| 750 |
Macro name C type Python type |
| 751 |
================================ ============================= ====================== |
| 752 |
.. c:macro:: Py_T_BYTE :c:expr:`char` :py:class:`int` |
| 753 |
.. c:macro:: Py_T_SHORT :c:expr:`short` :py:class:`int` |
| 754 |
.. c:macro:: Py_T_INT :c:expr:`int` :py:class:`int` |
| 755 |
.. c:macro:: Py_T_LONG :c:expr:`long` :py:class:`int` |
| 756 |
.. c:macro:: Py_T_LONGLONG :c:expr:`long long` :py:class:`int` |
| 757 |
.. c:macro:: Py_T_UBYTE :c:expr:`unsigned char` :py:class:`int` |
| 758 |
.. c:macro:: Py_T_UINT :c:expr:`unsigned int` :py:class:`int` |
| 759 |
.. c:macro:: Py_T_USHORT :c:expr:`unsigned short` :py:class:`int` |
| 760 |
.. c:macro:: Py_T_ULONG :c:expr:`unsigned long` :py:class:`int` |
| 761 |
.. c:macro:: Py_T_ULONGLONG :c:expr:`unsigned long long` :py:class:`int` |
| 762 |
.. c:macro:: Py_T_PYSSIZET :c:expr:`Py_ssize_t` :py:class:`int` |
| 763 |
.. c:macro:: Py_T_FLOAT :c:expr:`float` :py:class:`float` |
| 764 |
.. c:macro:: Py_T_DOUBLE :c:expr:`double` :py:class:`float` |
| 765 |
.. c:macro:: Py_T_BOOL :c:expr:`char` :py:class:`bool` |
| 766 |
(written as 0 or 1) |
| 767 |
.. c:macro:: Py_T_STRING :c:expr:`const char *` (*) :py:class:`str` (RO) |
| 768 |
.. c:macro:: Py_T_STRING_INPLACE :c:expr:`const char[]` (*) :py:class:`str` (RO) |
| 769 |
.. c:macro:: Py_T_CHAR :c:expr:`char` (0-127) :py:class:`str` (**) |
| 770 |
.. c:macro:: Py_T_OBJECT_EX :c:expr:`PyObject *` :py:class:`object` (D) |
| 771 |
================================ ============================= ====================== |
| 772 |
|
| 773 |
(*): Zero-terminated, UTF8-encoded C string. |
| 774 |
With :c:macro:`!Py_T_STRING` the C representation is a pointer; |
| 775 |
with :c:macro:`!Py_T_STRING_INPLACE` the string is stored directly |
| 776 |
in the structure. |
| 777 |
|
| 778 |
(**): String of length 1. Only ASCII is accepted. |
| 779 |
|
| 780 |
(RO): Implies :c:macro:`Py_READONLY`. |
| 781 |
|
| 782 |
(D): Can be deleted, in which case the pointer is set to ``NULL``. |
| 783 |
Reading a ``NULL`` pointer raises :py:exc:`AttributeError`. |
| 784 |
|
| 785 |
.. index:: |
| 786 |
single: T_BYTE (C macro) |
| 787 |
single: T_SHORT (C macro) |
| 788 |
single: T_INT (C macro) |
| 789 |
single: T_LONG (C macro) |
| 790 |
single: T_LONGLONG (C macro) |
| 791 |
single: T_UBYTE (C macro) |
| 792 |
single: T_USHORT (C macro) |
| 793 |
single: T_UINT (C macro) |
| 794 |
single: T_ULONG (C macro) |
| 795 |
single: T_ULONGULONG (C macro) |
| 796 |
single: T_PYSSIZET (C macro) |
| 797 |
single: T_FLOAT (C macro) |
| 798 |
single: T_DOUBLE (C macro) |
| 799 |
single: T_BOOL (C macro) |
| 800 |
single: T_CHAR (C macro) |
| 801 |
single: T_STRING (C macro) |
| 802 |
single: T_STRING_INPLACE (C macro) |
| 803 |
single: T_OBJECT_EX (C macro) |
| 804 |
single: structmember.h |
| 805 |
|
| 806 |
.. versionadded:: 3.12 |
| 807 |
|
| 808 |
In previous versions, the macros were only available with |
| 809 |
``#include "structmember.h"`` and were named without the ``Py_`` prefix |
| 810 |
(e.g. as ``T_INT``). |
| 811 |
The header is still available and contains the old names, along with |
| 812 |
the following deprecated types: |
| 813 |
|
| 814 |
.. c:macro:: T_OBJECT |
| 815 |
|
| 816 |
Like ``Py_T_OBJECT_EX``, but ``NULL`` is converted to ``None``. |
| 817 |
This results in surprising behavior in Python: deleting the attribute |
| 818 |
effectively sets it to ``None``. |
| 819 |
|
| 820 |
.. c:macro:: T_NONE |
| 821 |
|
| 822 |
Always ``None``. Must be used with :c:macro:`Py_READONLY`. |
| 823 |
|
| 824 |
Defining Getters and Setters |
| 825 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 826 |
|
| 827 |
.. c:type:: PyGetSetDef |
| 828 |
|
| 829 |
Structure to define property-like access for a type. See also description of |
| 830 |
the :c:member:`PyTypeObject.tp_getset` slot. |
| 831 |
|
| 832 |
.. c:member:: const char* name |
| 833 |
|
| 834 |
attribute name |
| 835 |
|
| 836 |
.. c:member:: getter get |
| 837 |
|
| 838 |
C function to get the attribute. |
| 839 |
|
| 840 |
.. c:member:: setter set |
| 841 |
|
| 842 |
Optional C function to set or delete the attribute. |
| 843 |
If ``NULL``, the attribute is read-only. |
| 844 |
|
| 845 |
.. c:member:: const char* doc |
| 846 |
|
| 847 |
optional docstring |
| 848 |
|
| 849 |
.. c:member:: void* closure |
| 850 |
|
| 851 |
Optional user data pointer, providing additional data for getter and setter. |
| 852 |
|
| 853 |
.. c:type:: PyObject *(*getter)(PyObject *, void *) |
| 854 |
|
| 855 |
The ``get`` function takes one :c:expr:`PyObject*` parameter (the |
| 856 |
instance) and a user data pointer (the associated ``closure``): |
| 857 |
|
| 858 |
It should return a new reference on success or ``NULL`` with a set exception |
| 859 |
on failure. |
| 860 |
|
| 861 |
.. c:type:: int (*setter)(PyObject *, PyObject *, void *) |
| 862 |
|
| 863 |
``set`` functions take two :c:expr:`PyObject*` parameters (the instance and |
| 864 |
the value to be set) and a user data pointer (the associated ``closure``): |
| 865 |
|
| 866 |
In case the attribute should be deleted the second parameter is ``NULL``. |
| 867 |
Should return ``0`` on success or ``-1`` with a set exception on failure. |