Введение¶Introduction

Совместимость версий языка¶Language version compatibility

C API Python совместим с версиями C11 и C++11 языков C и C++.

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

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

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

Заголовочные файлы¶Include Files

Все определения функций, типов и макросов, необходимые для использования 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 компилятора. Не помещайте родительские каталоги в путь поиска, а затем используйте #include <pythonX.Y/Python.h>; это нарушит сборку на нескольких платформах, поскольку независимые от платформы заголовочные файлы в prefix включают специфичные для платформы заголовочные файлы из exec_prefix.

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

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

В заголовочных файлах 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).

Объекты, типы и счетчики ссылок¶Objects, Types and Reference Counts

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

Все объекты Python (даже целые числа Python) имеют тип и счетчик ссылок. Тип объекта определяет, что это за объект (например, целое число, список или пользовательская функция; существует гораздо больше типов, как описано в Стандартная иерархия типов). Для каждого из известных типов существует макрос, проверяющий, является ли объект объектом этого типа; например, PyList_Check(a) истинно тогда и только тогда, когда объект, на который указывает 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; /* Не список */
    for (i = 0; i < n; i++) {
        item = PyList_GetItem(list, i); /* Не может завершиться ошибкой */
        if (!PyLong_Check(item)) continue; /* Пропустить нецелые значения */
        value = PyLong_AsLong(item);
        if (value == -1 && PyErr_Occurred())
            /* Целое число слишком велико для C long, выход */
            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; /* Не имеет длины */
    for (i = 0; i < n; i++) {
        item = PySequence_GetItem(sequence, i);
        if (item == NULL)
            return -1; /* Не последовательность или другая ошибка */
        if (PyLong_Check(item)) {
            value = PyLong_AsLong(item);
            Py_DECREF(item);
            if (value == -1 && PyErr_Occurred())
                /* Целое число слишком велико для C long, выход */
                return -1;
            total += value;
        }
        else {
            Py_DECREF(item); /* Отказ от владения ссылкой */
        }
    }
    return total;
}

Исключения¶Exceptions

Программисту на 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 представляют последнее исключение, обрабатываемое оператором 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)
{
    /* Все объекты инициализированы в NULL для Py_XDECREF */
    PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
    int rv = -1; /* Возвращаемое значение инициализировано как -1 (ошибка) */

    item = PyObject_GetItem(dict, key);
    if (item == NULL) {
        /* Обрабатывать только KeyError: */
        if (!PyErr_ExceptionMatches(PyExc_KeyError))
            goto error;

        /* Очистить ошибку и использовать ноль: */
        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; /* Успех */
    /* Продолжить с кодом очистки */

 error:
    /* Код очистки, общий для путей успеха и ошибки */

    /* Используйте Py_XDECREF() для игнорирования NULL-ссылок */
    Py_XDECREF(item);
    Py_XDECREF(const_one);
    Py_XDECREF(incremented_item);

    return rv; /* -1 для ошибки, 0 для успеха */
}

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

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

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

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

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

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

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

Встраивающее приложение может управлять поиском, установив PyConfig.program_name перед вызовом Py_InitializeFromConfig(). Обратите внимание, что PYTHONHOME по-прежнему переопределяет это, а PYTHONPATH всё ещё вставляется в начало стандартного пути.

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

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

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

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

Py_DEBUG¶

Компиляция интерпретатора с определённым макросом Py_DEBUG даёт то, что обычно называют отладочной сборкой Python.

В Unix Py_DEBUG можно включить, добавив --with-pydebug к команде ./configure. При этом также отключается оптимизация компилятора.

В Windows выбор отладочной сборки (например, передача опции -d PCbuild/build.bat) автоматически включает Py_DEBUG. Кроме того, наличие неспецифичного для Python макроса _DEBUG, если он определён компилятором, также неявно включает Py_DEBUG.

Помимо отладки подсчёта ссылок, описанной ниже, выполняются дополнительные проверки. Подробнее см. Python Debug Build.

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

См. Misc/SpecialBuilds.txt в дистрибутиве исходных текстов Python для получения более подробной информации.

Рекомендуемые сторонние инструменты¶Recommended third party tools

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

• Cython

• cffi

• HPy

• nanobind (C++)

• Numba

• pybind11 (C++)

• PyO3 (Rust)

• SWIG

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

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