Введение¶Introduction

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

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

#include "Python.h"

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

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

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

Заголовочные файлы обычно устанавливаются вместе с Python. В Unix они находятся в каталогах prefix/include/pythonversion/ и exec_prefix/include/pythonversion/, где prefix и exec_prefix определяются соответствующими параметрами сценария configure, а 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++.

Объекты, типы и счетчики ссылок¶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 представляют последнее исключение, обрабатываемое оператором 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, который будет выполняться позже, её необходимо явно установить с помощью вызова PySys_SetArgvEx(argc, argv, updatepath) после вызова Py_Initialize().

В большинстве систем (в частности, в 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.

Встраивающее приложение может управлять поиском, вызвав Py_SetProgramName(file) перед вызовом Py_Initialize(). Обратите внимание, что 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, например, память, выделенная модулями расширения, в настоящее время не может быть освобождена.

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

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

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

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

В дополнение к отладке счётчика ссылок, описанной ниже, выполняются следующие дополнительные проверки:

• Дополнительные проверки добавлены в распределитель объектов.

• Дополнительные проверки добавлены в синтаксический анализатор и компилятор.

• Проверяются понижающие приведения от широких типов к узким на предмет потери информации.

• В реализации словаря и множества добавлен ряд утверждений. Кроме того, объект множества получает метод test_c_api().

• Проверки корректности входных аргументов добавлены при создании фрейма.

• Память для целых чисел инициализируется известным недопустимым шаблоном для выявления ссылок на неинициализированные разряды.

• Низкоуровневая трассировка и дополнительные проверки исключений добавлены в виртуальную машину времени выполнения.

• Дополнительные проверки добавлены в реализацию области памяти (arena).

• Дополнительная отладка добавлена в модуль thread.

Могут быть и другие проверки, не упомянутые здесь.

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

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