This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# Загальні структури об’єктів

Існує велика кількість структур, які використовуються для визначення типів об’єктів для Python. У цьому розділі описано ці структури та як вони використовуються.

## Базові типи об’єктів і макроси

All Python objects ultimately share a small number of fields at the beginning of the object’s representation in memory. These are represented by the `PyObject` and `PyVarObject` types, which are defined, in turn, by the expansions of some macros also used, whether directly or indirectly, in the definition of all other Python objects.

`PyObject`

  All object types are extensions of this type. This is a type which contains the information Python needs to treat a pointer to an object as an object. In a normal «release» build, it contains only the object’s reference count and a pointer to the corresponding type object. Nothing is actually declared to be a `PyObject`, but every pointer to a Python object can be cast to a `PyObject*`. Access to the members must be done by using the macros `Py_REFCNT` and `Py_TYPE`.

`PyVarObject`

  This is an extension of `PyObject` that adds the `ob_size` field. This is only used for objects that have some notion of length. This type does not often appear in the Python/C API. Access to the members must be done by using the macros `Py_REFCNT`, `Py_TYPE`, and `Py_SIZE`.

`PyObject_HEAD`

  Це макрос, який використовується під час оголошення нових типів, які представляють об’єкти без змінної довжини. Макрос PyObject_HEAD розширюється до:

      PyObject ob_base;

  Перегляньте документацію `PyObject` вище.

`PyObject_VAR_HEAD`

  Це макрос, який використовується під час оголошення нових типів, які представляють об’єкти з довжиною, що змінюється від екземпляра до екземпляра. Макрос PyObject_VAR_HEAD розширюється до:

      PyVarObject ob_base;

  Перегляньте документацію `PyVarObject` вище.

`Py_TYPE`(o)

  This macro is used to access the `ob_type` member of a Python object. It expands to:

      (((PyObject*)(o))->ob_type)

int `Py_IS_TYPE`(PyObject *o, PyTypeObject *type)

  Повертає ненульове значення, якщо тип об’єкта o є type. Інакше поверніть нуль. Еквівалент: `Py_TYPE(o) == type`.

  Нове в версії 3.9.

void `Py_SET_TYPE`(PyObject *o, PyTypeObject *type)

  Встановіть тип об’єкта o на type.

  Нове в версії 3.9.

`Py_REFCNT`(o)

  This macro is used to access the `ob_refcnt` member of a Python object. It expands to:

      (((PyObject*)(o))->ob_refcnt)

void `Py_SET_REFCNT`(PyObject *o, Py_ssize_t refcnt)

  Set the object o reference counter to refcnt.

  Нове в версії 3.9.

`Py_SIZE`(o)

  This macro is used to access the `ob_size` member of a Python object. It expands to:

      (((PyVarObject*)(o))->ob_size)

void `Py_SET_SIZE`(PyVarObject *o, Py_ssize_t size)

  Встановіть розмір об’єкта o на size.

  Нове в версії 3.9.

`PyObject_HEAD_INIT`(type)

  Це макрос, який розширюється до значень ініціалізації для нового типу `PyObject`. Цей макрос розширюється до:

      _PyObject_EXTRA_INIT
      1, type,

`PyVarObject_HEAD_INIT`(type, size)

  This is a macro which expands to initialization values for a new `PyVarObject` type, including the `ob_size` field. This macro expands to:

      _PyObject_EXTRA_INIT
      1, type, size,

## Реалізація функцій і методів

`PyCFunction`

  Type of the functions used to implement most Python callables in C. Functions of this type take two `PyObject*` parameters and return one such value. If the return value is `NULL`, an exception shall have been set. If not `NULL`, the return value is interpreted as the return value of the function as exposed in Python. The function must return a new reference.

  Сигнатура функції:

      PyObject *PyCFunction(PyObject *self,
                            PyObject *args);

`PyCFunctionWithKeywords`

  Type of the functions used to implement Python callables in C with signature `METH_VARARGS | METH_KEYWORDS`. The function signature is:

      PyObject *PyCFunctionWithKeywords(PyObject *self,
                                        PyObject *args,
                                        PyObject *kwargs);

`_PyCFunctionFast`

  Type of the functions used to implement Python callables in C with signature `METH_FASTCALL`. The function signature is:

      PyObject *_PyCFunctionFast(PyObject *self,
                                 PyObject *const *args,
                                 Py_ssize_t nargs);

`_PyCFunctionFastWithKeywords`

  Type of the functions used to implement Python callables in C with signature `METH_FASTCALL | METH_KEYWORDS`. The function signature is:

      PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                             PyObject *const *args,
                                             Py_ssize_t nargs,
                                             PyObject *kwnames);

`PyCMethod`

  Type of the functions used to implement Python callables in C with signature `METH_METHOD | METH_FASTCALL | METH_KEYWORDS`. The function signature is:

      PyObject *PyCMethod(PyObject *self,
                          PyTypeObject *defining_class,
                          PyObject *const *args,
                          Py_ssize_t nargs,
                          PyObject *kwnames)

  Нове в версії 3.9.

`PyMethodDef`

  Структура, що використовується для опису методу типу розширення. Ця структура має чотири поля:

  Field | C Type | Meaning
  --- | --- | ---
  `ml_name` | const char * | name of the method
  `ml_meth` | PyCFunction | pointer to the C implementation
  `ml_flags` | int | flag bits indicating how the call should be constructed
  `ml_doc` | const char * | points to the contents of the docstring

The `ml_meth` is a C function pointer. The functions may be of different types, but they always return `PyObject*`. If the function is not of the `PyCFunction`, the compiler will require a cast in the method table. Even though `PyCFunction` defines the first parameter as `PyObject*`, it is common that the method implementation uses the specific C type of the self object.

The `ml_flags` field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention.

Існують такі умови виклику:

`METH_VARARGS`

  This is the typical calling convention, where the methods have the type `PyCFunction`. The function expects two `PyObject*` values. The first one is the self object for methods; for module functions, it is the module object. The second parameter (often called args) is a tuple object representing all arguments. This parameter is typically processed using `PyArg_ParseTuple()` or `PyArg_UnpackTuple()`.

`METH_VARARGS | METH_KEYWORDS`

  Методи з цими прапорцями мають бути типу `PyCFunctionWithKeywords`. Функція очікує три параметри: self, args, kwargs, де kwargs є словником усіх аргументів ключового слова або, можливо, `NULL`, якщо аргументів ключового слова немає. Параметри зазвичай обробляються за допомогою `PyArg_ParseTupleAndKeywords()`.

`METH_FASTCALL`

  Fast calling convention supporting only positional arguments. The methods have the type `_PyCFunctionFast`. The first parameter is self, the second parameter is a C array of `PyObject*` values indicating the arguments and the third parameter is the number of arguments (the length of the array).

  This is not part of the limited API.

  Нове в версії 3.7.

`METH_FASTCALL | METH_KEYWORDS`

  Extension of `METH_FASTCALL` supporting also keyword arguments, with methods of type `_PyCFunctionFastWithKeywords`. Keyword arguments are passed the same way as in the vectorcall protocol: there is an additional fourth `PyObject*` parameter which is a tuple representing the names of the keyword arguments (which are guaranteed to be strings) or possibly `NULL` if there are no keywords. The values of the keyword arguments are stored in the args array, after the positional arguments.

  This is not part of the limited API.

  Нове в версії 3.7.

`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`

  Extension of `METH_FASTCALL | METH_KEYWORDS` supporting the defining class, that is, the class that contains the method in question. The defining class might be a superclass of `Py_TYPE(self)`.

  Метод має мати тип `PyCMethod`, такий самий, як і для `METH_FASTCALL | METH_KEYWORDS` з аргументом `defining_class`, доданим після `self`.

  Нове в версії 3.9.

`METH_NOARGS`

  Methods without parameters don’t need to check whether arguments are given if they are listed with the `METH_NOARGS` flag. They need to be of type `PyCFunction`. The first parameter is typically named self and will hold a reference to the module or object instance. In all cases the second parameter will be `NULL`.

`METH_O`

  Methods with a single object argument can be listed with the `METH_O` flag, instead of invoking `PyArg_ParseTuple()` with a `"O"` argument. They have the type `PyCFunction`, with the self parameter, and a `PyObject*` parameter representing the single argument.

Ці дві константи не використовуються для вказівки умов виклику, а для прив’язки під час використання з методами класів. Їх не можна використовувати для функцій, визначених для модулів. Щонайбільше один із цих прапорів може бути встановлений для будь-якого методу.

`METH_CLASS`

  Методу буде передано об’єкт типу як перший параметр, а не екземпляр типу. Це використовується для створення методів класу, подібних до того, що створюється під час використання вбудованої функції `classmethod()`.

`METH_STATIC`

  Методу буде передано `NULL` як перший параметр, а не екземпляр типу. Це використовується для створення статичних методів, подібних до того, що створюється під час використання вбудованої функції `staticmethod()`.

Ще одна константа контролює, чи завантажується метод замість іншого визначення з таким же ім’ям методу.

`METH_COEXIST`

  The method will be loaded in place of existing definitions. Without METH_COEXIST, the default is to skip repeated definitions. Since slot wrappers are loaded before the method table, the existence of a sq_contains slot, for example, would generate a wrapped method named `__contains__()` and preclude the loading of a corresponding PyCFunction with the same name. With the flag defined, the PyCFunction will be loaded in place of the wrapper object and will co-exist with the slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls.

## Доступ до атрибутів типів розширень

`PyMemberDef`

  Structure which describes an attribute of a type which corresponds to a C struct member. Its fields are:

  Field | C Type | Meaning
  --- | --- | ---
  `name` | const char * | name of the member
  `type` | int | the type of the member in the C struct
  `offset` | Py_ssize_t | the offset in bytes that the member is located on the type’s object struct
  `flags` | int | flag bits indicating if the field should be read-only or writable
  `doc` | const char * | points to the contents of the docstring

  `type` can be one of many `T_` macros corresponding to various C types. When the member is accessed in Python, it will be converted to the equivalent Python type.

  Назва макросу | тип С
  --- | ---
  T_SHORT | short
  T_INT | int
  T_LONG | long
  T_FLOAT | float
  T_DOUBLE | double
  T_STRING | const char *
  T_OBJECT | PyObject *
  T_OBJECT_EX | PyObject *
  T_CHAR | char
  T_BYTE | char
  T_UBYTE | unsigned char
  T_UINT | unsigned int
  T_USHORT | unsigned short
  T_ULONG | unsigned long
  T_BOOL | char
  T_LONGLONG | long long
  T_ULONGLONG | unsigned long long
  T_PYSSIZET | Py_ssize_t

  `T_OBJECT` and `T_OBJECT_EX` differ in that `T_OBJECT` returns `None` if the member is `NULL` and `T_OBJECT_EX` raises an `AttributeError`. Try to use `T_OBJECT_EX` over `T_OBJECT` because `T_OBJECT_EX` handles use of the `del` statement on that attribute more correctly than `T_OBJECT`.

  `flags` can be `0` for write and read access or `READONLY` for read-only access. Using `T_STRING` for `type` implies `READONLY`. `T_STRING` data is interpreted as UTF-8. Only `T_OBJECT` and `T_OBJECT_EX` members can be deleted. (They are set to `NULL`).

  Heap allocated types (created using `PyType_FromSpec()` or similar), `PyMemberDef` may contain definitions for the special members `__dictoffset__`, `__weaklistoffset__` and `__vectorcalloffset__`, corresponding to `tp_dictoffset`, `tp_weaklistoffset` and `tp_vectorcall_offset` in type objects. These must be defined with `T_PYSSIZET` and `READONLY`, for example:

      static PyMemberDef spam_type_members[] = {
          {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
          {NULL}  /* Sentinel */
      };

PyObject* `PyMember_GetOne`(const char *obj_addr, struct PyMemberDef *m)

  Отримати атрибут, що належить об’єкту за адресою obj_addr. Атрибут описується `PyMemberDef` m. Повертає `NULL` у разі помилки.

int `PyMember_SetOne`(char *obj_addr, struct PyMemberDef *m, PyObject *o)

  Установіть атрибут, що належить об’єкту за адресою obj_addr, на об’єкт o. Атрибут, який потрібно встановити, описується `PyMemberDef` m. Повертає `0` у разі успіху та від’ємне значення у випадку невдачі.

`PyGetSetDef`

  Структура для визначення доступу типу властивості. Дивіться також опис слота `PyTypeObject.tp_getset`.

  Field | C Type | Meaning
  --- | --- | ---
  name | const char * | назва атрибута
  get | getter | C function to get the attribute
  set | setter | optional C function to set or delete the attribute, if omitted the attribute is readonly
  doc | const char * | додатковий рядок документації
  closure | void * | optional function pointer, providing additional data for getter and setter

  The `get` function takes one `PyObject*` parameter (the instance) and a function pointer (the associated `closure`):

      typedef PyObject *(*getter)(PyObject *, void *);

  Він повинен повертати нове посилання в разі успіху або `NULL` із встановленим винятком у випадку невдачі.

  `set` functions take two `PyObject*` parameters (the instance and the value to be set) and a function pointer (the associated `closure`):

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

  У випадку, якщо атрибут потрібно видалити, другим параметром є `NULL`. Має повертати `0` у разі успіху або `-1` із встановленим винятком у випадку невдачі.