Введение

Совместимость с версиями языков

C API Python совместим с версиями C и C++, соответствующими стандартам C11 и C++11.

Это нижняя граница: C API не требует возможностей более поздних версий C/C++. Вам не нужно включать «режим c11» компилятора.

Стандарты кодирования

Если вы пишете код на C для включения в CPython, вы обязаны следовать рекомендациям и стандартам, определённым в PEP 7. Эти рекомендации применяются независимо от версии Python, в которую вы вносите вклад. Соблюдать эти соглашения необязательно для собственных сторонних модулей расширения, если только вы не планируете в дальнейшем внести их в Python.

Файлы заголовков

Все определения функций, типов и макросов, необходимые для использования Python/C API, включаются в код следующей строкой:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

Это подразумевает включение следующих стандартных заголовков: <stdio.h>, <string.h>, <errno.h>, <limits.h>, <assert.h> и <stdlib.h> (если доступны).

Все видимые пользователю имена, определённые в Python.h (за исключением имён, определённых во включённых стандартных заголовках), имеют префикс Py или _Py. Имена, начинающиеся с _Py, предназначены для внутреннего использования реализацией Python и не должны использоваться авторами расширений. Имена членов структур не имеют зарезервированного префикса.

Файлы заголовков обычно устанавливаются вместе с Python. В Unix они расположены в каталогах prefix/include/pythonversion/ и exec_prefix/include/pythonversion/, где prefix и exec_prefix задаются соответствующими параметрами скрипта configure Python, а version — это '%d.%d' % sys.version_info[:2]. В Windows заголовки устанавливаются в prefix/include, где prefix — каталог установки, указанный в программе установки.

Чтобы включить заголовки, добавьте оба каталога (если они различаются) в путь поиска подключаемых файлов компилятора. Не добавляйте в путь поиска родительские каталоги, а затем не используйте #include <pythonX.Y/Python.h>; это приведёт к ошибкам при сборке для нескольких платформ, поскольку независимые от платформы заголовки в prefix включают заголовки, специфичные для платформы, из exec_prefix.

Пользователям C++ следует учитывать, что, хотя API полностью определён с использованием C, в файлах заголовков точки входа правильно объявлены как extern "C". Поэтому для использования API из C++ не требуется никаких специальных действий.

Полезные макросы

В файлах заголовков Python определено несколько полезных макросов. Многие из них определены рядом с местом, где используются (например, Py_RETURN_NONE, PyMODINIT_FUNC). Другие макросы общего назначения определены здесь. Этот список не обязательно является полным.

Py_CAN_START_THREADS

Если этот макрос определён, текущая система может запускать потоки.

В настоящее время все системы, поддерживаемые CPython (согласно PEP 11), за исключением некоторых платформ WebAssembly, поддерживают запуск потоков.

Добавлен в версии 3.13.

Py_GETENV(s)

Аналог getenv(s), но возвращает NULL, если в командной строке был передан параметр -E (см. PyConfig.use_environment).

Объекты, типы и счетчики ссылок

Большинство функций Python/C API имеют один или несколько аргументов, а также возвращаемое значение типа PyObject*. Этот тип представляет собой указатель на непрозрачный тип данных, представляющий произвольный объект Python. Поскольку в большинстве ситуаций язык Python одинаково обрабатывает все типы объектов Python (например, при присваивании, применении правил области видимости и передаче аргументов), вполне естественно, что они представлены одним типом C. Почти все объекты Python находятся в куче: вы никогда не объявляете автоматическую или статическую переменную типа PyObject, можно объявлять только переменные-указатели типа PyObject*. Единственное исключение — объекты типов; поскольку их нельзя освобождать, обычно это статические объекты PyTypeObject.

У всех объектов Python (даже у целых чисел Python) есть тип и счетчик ссылок. Тип объекта определяет, что это за объект (например, целое число, список или пользовательская функция; существует множество других типов, описанных в разделе Стандартная иерархия типов). Для каждого из известных типов существует макрос, проверяющий, относится ли объект к этому типу; например, PyList_Check(a) имеет значение true тогда и только тогда, когда объект, на который указывает a, является списком Python.

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));

PyObject *tuple, *list;

tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");

int
set_all(PyObject *target, PyObject *item)
{
    Py_ssize_t i, n;

    n = PyObject_Length(target);
    if (n < 0)
        return -1;
    for (i = 0; i < n; i++) {
        PyObject *index = PyLong_FromSsize_t(i);
        if (!index)
            return -1;
        if (PyObject_SetItem(target, index, item) < 0) {
            Py_DECREF(index);
            return -1;
        }
        Py_DECREF(index);
    }
    return 0;
}

long
sum_list(PyObject *list)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;

    n = PyList_Size(list);
    if (n < 0)
        return -1; /* Not a list */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* Can't fail */
        if (!PyLong_Check(item)) continue; /* Skip non-integers */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Integer too big to fit in a C long, bail out */
            return -1;
        total += value;
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    Py_ssize_t i, n;
    long total = 0, value;
    PyObject *item;
    n = PySequence_Length(sequence);
    if (n < 0)
        return -1; /* Has no length */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Not a sequence, or other failure */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Integer too big to fit in a C long, bail out */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* Discard reference ownership */
        }
    }
    return total;
}

Исключения

Программисту на Python нужно работать с исключениями только в том случае, если требуется специальная обработка ошибок; необработанные исключения автоматически передаются вызывающей функции, затем вызывающей функции вызывающей функции и так далее, пока не достигнут интерпретатора верхнего уровня, где они сообщаются пользователю вместе с трассировкой стека.

Однако программистам на C всегда необходимо явно проверять наличие ошибок. Все функции Python/C API могут возбуждать исключения, если в документации конкретной функции явно не указано иное. Как правило, при возникновении ошибки функция устанавливает исключение, освобождает все принадлежащие ей ссылки на объекты и возвращает индикатор ошибки. Если не указано иное, этот индикатор — либо NULL, либо -1, в зависимости от типа возвращаемого функцией значения. Некоторые функции возвращают логический результат true/false, где false указывает на ошибку. Очень немногие функции не возвращают явный индикатор ошибки или имеют неоднозначное возвращаемое значение; для проверки ошибки в них требуется явно вызвать PyErr_Occurred(). Эти исключения всегда явно описаны в документации.

Состояние исключения хранится в потоке (в однопоточной программе это эквивалентно хранению в глобальной области). Поток может находиться в одном из двух состояний: исключение произошло или не произошло. Для проверки этого можно использовать функцию PyErr_Occurred(): если исключение произошло, она возвращает заимствованную ссылку на объект типа исключения, а в противном случае — NULL. Существует несколько функций для установки состояния исключения: PyErr_SetString() — наиболее распространенная (хотя и не самая универсальная) функция для установки состояния исключения, а PyErr_Clear() очищает его.

Полное состояние исключения состоит из трех объектов (каждый из которых может быть NULL): типа исключения, соответствующего значения исключения и трассировки стека. Их значения совпадают со значениями результата Python для sys.exc_info(), однако это не одно и то же: объекты Python представляют последнее исключение, обрабатываемое оператором Python try … except, тогда как состояние исключения на уровне C существует только во время передачи исключения между функциями C, пока оно не достигнет главного цикла интерпретатора байт-кода Python, который отвечает за передачу его в sys.exc_info() и подобные объекты.

Обратите внимание, что начиная с Python 1.5 предпочтительным и потокобезопасным способом доступа к состоянию исключения из кода Python является вызов функции sys.exc_info(), возвращающей состояние исключения текущего потока для кода Python. Кроме того, семантика обоих способов доступа к состоянию исключения изменилась: функция, перехватывающая исключение, сохраняет и восстанавливает состояние исключения своего потока, чтобы сохранить состояние исключения вызывающей функции. Это предотвращает распространенные ошибки в коде обработки исключений, вызванные тем, что безобидно выглядящая функция перезаписывает обрабатываемое исключение; кроме того, это уменьшает часто нежелательное продление времени жизни объектов, на которые ссылаются кадры стека в трассировке.

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

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

def incr_item(dict, key):
    try:
        item = dict[key]
    except KeyError:
        item = 0
    dict[key] = item + 1

А вот соответствующий код на C во всей красе:

int
incr_item(PyObject *dict, PyObject *key)
{
    /* Objects all initialized to NULL for Py_XDECREF */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* Return value initialized to -1 (failure) */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) {
        /* Handle KeyError only: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* Clear the error and use zero: */
        PyErr_Clear();
        item = PyLong_FromLong(0L);
        if (item == NULL)
            goto error;
    }
    const_one = PyLong_FromLong(1L);
    if (const_one == NULL)
        goto error;

    incremented_item = PyNumber_Add(item, const_one);
    if (incremented_item == NULL)
        goto error;

    if (PyObject_SetItem(dict, key, incremented_item) < 0)
        goto error;
    rv = 0; /* Success */
    /* Continue with cleanup code */

 error:
    /* Cleanup code, shared by success and failure path */

    /* Use Py_XDECREF() to ignore NULL references */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* -1 for error, 0 for success */
}

Этот пример демонстрирует одобренный способ использования оператора goto в C! В нем показано применение PyErr_ExceptionMatches() и PyErr_Clear() для обработки определенных исключений, а также Py_XDECREF() для освобождения принадлежащих функции ссылок, которые могут быть NULL (обратите внимание на 'X' в имени; Py_DECREF() привел бы к сбою при обработке ссылки со значением NULL). Для правильной работы важно инициализировать переменные, используемые для хранения принадлежащих функции ссылок, значением NULL; аналогично предполагаемое возвращаемое значение инициализируется значением -1 (ошибка) и получает значение успеха только после успешного выполнения последнего вызова.

Встраивание Python

Единственная важная задача, о которой должны заботиться только разработчики встраиваемых приложений (в отличие от авторов расширений) для интерпретатора Python, — инициализация и, возможно, завершение работы интерпретатора. Большинство функций интерпретатора можно использовать только после его инициализации.

Основная функция инициализации — Py_Initialize(). Она инициализирует таблицу загруженных модулей и создает основные модули builtins, __main__ и sys. Она также инициализирует путь поиска модулей (sys.path).

Py_Initialize() не задает «список аргументов скрипта» (sys.argv). Если эта переменная нужна коду Python, который будет выполнен позднее, необходимо задать PyConfig.argv и PyConfig.parse_argv: см. раздел Конфигурация инициализации Python.

В большинстве систем (в частности, в Unix и Windows, хотя детали немного различаются) функция Py_Initialize() вычисляет путь поиска модулей, исходя из предположения о местонахождении стандартного исполняемого файла интерпретатора Python и фиксированном расположении библиотеки Python относительно него. В частности, она ищет каталог с именем lib/pythonX.Y относительно родительского каталога, в котором в пути поиска команд оболочки найден исполняемый файл с именем python (переменная окружения PATH).

Например, если исполняемый файл Python найден в /usr/local/bin/python, предполагается, что библиотеки находятся в /usr/local/lib/pythonX.Y. (Фактически этот конкретный путь также является резервным расположением, используемым, если в PATH не найден исполняемый файл с именем python.) Пользователь может переопределить это поведение, задав переменную окружения PYTHONHOME, или добавить каталоги перед стандартным путем, задав PYTHONPATH.

Встраиваемое приложение может управлять поиском, задав PyConfig.program_name до вызова Py_InitializeFromConfig(). Обратите внимание, что PYTHONHOME по-прежнему переопределяет это значение, а PYTHONPATH по-прежнему добавляется перед стандартным путем. Приложение, которому необходим полный контроль, должно предоставить собственную реализацию функций Py_GetPath(), Py_GetPrefix(), Py_GetExecPrefix() и Py_GetProgramFullPath() (все они определены в Modules/getpath.c).

Иногда требуется «деинициализировать» Python. Например, приложению может понадобиться начать работу заново (повторно вызвать Py_Initialize()) или оно больше не использует Python и хочет освободить память, выделенную Python. Для этого можно вызвать Py_FinalizeEx(). Функция Py_IsInitialized() возвращает true, если Python в данный момент инициализирован. Более подробная информация об этих функциях приведена в следующей главе. Обратите внимание, что Py_FinalizeEx() не освобождает всю память, выделенную интерпретатором Python; например, память, выделенная модулями расширения, пока освободить невозможно.

Отладочные сборки

Python можно собрать с несколькими макросами, включающими дополнительные проверки интерпретатора и модулей расширения. Эти проверки создают значительную нагрузку на время выполнения, поэтому по умолчанию они отключены.

Полный список различных типов отладочных сборок приведен в файле Misc/SpecialBuilds.txt из дистрибутива исходного кода Python. Доступны сборки, поддерживающие трассировку счетчиков ссылок, отладку распределителя памяти и низкоуровневое профилирование основного цикла интерпретатора. В оставшейся части этого раздела описаны только наиболее часто используемые сборки.

Py_DEBUG

Компиляция интерпретатора с определенным макросом Py_DEBUG создает то, что обычно называют отладочной сборкой Python. В сборке для Unix Py_DEBUG включается добавлением --with-pydebug к команде ./configure. Его наличие также подразумевается при наличии не специфичного для Python макроса _DEBUG. Если в сборке для Unix включен Py_DEBUG, оптимизация компилятора отключается.

Помимо описанной ниже отладки счетчиков ссылок выполняются дополнительные проверки; см. раздел Отладочная сборка Python.

Определение Py_TRACE_REFS включает трассировку ссылок (см. параметр configure --with-trace-refs option). При его определении для активных объектов поддерживается циклический двусвязный список: в каждый PyObject добавляются два дополнительных поля. Также отслеживается общее количество выделений памяти. При выходе печатаются все существующие ссылки. (В интерактивном режиме это происходит после каждого оператора, выполненного интерпретатором.)

Более подробную информацию см. в Misc/SpecialBuilds.txt из дистрибутива исходного кода Python.

Рекомендуемые сторонние инструменты

Следующие сторонние инструменты предлагают как простые, так и более сложные способы создания расширений на C, C++ и Rust для Python:

• Cython
• cffi
• HPy
• nanobind (C++)
• Numba
• pybind11 (C++)
• PyO3 (Rust)
• SWIG

Использование подобных инструментов помогает избежать написания кода, жестко привязанного к конкретной версии CPython, ошибок при подсчете ссылок и позволяет сосредоточиться на собственном коде, а не на работе с API CPython. Как правило, для поддержки новых версий Python достаточно обновить инструмент, и ваш код зачастую автоматически начнет использовать более новые и эффективные API. Некоторые инструменты также позволяют собирать код для других реализаций Python из одного набора исходных файлов.

Эти проекты не поддерживаются теми же людьми, которые сопровождают Python, поэтому о проблемах следует сообщать непосредственно в соответствующие проекты. Не забывайте проверять, что проект по-прежнему сопровождается и поддерживается, поскольку приведенный выше список может устареть.