1. Расширение Python с помощью C или C++¶Extending Python with C or C++

1.1. Простой пример¶A Simple Example

Давайте создадим модуль расширения с именем spam (любимая еда фанатов Монти Питона…) и предположим, что мы хотим создать интерфейс Python для функции C библиотеки system() 1. Эта функция принимает в качестве аргумента строку, завершающуюся нулевым символом, и возвращает целое число. Мы хотим, чтобы эту функцию можно было вызывать из Python следующим образом:

>>> import spam
>>> status = spam.system("ls -l")

Начните с создания файла spammodule.c. (Исторически сложилось, что если модуль называется spam, то C-файл, содержащий его реализацию, называется spammodule.c; если имя модуля очень длинное, например spammify, то имя модуля может быть просто spammify.c.)

Первые две строки нашего файла могут быть:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

которые подключают Python API (при желании можно добавить комментарий, описывающий назначение модуля, и уведомление об авторских правах).

Все видимые пользователю символы, определённые Python.h, имеют префикс Py или PY, за исключением определённых в стандартных заголовочных файлах. Для удобства, а также поскольку они широко используются интерпретатором Python, "Python.h" включает несколько стандартных заголовочных файлов: <stdio.h>, <string.h>, <errno.h> и <stdlib.h>. Если последнего заголовочного файла нет в вашей системе, в нём напрямую объявляются функции malloc(), free() и realloc().

Следующее, что мы добавим в наш файл модуля, – это C-функция, которая будет вызываться при вычислении выражения Python spam.system(string) (чуть позже мы увидим, как именно она в итоге вызывается):

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    return PyLong_FromLong(sts);
}

Существует прямой способ отображения списка аргументов в Python (например, одиночного выражения "ls -l") на аргументы, передаваемые C-функции. C-функция всегда имеет два аргумента, традиционно называемых self и args.

Аргумент self указывает на объект модуля для функций уровня модуля; для метода он указывал бы на экземпляр объекта.

Аргумент args будет указателем на кортеж Python, содержащий аргументы. Каждый элемент кортежа соответствует одному аргументу из списка аргументов вызова. Аргументы – это объекты Python; чтобы выполнить с ними какие-либо действия в нашей C-функции, их необходимо преобразовать в значения C. Функция PyArg_ParseTuple() из Python API проверяет типы аргументов и преобразует их в значения C. Она использует строку формата для определения требуемых типов аргументов, а также типов переменных C, в которые будут сохранены преобразованные значения. Подробнее об этом позже.

PyArg_ParseTuple() возвращает истину (ненулевое значение), если все аргументы имеют правильный тип и их компоненты сохранены в переменные, адреса которых переданы. Она возвращает ложь (ноль), если передан недопустимый список аргументов. В последнем случае она также возбуждает соответствующее исключение, чтобы вызывающая функция могла немедленно вернуть NULL (как мы видели в примере).

1.2. Интермеццо: ошибки и исключения¶Intermezzo: Errors and Exceptions

Важное соглашение во всём интерпретаторе Python заключается в следующем: когда функция завершается ошибкой, она должна установить условие исключения и вернуть значение ошибки (обычно -1 или указатель NULL). Информация об исключении хранится в трёх элементах состояния потока интерпретатора. Если исключения нет, они равны NULL. В противном случае они являются C-эквивалентами элементов кортежа Python, возвращаемого функцией sys.exc_info(). Это тип исключения, экземпляр исключения и объект traceback. Важно знать о них, чтобы понимать, как передаются ошибки.

Python API определяет ряд функций для установки различных типов исключений.

Самая распространённая из них – PyErr_SetString(). Её аргументы – объект исключения и C-строка. Объект исключения обычно является предопределённым объектом, таким как PyExc_ZeroDivisionError. C-строка указывает причину ошибки и преобразуется в строковый объект Python, который сохраняется как «связанное значение» исключения.

Другая полезная функция – PyErr_SetFromErrno(), которая принимает только аргумент-исключение и формирует связанное значение, проверяя глобальную переменную errno. Самая общая функция – PyErr_SetObject(), принимающая два объектных аргумента: исключение и его связанное значение. Не требуется Py_INCREF() объекты, переданные любой из этих функций.

Можно неразрушающе проверить, было ли установлено исключение, с помощью PyErr_Occurred(). Она возвращает текущий объект исключения или NULL, если исключения не возникло. Обычно не нужно вызывать PyErr_Occurred(), чтобы узнать, произошла ли ошибка при вызове функции, так как об этом можно судить по возвращаемому значению.

Когда функция f, вызывающая другую функцию g, обнаруживает, что последняя завершилась ошибкой, f сама должна вернуть значение ошибки (обычно NULL или -1). Она не должна вызывать одну из функций PyErr_* – одна уже была вызвана функцией g. Вызывающий код f затем также должен вернуть индикацию ошибки своему своему вызывающему, опять же без вызова PyErr_*, и так далее – наиболее подробная причина ошибки уже была сообщена функцией, которая первой её обнаружила. Как только ошибка достигает главного цикла интерпретатора Python, это прерывает выполняемый код Python и пытается найти обработчик исключения, указанный программистом на Python.

(Бывают ситуации, когда модуль может дать более подробное сообщение об ошибке, вызвав другую функцию PyErr_*, и в таких случаях это допустимо. Однако, как правило, это не обязательно и может привести к потере информации о причине ошибки: большинство операций могут завершиться ошибкой по разным причинам.)

Чтобы проигнорировать исключение, установленное неудачным вызовом функции, условие исключения должно быть явно очищено вызовом PyErr_Clear(). Единственный случай, когда C-код должен вызывать PyErr_Clear(), – это если он не хочет передавать ошибку интерпретатору, а хочет полностью обработать её самостоятельно (возможно, попробовав что-то другое или сделав вид, что ничего не произошло).

Каждый неудачный вызов malloc() должен быть преобразован в исключение – непосредственный вызывающий код malloc() (или realloc()) должен вызвать PyErr_NoMemory() и сам вернуть индикатор ошибки. Все функции, создающие объекты (например, PyLong_FromLong()), уже делают это, поэтому данное замечание относится только к тем, кто вызывает malloc() напрямую.

Также обратите внимание, что, за важным исключением PyArg_ParseTuple() и подобных, функции, возвращающие целочисленный статус, обычно возвращают положительное значение или ноль в случае успеха и -1 в случае ошибки, как системные вызовы Unix.

Наконец, следует позаботиться об очистке мусора (вызвав Py_XDECREF() или Py_DECREF() для уже созданных объектов) при возврате индикатора ошибки.

Выбор, какое исключение возбуждать, полностью за вами. Существуют предварительно объявленные C-объекты, соответствующие всем встроенным исключениям Python, например PyExc_ZeroDivisionError, которые можно использовать напрямую. Конечно, следует выбирать исключения разумно – не стоит использовать PyExc_TypeError для обозначения того, что файл не удалось открыть (для этого вероятно следует использовать PyExc_IOError). Если что-то не так со списком аргументов, функция PyArg_ParseTuple() обычно возбуждает PyExc_TypeError. Если значение аргумента должно находиться в определённом диапазоне или удовлетворять другим условиям, подходит PyExc_ValueError.

Можно также определить новое исключение, уникальное для вашего модуля. Для этого обычно объявляется статическая объектная переменная в начале файла:

static PyObject *SpamError;

и инициализировать её в функции инициализации модуля (PyInit_spam()) объектом исключения:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_XINCREF(SpamError);
    if (PyModule_AddObject(m, "error", SpamError) < 0) {
        Py_XDECREF(SpamError);
        Py_CLEAR(SpamError);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Обратите внимание, что имя исключения в Python – spam.error. Функция PyErr_NewException() может создать класс с базовым классом Exception (если только не передан другой класс вместо NULL), описанный в Встроенные исключения.

Также обратите внимание, что переменная SpamError сохраняет ссылку на вновь созданный класс исключения; это сделано намеренно! Поскольку исключение может быть удалено из модуля внешним кодом, необходима собственная ссылка на класс, чтобы гарантировать, что он не будет отброшен, что приведёт к превращению SpamError в висячий указатель. Если он станет висячим указателем, C-код, возбуждающий исключение, может вызвать аварийный дамп или другие непреднамеренные побочные эффекты.

Использование PyMODINIT_FUNC в качестве возвращаемого типа функции обсуждается далее в этом примере.

Исключение spam.error может быть возбуждено в вашем модуле расширения с помощью вызова PyErr_SetString(), как показано ниже:

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = system(command);
    if (sts < 0) {
        PyErr_SetString(SpamError, "System command failed");
        return NULL;
    }
    return PyLong_FromLong(sts);
}

1.3. Возвращаясь к примеру¶Back to the Example

Вернёмся к нашей функции-примеру. Теперь вы должны понимать этот оператор:

if (!PyArg_ParseTuple(args, "s", &command))
    return NULL;

Она возвращает NULL (индикатор ошибки для функций, возвращающих указатели на объекты), если в списке аргументов обнаружена ошибка, полагаясь на исключение, установленное PyArg_ParseTuple(). В противном случае строковое значение аргумента копируется в локальную переменную command. Это присваивание указателя, и строка, на которую он указывает, не должна изменяться (поэтому в стандартном C переменная command должна быть объявлена как const char *command).

Следующий оператор – это вызов функции Unix system() с передачей строки, полученной от PyArg_ParseTuple():

sts = system(command);

Наша функция spam.system() должна вернуть значение sts как объект Python. Это делается с помощью функции PyLong_FromLong().

return PyLong_FromLong(sts);

В данном случае она вернёт целочисленный объект. (Да, даже целые числа в Python – это объекты в куче!)

Если у вас есть C-функция, которая не возвращает полезного аргумента (функция, возвращающая void), соответствующая функция Python должна возвращать None. Для этого требуется такая идиома (она реализована макросом Py_RETURN_NONE):

Py_INCREF(Py_None);
return Py_None;

Py_None – это имя в C для специального объекта Python None. Это настоящий объект Python, а не указатель NULL, который в большинстве контекстов означает «ошибку», как мы уже видели.

1.4. Таблица методов модуля и функция инициализации¶The Module’s Method Table and Initialization Function

Я обещал показать, как spam_system() вызывается из программ Python. Сначала нужно перечислить её имя и адрес в «таблице методов»:

static PyMethodDef SpamMethods[] = {
    ...
    {"system",  spam_system, METH_VARARGS,
     "Execute a shell command."},
    ...
    {NULL, NULL, 0, NULL}        /* Страж */
};

Обратите внимание на третью запись (METH_VARARGS). Это флаг, сообщающий интерпретатору соглашение о вызове для C-функции. Обычно он должен быть METH_VARARGS или METH_VARARGS | METH_KEYWORDS; значение 0 означает, что используется устаревший вариант PyArg_ParseTuple().

При использовании только METH_VARARGS функция должна ожидать, что параметры уровня Python будут переданы в виде кортежа, пригодного для разбора через PyArg_ParseTuple(); подробнее об этой функции сказано ниже.

Флаг METH_KEYWORDS может быть установлен в третьем поле, если функции должны передаваться ключевые аргументы. В этом случае C-функция должна принимать третий параметр PyObject * – словарь ключевых слов. Для разбора аргументов такой функции используйте PyArg_ParseTupleAndKeywords().

Таблица методов должна быть указана в структуре определения модуля:

static struct PyModuleDef spammodule = {
    PyModuleDef_HEAD_INIT,
    "spam",   /* имя модуля */
    spam_doc, /* документация модуля, может быть NULL */
    -1,       /* размер состояния модуля для каждого интерпретатора,
                 или -1, если модуль хранит состояние в глобальных переменных. */
    SpamMethods
};

Эта структура, в свою очередь, должна быть передана интерпретатору в функции инициализации модуля. Функция инициализации должна называться PyInit_name(), где name – имя модуля, и должна быть единственным не-static элементом, определённым в файле модуля:

PyMODINIT_FUNC
PyInit_spam(void)
{
    return PyModule_Create(&spammodule);
}

Обратите внимание, что PyMODINIT_FUNC объявляет функцию с типом возвращаемого значения PyObject *, объявляет все необходимые для платформы специальные объявления компоновки, а для C++ объявляет функцию как extern "C".

Когда программа Python впервые импортирует модуль spam, вызывается PyInit_spam(). (См. ниже комментарии о встраивании Python.) Она вызывает PyModule_Create(), которая возвращает объект модуля, и вставляет объекты встроенных функций в только что созданный модуль на основе таблицы (массива структур PyMethodDef), находящейся в определении модуля. PyModule_Create() возвращает указатель на объект модуля, который она создаёт. При некоторых ошибках она может завершиться фатальной ошибкой или вернуть NULL, если модуль не удалось инициализировать удовлетворительно. Функция инициализации должна вернуть объект модуля своему вызывающему, чтобы затем он был вставлен в sys.modules.

При встраивании Python функция PyInit_spam() не вызывается автоматически, если только в таблице PyImport_Inittab нет соответствующей записи. Чтобы добавить модуль в таблицу инициализации, используйте PyImport_AppendInittab(), за которым опционально следует импорт модуля:

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }

    /* Добавить встроенный модуль перед Py_Initialize */
    if (PyImport_AppendInittab("spam", PyInit_spam) == -1) {
        fprintf(stderr, "Error: could not extend in-built modules table\n");
        exit(1);
    }

    /* Передать argv[0] интерпретатору Python */
    Py_SetProgramName(program);

    /* Инициализировать интерпретатор Python. Обязательно.
       Если этот шаг завершится неудачей, произойдет фатальная ошибка. */
    Py_Initialize();

    /* Опционально импортировать модуль; в качестве альтернативы,
       импорт может быть отложен до тех пор, пока встроенный скрипт
       не импортирует его. */
    PyObject *pmodule = PyImport_ImportModule("spam");
    if (!pmodule) {
        PyErr_Print();
        fprintf(stderr, "Error: could not import module 'spam'\n");
    }

    ...

    PyMem_RawFree(program);
    return 0;
}

Более объёмный пример модуля включён в дистрибутив исходных текстов Python как Modules/xxmodule.c. Этот файл можно использовать как шаблон или просто прочитать как пример.

1.5. Компиляция и компоновка¶Compilation and Linkage

Перед использованием нового расширения необходимо сделать ещё две вещи: скомпилировать и скомпоновать его с системой Python. Если используется динамическая загрузка, детали могут зависеть от стиля динамической загрузки, применяемого в вашей системе; см. главы о сборке модулей расширения (глава Сборка расширений на C и C++) и дополнительную информацию, относящуюся только к сборке в Windows (глава Сборка расширений на C и C++ в Windows) для получения более подробных сведений.

Если динамическая загрузка недоступна или вы хотите сделать модуль постоянной частью интерпретатора Python, придётся изменить конфигурацию и пересобрать интерпретатор. К счастью, в Unix это очень просто: поместите ваш файл (например, spammodule.c) в каталог Modules/ распакованного дистрибутива исходных кодов, добавьте строку в файл Modules/Setup.local, описывающую ваш файл:

spam spammodule.o

и пересобрать интерпретатор, выполнив make в корневом каталоге. Также можно выполнить make в подкаталоге Modules/, но тогда сначала нужно пересобрать Makefile там, выполнив 'make Makefile'. (Это необходимо каждый раз при изменении файла Setup.)

Если ваш модуль требует дополнительных библиотек для компоновки, их также можно перечислить в строке конфигурационного файла, например:

spam spammodule.o -lX11

1.6. Вызов функций Python из C¶Calling Python Functions from C

До сих пор мы сосредотачивались на том, как сделать C-функции вызываемыми из Python. Обратное также полезно: вызов функций Python из C. Это особенно актуально для библиотек, поддерживающих так называемые «колбэки». Если C-интерфейс использует колбэки, то эквивалентный Python часто должен предоставить механизм колбэков программисту на Python; реализация потребует вызова функций Python-колбэков из C-колбэка. Можно представить и другие варианты использования.

К счастью, интерпретатор Python легко вызывается рекурсивно, и существует стандартный интерфейс для вызова функции Python. (Я не буду останавливаться на том, как вызвать анализатор Python с определённой строкой на входе – если вам интересно, взгляните на реализацию опции командной строки -c в Modules/main.c из исходного кода Python.)

Вызвать функцию Python легко. Во-первых, программа на Python должна каким-то образом передать вам объект функции Python. Вы должны предоставить функцию (или какой-то другой интерфейс) для этого. Когда эта функция вызывается, сохраните указатель на объект функции Python (не забудьте Py_INCREF() её!) в глобальной переменной – или где сочтёте нужным. Например, следующая функция может быть частью определения модуля:

static PyObject *my_callback = NULL;

static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
{
    PyObject *result = NULL;
    PyObject *temp;

    if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
        if (!PyCallable_Check(temp)) {
            PyErr_SetString(PyExc_TypeError, "parameter must be callable");
            return NULL;
        }
        Py_XINCREF(temp);         /* Добавить ссылку на новый колбэк */
        Py_XDECREF(my_callback);  /* Освободить предыдущий колбэк */
        my_callback = temp;       /* Запомнить новый колбэк */
        /* Шаблон для возврата None */
        Py_INCREF(Py_None);
        result = Py_None;
    }
    return result;
}

Эта функция должна быть зарегистрирована в интерпретаторе с помощью флага METH_VARARGS; это описано в разделе Таблица методов модуля и функция инициализации. Функция PyArg_ParseTuple() и её аргументы описаны в разделе Извлечение параметров в функциях расширения.

Макросы Py_XINCREF() и Py_XDECREF() увеличивают/уменьшают счётчик ссылок объекта и безопасны при наличии указателей NULL (но обратите внимание, что temp не будет NULL в этом контексте). Подробнее о них в разделе Счётчики ссылок.

Позже, когда придёт время вызвать функцию, вы вызываете C-функцию PyObject_CallObject(). Эта функция имеет два аргумента, оба указатели на произвольные объекты Python: функцию Python и список аргументов. Список аргументов всегда должен быть объектом кортежа, длина которого равна количеству аргументов. Для вызова функции Python без аргументов передайте NULL или пустой кортеж; для вызова с одним аргументом передайте кортеж из одного элемента. Py_BuildValue() возвращает кортеж, если строка формата состоит из нуля или более кодов формата в скобках. Например:

int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Вызов колбэка */
arglist = Py_BuildValue("(i)", arg);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);

PyObject_CallObject() возвращает указатель на объект Python: это возвращаемое значение функции Python. PyObject_CallObject() нейтрален по отношению к счётчику ссылок своих аргументов. В примере был создан новый кортеж для использования в качестве списка аргументов, который Py_DECREF()-ится сразу после вызова PyObject_CallObject().

Возвращаемое значение PyObject_CallObject() является «новым»: это либо совершенно новый объект, либо существующий объект, чей счётчик ссылок был увеличен. Поэтому, если вы не хотите сохранять его в глобальной переменной, вы должны каким-то образом Py_DECREF() результат, даже (особенно!) если вас не интересует его значение.

Однако перед этим важно проверить, что возвращаемое значение не равно NULL. Если это так, функция Python завершилась возбуждением исключения. Если C-код, вызвавший PyObject_CallObject(), был вызван из Python, он должен вернуть индикатор ошибки своему вызывающему коду на Python, чтобы интерпретатор мог вывести трассировку стека, или вызывающий код на Python мог обработать исключение. Если это невозможно или нежелательно, исключение следует очистить вызовом PyErr_Clear(). Например:

if (result == NULL)
    return NULL; /* Передать ошибку обратно */
...use result...
Py_DECREF(result);

В зависимости от желаемого интерфейса к Python-функции обратного вызова, вам также может потребоваться предоставить список аргументов для PyObject_CallObject(). В некоторых случаях список аргументов также предоставляется программой на Python через тот же интерфейс, который задал функцию обратного вызова. Затем его можно сохранить и использовать так же, как объект функции. В других случаях вам может потребоваться создать новый кортеж для передачи в качестве списка аргументов. Самый простой способ сделать это – вызвать Py_BuildValue(). Например, если вы хотите передать целочисленный код события, можно использовать следующий код:

PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
    return NULL; /* Передать ошибку обратно */
/* Здесь, возможно, используется результат */
Py_DECREF(result);

Обратите внимание на размещение Py_DECREF(arglist) сразу после вызова, перед проверкой ошибки! Также обратите внимание, что строго говоря, этот код не полон: Py_BuildValue() может исчерпать память, и это должно быть проверено.

Вы также можете вызвать функцию с именованными аргументами, используя PyObject_Call(), который поддерживает аргументы и именованные аргументы. Как в примере выше, мы используем Py_BuildValue() для создания словаря.

PyObject *dict;
...
dict = Py_BuildValue("{s:i}", "name", val);
result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict);
if (result == NULL)
    return NULL; /* Передать ошибку обратно */
/* Здесь, возможно, используется результат */
Py_DECREF(result);

1.7. Извлечение параметров в функциях расширения¶Extracting Parameters in Extension Functions

Функция PyArg_ParseTuple() объявляется следующим образом:

int PyArg_ParseTuple(PyObject *arg, const char *format, ...);

Аргумент arg должен быть объектом кортежа, содержащим список аргументов, переданных из Python в C-функцию. Аргумент format должен быть строкой формата, чей синтаксис описан в разделе Разбор аргументов и построение значений справочного руководства Python/C API. Остальные аргументы должны быть адресами переменных, чей тип определяется строкой формата.

Обратите внимание, что хотя PyArg_ParseTuple() проверяет, что аргументы Python имеют требуемые типы, он не может проверить корректность адресов C-переменных, переданных в вызов: если там допущены ошибки, код, вероятно, аварийно завершится или, по крайней мере, перезапишет случайные биты в памяти. Поэтому следует быть осторожным!

Обратите внимание, что любые ссылки на объекты Python, передаваемые вызывающему, являются заимствованными ссылками; уменьшать их счётчик ссылок не следует.

Несколько примеров вызовов:

#define PY_SSIZE_T_CLEAN  /* Сделать так, чтобы "s#" использовало Py_ssize_t, а не int. */
#include <Python.h>

int ok;
int i, j;
long k, l;
const char *s;
Py_ssize_t size;

ok = PyArg_ParseTuple(args, ""); /* Без аргументов */
    /* Вызов Python: f() */

ok = PyArg_ParseTuple(args, "s", &s); /* Строка */
    /* Возможный вызов Python: f('whoops!') */

ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Два длинных целых и строка */
    /* Возможный вызов Python: f(1, 2, 'three') */

ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
    /* Пара int и строка, размер которой также возвращается */
    /* Возможный вызов Python: f((1, 2), 'three') */

{
    const char *file;
    const char *mode = "r";
    int bufsize = 0;
    ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
    /* Строка и, опционально, ещё одна строка и целое число */
    /* Возможные вызовы Python:
       f('spam')
       f('spam', 'w')
       f('spam', 'wb', 100000) */
}

{
    int left, top, right, bottom, h, v;
    ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
             &left, &top, &right, &bottom, &h, &v);
    /* Прямоугольник и точка */
    /* Возможный вызов Python:
       f(((0, 0), (400, 300)), (10, 10)) */
}

{
    Py_complex c;
    ok = PyArg_ParseTuple(args, "D:myfunction", &c);
    /* комплексное число, также предоставляющее имя функции для сообщений об ошибках */
    /* Возможный вызов Python: myfunction(1+2j) */
}

1.8. Именованные параметры для функций расширения¶Keyword Parameters for Extension Functions

Функция PyArg_ParseTupleAndKeywords() объявляется следующим образом:

int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
                                const char *format, char *kwlist[], ...);

Параметры arg и format идентичны параметрам функции PyArg_ParseTuple(). Параметр kwdict – это словарь ключевых слов, полученный в качестве третьего параметра от среды выполнения Python. Параметр kwlist – это список строк, завершающийся NULL, который идентифицирует параметры; имена сопоставляются с информацией о типах из format слева направо. В случае успеха PyArg_ParseTupleAndKeywords() возвращает true, в противном случае возвращает false и возбуждает соответствующее исключение.

Вот пример модуля, использующего ключевые слова, основанный на примере Джеффа Филбрика (philbrick@hks.com):

#define PY_SSIZE_T_CLEAN  /* Сделать так, чтобы "s#" использовало Py_ssize_t, а не int. */
#include <Python.h>

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
    int voltage;
    const char *state = "a stiff";
    const char *action = "voom";
    const char *type = "Norwegian Blue";

    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
                                     &voltage, &state, &action, &type))
        return NULL;

    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_RETURN_NONE;
}

static PyMethodDef keywdarg_methods[] = {
    /* Приведение функции необходимо, поскольку значения PyCFunction
     * принимают только два параметра PyObject*, а keywdarg_parrot() принимает
     * три.
     */
    {"parrot", (PyCFunction)(void(*)(void))keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
     "Print a lovely skit to standard output."},
    {NULL, NULL, 0, NULL}   /* сторожевое значение */
};

static struct PyModuleDef keywdargmodule = {
    PyModuleDef_HEAD_INIT,
    "keywdarg",
    NULL,
    -1,
    keywdarg_methods
};

PyMODINIT_FUNC
PyInit_keywdarg(void)
{
    return PyModule_Create(&keywdargmodule);
}

1.9. Создание произвольных значений¶Building Arbitrary Values

Эта функция является аналогом PyArg_ParseTuple(). Она объявляется следующим образом:

PyObject *Py_BuildValue(const char *format, ...);

Она распознаёт набор форматных единиц, аналогичный распознаваемым PyArg_ParseTuple(), но аргументы (которые являются входными для функции, а не выходными) не должны быть указателями, только значениями. Она возвращает новый объект Python, подходящий для возврата из C-функции, вызванной из Python.

Одно отличие от PyArg_ParseTuple(): последняя требует, чтобы её первый аргумент был кортежем (поскольку списки аргументов Python внутренне всегда представлены как кортежи), тогда как Py_BuildValue() не всегда строит кортеж. Она строит кортеж, только если строка формата содержит две или более форматных единиц. Если строка формата пуста, она возвращает None; если она содержит ровно одну форматную единицу, она возвращает объект, описываемый этой единицей. Чтобы принудительно вернуть кортеж размера 0 или 1, строку формата следует заключить в скобки.

Примеры (слева вызов, справа результирующее значение Python):

Py_BuildValue("")                        None
Py_BuildValue("i", 123)                  123
Py_BuildValue("iii", 123, 456, 789)      (123, 456, 789)
Py_BuildValue("s", "hello")              'hello'
Py_BuildValue("y", "hello")              b'hello'
Py_BuildValue("ss", "hello", "world")    ('hello', 'world')
Py_BuildValue("s#", "hello", 4)          'hell'
Py_BuildValue("y#", "hello", 4)          b'hell'
Py_BuildValue("()")                      ()
Py_BuildValue("(i)", 123)                (123,)
Py_BuildValue("(ii)", 123, 456)          (123, 456)
Py_BuildValue("(i,i)", 123, 456)         (123, 456)
Py_BuildValue("[i,i]", 123, 456)         [123, 456]
Py_BuildValue("{s:i,s:i}",
              "abc", 123, "def", 456)    {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
              1, 2, 3, 4, 5, 6)          (((1, 2), (3, 4)), (5, 6))

1.10. Счётчики ссылок¶Reference Counts

В таких языках, как C или C++, программист отвечает за динамическое выделение и освобождение памяти в куче. В C это делается с помощью функций malloc() и free(). В C++ операторы new и delete используются с тем же смыслом; дальнейшее обсуждение ограничивается случаем C.

Каждый блок памяти, выделенный с помощью malloc(), в конечном итоге должен быть возвращён в пул доступной памяти ровно одним вызовом free(). Очень важно вызвать free() в нужный момент. Если адрес блока будет забыт, а free() для него не вызван, занимаемая им память не может быть использована повторно до завершения программы. Это называется утечкой памяти. С другой стороны, если программа вызывает free() для блока, а затем продолжает его использовать, это создаёт конфликт с повторным использованием блока через другой вызов malloc(). Это называется использованием освобождённой памяти. Это имеет такие же плохие последствия, как обращение к неинициализированным данным – дампы памяти, неверные результаты, загадочные сбои.

Распространённые причины утечек памяти – нестандартные пути выполнения кода. Например, функция может выделить блок памяти, выполнить некоторые вычисления, а затем снова освободить блок. Теперь изменение требований к функции может добавить в вычисление проверку, которая обнаруживает ошибочную ситуацию и может привести к преждевременному возврату из функции. Легко забыть освободить выделенный блок памяти при таком преждевременном выходе, особенно если он был добавлен в код позднее. Такие утечки, будучи однажды внесёнными, часто остаются незамеченными долгое время: ошибочный выход происходит лишь в небольшой доле всех вызовов, а на большинстве современных машин достаточно виртуальной памяти, поэтому утечка становится заметна только в долго работающем процессе, который часто использует функцию с утечкой. Следовательно, важно предотвращать утечки, используя соглашение о кодировании или стратегию, которая минимизирует такого рода ошибки.

Поскольку Python активно использует malloc() и free(), ему нужна стратегия для предотвращения как утечек памяти, так и использования освобождённой памяти. Выбранный метод называется подсчётом ссылок. Принцип прост: каждый объект содержит счётчик, который увеличивается, когда ссылка на объект сохраняется где-либо, и уменьшается, когда ссылка на него удаляется. Когда счётчик достигает нуля, последняя ссылка на объект удалена, и объект освобождается.

Альтернативная стратегия называется автоматической сборкой мусора. (Иногда подсчёт ссылок тоже называют стратегией сборки мусора, поэтому я использую слово «автоматическая», чтобы различать их.) Большое преимущество автоматической сборки мусора в том, что пользователю не нужно вызывать free() явно. (Другое заявляемое преимущество – улучшение скорости или использования памяти, однако это не факт.) Недостаток в том, что для C не существует по-настоящему переносимого автоматического сборщика мусора, в то время как подсчёт ссылок можно реализовать переносимо (при условии, что функции malloc() и free() доступны – что гарантирует стандарт C). Возможно, когда-нибудь для C появится достаточно переносимый автоматический сборщик мусора. До тех пор придётся мириться с подсчётом ссылок.

Хотя Python использует традиционную реализацию подсчёта ссылок, он также предлагает детектор циклов, который обнаруживает циклические ссылки. Это позволяет приложениям не беспокоиться о создании прямых или косвенных циклических ссылок; они являются слабым местом сборки мусора, реализованной только с помощью подсчёта ссылок. Циклические ссылки состоят из объектов, которые содержат (возможно, косвенные) ссылки на самих себя, так что каждый объект в цикле имеет ненулевой счётчик ссылок. Типичные реализации подсчёта ссылок не могут освободить память, принадлежащую объектам в циклической ссылке или на которые есть ссылки из объектов в цикле, даже если на сам цикл больше нет ссылок.

Детектор циклов способен обнаруживать мусорные циклы и может их освобождать. Модуль gc предоставляет способ запуска детектора (функция collect()), а также интерфейсы конфигурации и возможность отключения детектора во время выполнения.

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0); /* ОШИБКА! */
}

void
no_bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);

    Py_INCREF(item);
    PyList_SetItem(list, 1, PyLong_FromLong(0L));
    PyObject_Print(item, stdout, 0);
    Py_DECREF(item);
}

void
bug(PyObject *list)
{
    PyObject *item = PyList_GetItem(list, 0);
    Py_BEGIN_ALLOW_THREADS
    ...some blocking I/O call...
    Py_END_ALLOW_THREADS
    PyObject_Print(item, stdout, 0); /* ОШИБКА! */
}

1.11. Написание расширений на C++¶Writing Extensions in C++

Модули расширения можно писать на C++. Применяются некоторые ограничения. Если главная программа (интерпретатор Python) компилируется и компонуется C- компилятором, нельзя использовать глобальные или статические объекты с конструкторами. Это не проблема, если главная программа компонуется C++-компилятором. Функции, которые будут вызываться интерпретатором Python (в частности, функции инициализации модулей), должны быть объявлены с помощью extern "C". Нет необходимости заключать заголовочные файлы Python в extern "C" {...} – они уже используют эту форму, если определён символ __cplusplus (все современные C++-компиляторы определяют этот символ).

1.12. Предоставление C API для модуля расширения¶Providing a C API for an Extension Module

Многие модули расширения просто предоставляют новые функции и типы для использования из Python, но иногда код в модуле расширения может быть полезен для других модулей расширения. Например, модуль расширения может реализовать тип «коллекция», который работает как список без порядка. Подобно тому, как стандартный тип списка Python имеет C API, позволяющий модулям расширения создавать списки и управлять ими, этот новый тип коллекции должен иметь набор C-функций для прямого управления из других модулей расширения.

На первый взгляд задача кажется простой: достаточно написать функции (не объявляя их static, разумеется), предоставить соответствующий заголовочный файл и документировать C API. И действительно, это бы сработало, если бы все модули расширения всегда статически компоновались с интерпретатором Python. Однако, когда модули используются как разделяемые библиотеки, символы, определённые в одном модуле, могут быть не видны другому модулю. Детали видимости зависят от операционной системы; одни системы используют единое глобальное пространство имён для интерпретатора Python и всех модулей расширения (например, Windows), а другие требуют явного списка импортируемых символов на этапе компоновки модуля (например, AIX) или предлагают выбор разных стратегий (большинство Unix-систем). И даже если символы глобально видны, модуль, функции которого нужно вызвать, может быть ещё не загружен!

Поэтому для обеспечения переносимости не следует делать предположений о видимости символов. Это означает, что все символы в модулях расширения должны быть объявлены static, за исключением функции инициализации модуля, чтобы избежать конфликтов имён с другими модулями расширения (как обсуждается в разделе Таблица методов модуля и функция инициализации). И это также означает, что символы, которые должны быть доступны из других модулей расширения, должны экспортироваться иным способом.

Python предоставляет специальный механизм для передачи информации уровня C (указателей) из одного модуля расширения в другой: капсулы (Capsules). Капсула – это тип данных Python, который хранит указатель (void*). Капсулы можно создавать и использовать только через их C API, но их можно передавать как любой другой объект Python. В частности, их можно присвоить имени в пространстве имён модуля расширения. Другие модули расширения могут затем импортировать этот модуль, получить значение этого имени и затем извлечь указатель из капсулы.

Существует много способов использования Capsules для экспорта C API модуля расширения. Каждая функция может получить свой собственный Capsule, или все указатели C API могут храниться в массиве, адрес которого опубликован в Capsule. А различные задачи хранения и извлечения указателей могут быть распределены разными способами между модулем, предоставляющим код, и модулями-клиентами.

Какой бы метод вы ни выбрали, важно правильно называть свои капсулы. Функция PyCapsule_New() принимает параметр имени (const char*); разрешается передавать имя NULL, но мы настоятельно рекомендуем указывать имя. Правильно названные капсулы обеспечивают определённую степень типобезопасности во время выполнения; нет надёжного способа отличить одну безымянную капсулу от другой.

В частности, Capsules, используемые для предоставления C API, должны получать имена согласно следующему соглашению:

modulename.attributename

Удобная функция PyCapsule_Import() упрощает загрузку C API, предоставленного через Capsule, но только если имя Capsule соответствует этому соглашению. Такое поведение даёт пользователям C API высокую степень уверенности в том, что загруженный ими Capsule содержит правильный C API.

Следующий пример демонстрирует подход, который возлагает большую часть ответственности на разработчика экспортирующего модуля, что подходит для часто используемых модулей библиотеки. Он хранит все указатели C API (в примере только один!) в массиве указателей void, который становится значением капсулы. Заголовочный файл, соответствующий модулю, предоставляет макрос, который импортирует модуль и получает его указатели C API; клиентским модулям остаётся только вызвать этот макрос перед обращением к C API.

Экспортирующий модуль – это модификация модуля spam из раздела Простой пример. Функция spam.system() не вызывает напрямую функцию библиотеки C system(), а вызывает функцию PySpam_System(), которая в реальности, конечно, делала бы что-то более сложное (например, добавляла бы «spam» к каждой команде). Эта функция PySpam_System() также экспортируется в другие модули расширения.

Функция PySpam_System() – это обычная функция на C, объявленная static, как и всё остальное:

static int
PySpam_System(const char *command)
{
    return system(command);
}

Функция spam_system() тривиально модифицирована:

static PyObject *
spam_system(PyObject *self, PyObject *args)
{
    const char *command;
    int sts;

    if (!PyArg_ParseTuple(args, "s", &command))
        return NULL;
    sts = PySpam_System(command);
    return PyLong_FromLong(sts);
}

В начале модуля, сразу после строки

#include <Python.h>

необходимо добавить ещё две строки:

#define SPAM_MODULE
#include "spammodule.h"

#define используется, чтобы сообщить заголовочному файлу, что он включается в экспортирующий модуль, а не в клиентский модуль. Наконец, функция инициализации модуля должна позаботиться об инициализации массива указателей C API:

PyMODINIT_FUNC
PyInit_spam(void)
{
    PyObject *m;
    static void *PySpam_API[PySpam_API_pointers];
    PyObject *c_api_object;

    m = PyModule_Create(&spammodule);
    if (m == NULL)
        return NULL;

    /* Инициализация массива указателей C API */
    PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;

    /* Создание капсулы, содержащей адрес массива указателей API */
    c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);

    if (PyModule_AddObject(m, "_C_API", c_api_object) < 0) {
        Py_XDECREF(c_api_object);
        Py_DECREF(m);
        return NULL;
    }

    return m;
}

Обратите внимание, что PySpam_API объявлен static; иначе массив указателей исчезнет после завершения PyInit_spam()!

Основная работа выполняется в заголовочном файле spammodule.h, который выглядит следующим образом:

#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif

/* Заголовочный файл для spammodule */

/* Функции C API */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)

/* Общее количество указателей C API */
#define PySpam_API_pointers 1


#ifdef SPAM_MODULE
/* Этот раздел используется при компиляции spammodule.c */

static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;

#else
/* Этот раздел используется в модулях, которые используют API spammodule */

static void **PySpam_API;

#define PySpam_System \
 (*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])

/* Возвращает -1 при ошибке, 0 при успехе.
 * PyCapsule_Import установит исключение, если произошла ошибка.
 */
static int
import_spam(void)
{
    PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
    return (PySpam_API != NULL) ? 0 : -1;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */

Всё, что нужно сделать клиентскому модулю для доступа к функции PySpam_System() – это вызвать функцию (точнее, макрос) import_spam() в своей функции инициализации:

PyMODINIT_FUNC
PyInit_client(void)
{
    PyObject *m;

    m = PyModule_Create(&clientmodule);
    if (m == NULL)
        return NULL;
    if (import_spam() < 0)
        return NULL;
    /* дополнительная инициализация может быть выполнена здесь */
    return m;
}

Главный недостаток этого подхода в том, что файл spammodule.h довольно сложен. Однако базовая структура одинакова для каждой экспортируемой функции, поэтому её достаточно изучить один раз.

Наконец, стоит упомянуть, что Capsules предоставляют дополнительную функциональность, которая особенно полезна для выделения и освобождения памяти указателя, хранящегося в Capsule. Подробности описаны в справочном руководстве по Python/C API в разделе Capsules и в реализации Capsules (файлы Include/pycapsule.h и Objects/pycapsule.c в дистрибутиве исходного кода Python).

Сноски

1

Интерфейс для этой функции уже существует в стандартном модуле os – он был выбран в качестве простого и наглядного примера.

2

Метафора «заимствования» ссылки не совсем точна: владелец всё ещё имеет копию ссылки.

3

Проверка того, что счётчик ссылок не меньше 1, не работает – сам счётчик ссылок может находиться в освобождённой памяти и поэтому может быть повторно использован для другого объекта!

4

Эти гарантии не действуют при использовании «старого» стиля соглашения о вызовах – он всё ещё встречается в большом объёме существующего кода.