1. Встраивание Python в другое приложение¶Embedding Python in Another Application

1.1. Встраивание на очень высоком уровне¶Very High Level Embedding

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

#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
{
    wchar_t *program = Py_DecodeLocale(argv[0], NULL);
    if (program == NULL) {
        fprintf(stderr, "Fatal error: cannot decode argv[0]\n");
        exit(1);
    }
    Py_SetProgramName(program);  /* опционально, но рекомендуется */
    Py_Initialize();
    PyRun_SimpleString("from time import time,ctime\n"
                       "print('Today is', ctime(time()))\n");
    if (Py_FinalizeEx() < 0) {
        exit(120);
    }
    PyMem_RawFree(program);
    return 0;
}

Функция Py_SetProgramName() должна вызываться до Py_Initialize(), чтобы сообщить интерпретатору пути к библиотекам времени выполнения Python. Затем инициализируется интерпретатор Python с помощью Py_Initialize(), после чего выполняется жёстко заданный скрипт Python, который выводит дату и время. После этого вызов Py_FinalizeEx() завершает работу интерпретатора, и программа заканчивается. В реальной программе можно получать скрипт Python из другого источника, например, из редактора текста, файла или базы данных. Получение кода Python из файла лучше выполнять с помощью функции PyRun_SimpleFile(), которая избавляет от необходимости выделять память и загружать содержимое файла.

1.2. За пределами очень высокого уровня: обзор¶Beyond Very High Level Embedding: An overview

Высокоуровневый интерфейс позволяет выполнять произвольные фрагменты Python-кода из вашего приложения, но обмен значениями данных – как минимум весьма затруднителен. Если это необходимо, следует использовать низкоуровневые вызовы. Ценой написания большего количества кода на C можно достичь почти всего.

Следует отметить, что расширение Python и встраивание Python – по сути одно и то же действие, несмотря на разные цели. Большинство тем, рассмотренных в предыдущих главах, остаются актуальными. Чтобы показать это, рассмотрим, что на самом деле делает код расширения от Python к C:

1. Преобразование значений данных из Python в C,

2. Вызов функции C с использованием преобразованных значений и

3. Преобразование значений данных из вызова из C в Python.

При встраивании Python код интерфейса делает:

1. Преобразование значений данных из C в Python,

2. Вызов функции интерфейса Python с использованием преобразованных значений и

3. Преобразование значений данных из вызова из Python в C.

Как видите, шаги преобразования данных просто меняются местами для соответствия разному направлению межъязыковой передачи. Единственное отличие – это функция, которую вызывают между двумя преобразованиями данных. При расширении вызывается C-функция, при встраивании – Python-функция.

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

1.3. Чистое встраивание¶Pure Embedding

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

Код для выполнения функции, определённой в скрипте Python:

#define PY_SSIZE_T_CLEAN
#include <Python.h>

int
main(int argc, char *argv[])
{
    PyObject *pName, *pModule, *pFunc;
    PyObject *pArgs, *pValue;
    int i;

    if (argc < 3) {
        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
        return 1;
    }

    Py_Initialize();
    pName = PyUnicode_DecodeFSDefault(argv[1]);
    /* Проверка ошибок pName опущена */

    pModule = PyImport_Import(pName);
    Py_DECREF(pName);

    if (pModule != NULL) {
        pFunc = PyObject_GetAttrString(pModule, argv[2]);
        /* pFunc – новая ссылка */

        if (pFunc && PyCallable_Check(pFunc)) {
            pArgs = PyTuple_New(argc - 3);
            for (i = 0; i < argc - 3; ++i) {
                pValue = PyLong_FromLong(atoi(argv[i + 3]));
                if (!pValue) {
                    Py_DECREF(pArgs);
                    Py_DECREF(pModule);
                    fprintf(stderr, "Cannot convert argument\n");
                    return 1;
                }
                /* Ссылка pValue перехвачена здесь: */
                PyTuple_SetItem(pArgs, i, pValue);
            }
            pValue = PyObject_CallObject(pFunc, pArgs);
            Py_DECREF(pArgs);
            if (pValue != NULL) {
                printf("Result of call: %ld\n", PyLong_AsLong(pValue));
                Py_DECREF(pValue);
            }
            else {
                Py_DECREF(pFunc);
                Py_DECREF(pModule);
                PyErr_Print();
                fprintf(stderr,"Call failed\n");
                return 1;
            }
        }
        else {
            if (PyErr_Occurred())
                PyErr_Print();
            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
        }
        Py_XDECREF(pFunc);
        Py_DECREF(pModule);
    }
    else {
        PyErr_Print();
        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
        return 1;
    }
    if (Py_FinalizeEx() < 0) {
        return 120;
    }
    return 0;
}

Этот код загружает скрипт Python с помощью argv[1] и вызывает функцию с именем из argv[2]. Его целочисленные аргументы – это остальные значения массива argv. Если скомпилировать и собрать эту программу (назовём готовый исполняемый файл call) и использовать её для выполнения скрипта Python, например:

def multiply(a,b):
    print("Will compute", a, "times", b)
    c = 0
    for i in range(0, a):
        c = c + b
    return c

то результат будет следующим:

$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6

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

Py_Initialize();
pName = PyUnicode_DecodeFSDefault(argv[1]);
/* Проверка ошибок pName опущена */
pModule = PyImport_Import(pName);

После инициализации интерпретатора скрипт загружается с помощью PyImport_Import(). Эта функция требует в качестве аргумента строку Python, которая создаётся с помощью подпрограммы преобразования данных PyUnicode_FromString().

pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc – новая ссылка */

if (pFunc && PyCallable_Check(pFunc)) {
    ...
}
Py_XDECREF(pFunc);

После загрузки скрипта искомое имя извлекается с помощью PyObject_GetAttrString(). Если имя существует и возвращённый объект является вызываемым, можно с уверенностью считать, что это функция. Затем программа обычным образом создаёт кортеж аргументов. После этого выполняется вызов функции Python с помощью:

pValue = PyObject_CallObject(pFunc, pArgs);

После возврата из функции pValue либо равен NULL, либо содержит ссылку на возвращаемое значение функции. После проверки значения ссылку необходимо освободить.

1.4. Расширение встроенного Python¶Extending Embedded Python

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

static int numargs=0;

/* Возвращает количество аргументов командной строки приложения */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
    if(!PyArg_ParseTuple(args, ":numargs"))
        return NULL;
    return PyLong_FromLong(numargs);
}

static PyMethodDef EmbMethods[] = {
    {"numargs", emb_numargs, METH_VARARGS,
     "Return the number of arguments received by the process."},
    {NULL, NULL, 0, NULL}
};

static PyModuleDef EmbModule = {
    PyModuleDef_HEAD_INIT, "emb", NULL, -1, EmbMethods,
    NULL, NULL, NULL, NULL
};

static PyObject*
PyInit_emb(void)
{
    return PyModule_Create(&EmbModule);
}

Вставьте приведённый выше код непосредственно перед функцией main(). Также вставьте следующие два оператора перед вызовом Py_Initialize():

numargs = argc;
PyImport_AppendInittab("emb", &PyInit_emb);

Эти две строки инициализируют переменную numargs и делают функцию emb.numargs() доступной для встроенного интерпретатора Python. С такими расширениями скрипт Python может делать следующее:

import emb
print("Number of arguments", emb.numargs())

В реальном приложении методы будут предоставлять Python API приложения.

1.5. Встраивание Python в C++¶Embedding Python in C++

Также возможно встроить Python в программу на C++; точный способ зависит от деталей используемой системы C++; в общем случае нужно написать основную программу на C++ и использовать компилятор C++ для компиляции и сборки программы. Нет необходимости перекомпилировать сам Python с помощью C++.

1.6. Компиляция и компоновка в Unix-подобных системах¶Compiling and Linking under Unix-like systems

Найти правильные флаги для передачи компилятору (и компоновщику) для встраивания интерпретатора Python в приложение – задача не всегда тривиальная, особенно потому что Python должен загружать библиотечные модули, реализованные в виде динамических расширений C (файлы .so), слинкованных с ним.

Чтобы узнать необходимые флаги компилятора и компоновщика, можно выполнить скрипт pythonX.Y-config, который создаётся в процессе установки (также может быть доступен скрипт python3-config). У этого скрипта есть несколько опций, из которых следующие будут непосредственно полезны:

• pythonX.Y-config --cflags выдаст рекомендуемые флаги при компиляции:

  $ /opt/bin/python3.4-config --cflags
  -I/opt/include/python3.4m -I/opt/include/python3.4m -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
  

• pythonX.Y-config --ldflags выдаст рекомендуемые флаги при компоновке:

  $ /opt/bin/python3.4-config --ldflags
  -L/opt/lib/python3.4/config-3.4m -lpthread -ldl -lutil -lm -lpython3.4m -Xlinker -export-dynamic
  

Если эта процедура не работает (она не гарантирует работу на всех Unix-подобных платформах; однако мы приветствуем сообщения об ошибках), то придётся прочитать документацию вашей системы о динамической компоновке и/или изучить файл Makefile Python (используйте sysconfig.get_makefile_filename(), чтобы найти его расположение) и параметры компиляции. В этом случае модуль sysconfig – полезный инструмент для программного извлечения значений конфигурации, которые нужно скомбинировать. Например:

>>> import sysconfig
>>> sysconfig.get_config_var('LIBS')
'-lpthread -ldl  -lutil'
>>> sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'