Введение¶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 из Python, а версия равна sys.version[:3]. В Windows заголовочные файлы устанавливаются в prefix/include, где prefix – это каталог установки, указанный программе установки.

Чтобы включить заголовочные файлы, поместите оба каталога (если они различаются) в путь поиска заголовочных файлов компилятора. Не помещайте родительские каталоги в путь поиска, а затем используйте #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.

All Python objects (even Python integers) have a type and a reference count. An object’s type determines what kind of object it is (e.g., an integer, a list, or a user-defined function; there are many more as explained in The standard type hierarchy). For each of the well-known types there is a macro to check whether an object is of that type; for instance, PyList_Check(a) is true if (and only if) the object pointed to by a is a Python list.

PyObject *t;

t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_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)
{
    int i, n;

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

long
sum_list(PyObject *list)
{
    int i, n;
    long total = 0;
    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; /* Пропустить нецелые значения */
        total += PyLong_AsLong(item);
    }
    return total;
}

long
sum_sequence(PyObject *sequence)
{
    int i, n;
    long total = 0;
    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))
            total += PyLong_AsLong(item);
        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): тип исключения, соответствующее значение исключения и traceback. Они имеют тот же смысл, что и результат Python sys.exc_info(); однако это не одно и то же: объекты Python представляют последнее исключение, обрабатываемое оператором Python try ... except, в то время как состояние исключения на уровне C существует только пока исключение передаётся между функциями C, пока не достигнет главного цикла интерпретатора байт-кода Python, который заботится о его передаче в sys.exc_info() и подобные функции.

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

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

Простой пример обнаружения исключений и их передачи приведен выше в примере 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_SetArgv(argc, argv) после вызова 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_Finalize(). Функция Py_IsInitialized() возвращает true, если Python находится в инициализированном состоянии. Дополнительная информация об этих функциях приведена в следующей главе. Обратите внимание, что Py_Finalize() не освобождает всю память, выделенную интерпретатором Python, например, память, выделенная модулями расширения, в настоящее время не может быть освобождена.

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

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

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

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

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

• Дополнительные проверки добавлены в распределитель объектов.
• Дополнительные проверки добавлены в синтаксический анализатор и компилятор.
• Проверяются понижающие приведения от широких типов к узким на предмет потери информации.
• В реализации словаря и множества добавлено несколько утверждений. Кроме того, объект множества получает метод test_c_api().
• Проверки корректности входных аргументов добавлены при создании фрейма.
• Память для целых чисел инициализируется известным недопустимым шаблоном для выявления ссылок на неинициализированные разряды.
• Низкоуровневая трассировка и дополнительные проверки исключений добавлены в виртуальную машину времени выполнения.
• Дополнительные проверки добавлены в реализацию области памяти (arena).
• Дополнительная отладка добавлена в модуль thread.

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

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

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