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.)

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

#include <Python.h>

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

All user-visible symbols defined by Python.h have a prefix of Py or PY, except those defined in standard header files. For convenience, and since they are used extensively by the Python interpreter, "Python.h" includes a few standard header files: <stdio.h>, <string.h>, <errno.h>, and <stdlib.h>. If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly.

Следующее, что мы добавим в файл модуля, – это 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 Py_BuildValue("i", sts);
}

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

Аргумент self используется только в том случае, когда C-функция реализует встроенный метод, а не функцию. В примере self всегда будет указателем NULL, поскольку мы определяем функцию, а не метод. (Это сделано для того, чтобы интерпретатору не приходилось разбираться с двумя разными типами C-функций.)

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

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

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

Важное соглашение, действующее во всём интерпретаторе Python, состоит в следующем: когда функция завершается ошибкой, она должна установить условие исключения и вернуть значение ошибки (обычно указатель NULL). Исключения хранятся в статической глобальной переменной внутри интерпретатора; если эта переменная равна NULL, исключения не произошло. Вторая глобальная переменная хранит «связанное значение» исключения (второй аргумент raise). Третья переменная содержит стек вызовов (traceback) на случай, если ошибка возникла в коде Python. Эти три переменные являются C-эквивалентами переменных Python sys.exc_type, sys.exc_value и sys.exc_traceback (см. раздел о модуле sys в справочнике по библиотеке Python). Важно знать о них, чтобы понимать, как передаются ошибки.

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() и сам вернуть признак ошибки. Все функции создания объектов (например, PyInt_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;

и инициализируйте его в функции инициализации модуля (initspam()) объектом исключения (пока пропуская проверку ошибок):

PyMODINIT_FUNC
initspam(void)
{
    PyObject *m;

    m = Py_InitModule("spam", SpamMethods);
    if (m == NULL)
        return;

    SpamError = PyErr_NewException("spam.error", NULL, NULL);
    Py_INCREF(SpamError);
    PyModule_AddObject(m, "error", SpamError);
}

Обратите внимание, что в 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. Это делается с помощью функции Py_BuildValue(), которая является чем-то вроде обратной к PyArg_ParseTuple(): она принимает строку формата и произвольное количество значений C и возвращает новый объект Python. Более подробная информация о Py_BuildValue() приведена далее.

return Py_BuildValue("i", 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() для разбора аргументов такой функции.

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

PyMODINIT_FUNC
initspam(void)
{
    (void) Py_InitModule("spam", SpamMethods);
}

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

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

При встраивании Python функция initspam() не вызывается автоматически, если только нет записи в таблице _PyImport_Inittab. Самый простой способ справиться с этим – статически инициализировать ваши статически скомпонованные модули, напрямую вызвав initspam() после вызова Py_Initialize():

int
main(int argc, char *argv[])
{
    /* Передать argv[0] интерпретатору Python */
    Py_SetProgramName(argv[0]);

    /* Инициализировать интерпретатор Python. Обязательно. */
    Py_Initialize();

    /* Добавить статический модуль */
    initspam();

Пример можно найти в файле Demo/embed/demo.c в дистрибутиве исходного кода Python.

Более существенный пример модуля включён в дистрибутив исходного кода Python как Modules/xxmodule.c. Этот файл может использоваться как шаблон или просто прочитан в качестве примера. Скрипт modulator.py, входящий в дистрибутив исходного кода или установку Windows, предоставляет простой графический интерфейс для объявления функций и объектов, которые должен реализовать модуль, и может сгенерировать шаблон для заполнения. Скрипт находится в каталоге Tools/modulator/; см. файл README там для получения дополнительной информации.

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

Прежде чем вы сможете использовать своё новое расширение, нужно сделать ещё две вещи: скомпилировать и скомпоновать его с системой Python. Если вы используете динамическую загрузку, детали могут зависеть от стиля динамической загрузки, применяемого в вашей системе; обратитесь к главам о сборке модулей расширения (глава Building C and C++ Extensions with distutils) и дополнительной информации, относящейся только к сборке в Windows (глава Building C and C++ Extensions on 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; это описано в разделе The Module’s Method Table and Initialization Function. Функция PyArg_ParseTuple() и её аргументы описаны в разделе Extracting Parameters in Extension Functions.

Макросы Py_XINCREF() и Py_XDECREF() увеличивают/уменьшают счётчик ссылок объекта и безопасны при наличии указателей NULL (но обратите внимание, что temp в данном контексте не будет NULL). Дополнительная информация о них – в разделе Reference Counts.

Затем, когда наступает время вызвать функцию, вызывается 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() является «новым»: это либо совершенно новый объект, либо существующий объект, чей счётчик ссылок был увеличен. Поэтому, если вы не хотите сохранять его в глобальной переменной, вам следует каким-то образом 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, char *format, ...);

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

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

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

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

int ok;
int i, j;
long k, l;
const char *s;
int 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,
                                char *format, char *kwlist[], ...);

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

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

#include "Python.h"

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
    int voltage;
    char *state = "a stiff";
    char *action = "voom";
    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_INCREF(Py_None);

    return Py_None;
}

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

void
initkeywdarg(void)
{
  /* Создать модуль и добавить функции */
  Py_InitModule("keywdarg", keywdarg_methods);
}

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

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

PyObject *Py_BuildValue(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("ss", "hello", "world")    ('hello', 'world')
Py_BuildValue("s#", "hello", 4)          '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 использует традиционную реализацию подсчёта ссылок, он также предлагает детектор циклов, который обнаруживает циклические ссылки. Это позволяет приложениям не беспокоиться о создании прямых или косвенных циклических ссылок; они являются слабым местом сборки мусора, реализованной только с помощью подсчёта ссылок. Циклические ссылки состоят из объектов, которые содержат (возможно, косвенные) ссылки на самих себя, так что каждый объект в цикле имеет ненулевой счётчик ссылок. Типичные реализации подсчёта ссылок не могут освободить память, принадлежащую объектам в циклической ссылке или на которые есть ссылки из объектов в цикле, даже если на сам цикл больше нет ссылок.

Детектор циклов способен обнаруживать сборные циклы и может перерабатывать их, пока в Python не реализованы финализаторы (методы __del__()). Если такие финализаторы есть, детектор показывает циклы через модуль gc (в частности, переменная garbage в этом модуле). Модуль gc также предоставляет способ запуска детектора (функция collect()), а также интерфейсы настройки и возможность отключения детектора во время выполнения. Детектор циклов считается опциональным компонентом; хотя он включён по умолчанию, его можно отключить при сборке, используя опцию --without-cycle-gc скрипта configure на платформах Unix (включая Mac OS X), или удалив определение WITH_CYCLE_GC в заголовочном файле pyconfig.h на других платформах. Если детектор циклов отключён таким образом, модуль gc будет недоступен.

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

    PyList_SetItem(list, 1, PyInt_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, PyInt_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) или предлагают выбор различных стратегий (большинство Unices). И даже если символы глобально видимы, модуль, функции которого требуется вызвать, возможно, ещё не загружен!

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

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

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

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

Экспортирующий модуль представляет собой модификацию модуля spam из раздела A Simple Example. Функция 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 Py_BuildValue("i", sts);
}

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

#include "Python.h"

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

#define SPAM_MODULE
#include "spammodule.h"

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

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

    m = Py_InitModule("spam", SpamMethods);
    if (m == NULL)
        return;

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

    /* Создать CObject, содержащий адрес массива указателей API */
    c_api_object = PyCObject_FromVoidPtr((void *)PySpam_API, NULL);

    if (c_api_object != NULL)
        PyModule_AddObject(m, "_C_API", c_api_object);
}

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

Основная часть работы выполняется в заголовочном файле 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 при успехе. */
static int
import_spam(void)
{
    PyObject *c_api_object;
    PyObject *module;

    module = PyImport_ImportModule("spam");
    if (module == NULL)
        return -1;

    c_api_object = PyObject_GetAttrString(module, "_C_API");
    if (c_api_object == NULL) {
        Py_DECREF(module);
        return -1;
    }
    if (PyCObject_Check(c_api_object))
        PySpam_API = (void **)PyCObject_AsVoidPtr(c_api_object);

    Py_DECREF(c_api_object);
    Py_DECREF(module);
    return 0;
}

#endif

#ifdef __cplusplus
}
#endif

#endif /* !defined(Py_SPAMMODULE_H) */

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

PyMODINIT_FUNC
initclient(void)
{
    PyObject *m;

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

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

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

Сноски